Spring - User contributions [en]

Lua UnsyncedRead

2010-11-26T11:08:37Z

Pithikos: /* Unsynced Read */

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

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z
'''Spring.TraceScreenRay'''
( number mouseX, number mouseY [, boolean onlyCoords [, boolean useMinimap] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean extrapolated ] ) -> nil | boolean
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== UI ==

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "path" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> 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.GetActiveCmdDesc'''
( number index ) -> nil | {
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.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''
( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed
'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number] = boolean,
...
}
'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | { [1] = {[string actionCmd] = string actionExtra}, ... }
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit

== Time ==
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.DiffTimers'''
( timer cur, timer ago) -> number seconds

[[category: Lua]]

Lua SyncedRead

2010-11-26T11:06:55Z

Pithikos: /* Game */

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

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

== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-25T19:21:32Z

Pithikos: /* Game */

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

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation regarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for XOR. So if you see A | B before the output sign("->") then it means that it gets either A or B as argument. If you see this after the output sign then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B before the output sign means that the function gets A and B as arguments. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicates the type of the argument or the return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
 Using functions 
Example with function that doesn't take arguments and returns a value: variable1=Spring.IsGodModeEnabled() Example with function that takes two numbers as arguments and returns a value: variable1=Spring.GetUnitRulesParam(132, 2) Example with function that returns two values: x, z=Spring.GetVectorFromHeading(23) 

=== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T10:30:45Z

Pithikos: /* Synced Read */

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

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for XOR. So if you see A | B before the output sign("->") then it means that it gets either A or B as argument. If you see this after the output sign then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B before the output sign means that the function gets A and B as arguments. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicates the type of the argument or the return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
 Using functions 
Example with function that doesn't take arguments and returns a value: variable1=Spring.IsGodModeEnabled() Example with function that takes two numbers as arguments and returns a value: variable1=Spring.GetUnitRulesParam(132, 2) Example with function that returns two values: x, z=Spring.GetVectorFromHeading(23) 

=== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T02:21:05Z

Pithikos: /* Rules */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 
 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=1px style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>
 
 
== GameStates ==

<table class="functionsDefined" width=100% border="1" style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>
 
 
== Rules ==
These 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!) 
 

<table class="functionsDefined" width=150% border=1px style="border:0px solid orange;">

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>
{
[key1]=string1,
[key2]=string2,
...
}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>
{
ruleIndex1 = {ruleName1 = number1},
ruleIndex2 = {ruleName2 = number2},
...
} | nil </td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>
{
ruleIndex1={ruleName1=number1},
ruleIndex2={ruleName2=number2},
...
} | nil</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>
{
ruleIndex1={ruleName1=number1},
ruleIndex2={ruleName2=number2},
...
} | nil </td>
</tr>

</table>
 
 

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T02:07:04Z

Pithikos: /* Synced Read */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 
 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=1px style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>
 
 
== GameStates ==

<table class="functionsDefined" width=100% border="1" style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>
 
 
== Rules ==
These 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!) 
 

<table class="functionsDefined" width=150% border=1px style="border:0px solid orange;">

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1]=string1, [key2]=string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>
 
 
== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T02:02:04Z

Pithikos: /* Rules */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border="1" style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

== Rules ==
These 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!) 
 

<table class="functionsDefined" width=150% border=1px style="border:0px solid orange;">

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1]=string1, [key2]=string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:57:21Z

Pithikos: /* Rules */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border="1" style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

== Rules ==
These 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!) 
 

<table class="functionsDefined" width=150% border=1px style="border:0px solid orange;">

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1] = string1, [key2] = string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:50:17Z

Pithikos: /* Rules */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border="1" style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=150% border=1px style="border:0px solid orange;">

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1] = string1, [key2] = string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:49:50Z

Pithikos: /* GameStates */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border="1" style="border:0px solid orange;">

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=150% border=1px>

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1] = string1, [key2] = string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:45:55Z

Pithikos: /* GameStates */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border=1px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=150% border=1px>

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1] = string1, [key2] = string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:43:37Z

Pithikos: /* Rules */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=150% border=1px>

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1] = string1, [key2] = string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:40:39Z

Pithikos: /* Rules */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<th style="border-bottom:1px solid grey;">Function name</th>
<th style="border-bottom:1px solid grey;">Description</th>
<th style="border-bottom:1px solid grey;">Input</th>
<th style="border-bottom:1px solid grey;">Output</th>
</tr>

<tr>
<td rowspan="2">Spring.GetRulesInfoMap</td>
<td rowspan="2">REMOVED in 0.82!</td>
<td>nil</td>
<td>{ [key1] = string1, [key2] = string2, ..}</td>
</tr>
<tr>
<td>string key</td>
<td>string</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1]=number1}, [ruleIndex2]= {[ruleName2] = number2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number1}, [ruleIndex2] = {[ruleName2] = number2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:27:06Z

Pithikos: /* Game */

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

= Synced Read =

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
Using functions

Example with function that doesn't take arguments and returns a value: 
variable1=Spring.IsGodModeEnabled() 
 
Example with function that takes two numbers as arguments and returns a value: 
variable1=Spring.GetUnitRulesParam(132, 2) 
 
Example with function that returns two values: 
x, z=Spring.GetVectorFromHeading(23) 

== Special TeamID Variables ==
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

== GameStates ==

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.GetRulesInfoMap</td><td>REMOVED in 0.82!</td><td>nil string "key" </td><td>{ [key1] = string value1, [key2] = string value2, ... } string value
</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

</table>

== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:13:44Z

Pithikos: /* Game */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 

=== Special TeamID Variables ===
(those special TeamIDs are not supported by all functions) 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

</table>

=== GameStates ===

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.GetRulesInfoMap</td><td>REMOVED in 0.82!</td><td>nil string "key" </td><td>{ [key1] = string value1, [key2] = string value2, ... } string value
</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

</table>

=== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:12:28Z

Pithikos: /* Special TeamID Variables */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 

=== Special TeamID Variables ===
(those special TeamIDs are not supported by all functions) 

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Variable name</td>
<td style="border-bottom:1px solid grey;">Description</td>
</tr>

<tr>
<td>Spring.ALL_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.MY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ALLY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

<tr>
<td>Spring.ENEMY_UNITS</td>
<td></td>
</tr>

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

</table>

=== GameStates ===

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.GetRulesInfoMap</td><td>REMOVED in 0.82!</td><td>nil string "key" </td><td>{ [key1] = string value1, [key2] = string value2, ... } string value
</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

</table>

=== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-23T01:08:35Z

Pithikos: /* Game */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Some conventions found in the following tables: 
*| stands for XOR. So if you see A | B as input then it means that it gets either A or B as argument. If you see this as output then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B as input means that the function gets A and B as arguments. As output it means that the function returns values A and B. 
*number, string, nil, boolean just indicate the type of the argument or the type of the returning value. So if it stands number A, string B as input then it means that the first argument must be a number and the second argument must be a string. In the output context it means that the first returned value A is a number and the second returned value B is a string. 
*[] stands for "optional". If you see number A, [string B] as input then it means that you MUST pass argument A and if you wish even a second argument(the optional one). 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.GetRulesInfoMap</td><td>REMOVED in 0.82!</td><td>nil string "key" </td><td>{ [key1] = string value1, [key2] = string value2, ... } string value
</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

</table>

=== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-22T23:59:16Z

Pithikos: /* Rules */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for XOR. So if you see A | B before the output sign("->") then it means that it gets either A or B as argument. If you see this after the output sign then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B before the output sign means that the function gets A and B as arguments. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicates the type of the argument or the return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.GetRulesInfoMap</td><td>REMOVED in 0.82!</td><td>nil string "key" </td><td>{ [key1] = string value1, [key2] = string value2, ... } string value
</td>
</tr>

<tr>
<td>Spring.GetGameRulesParam</td>
<td></td>
<td>number ruleIndex | string ruleName</td>
<td>number value</td>
</tr>

<tr>
<td>Spring.GetGameRulesParams</td>
<td></td>
<td></td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParam</td>
<td></td>
<td>number teamID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetTeamRulesParams</td>
<td></td>
<td>number teamID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID, number index | string ruleName</td>
<td>nil | number value</td>
</tr>

<tr>
<td>Spring.GetUnitRulesParam</td>
<td></td>
<td>number unitID</td>
<td>nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }</td>
</tr>

</table>

=== 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-22T23:26:59Z

Pithikos: /* Game */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for XOR. So if you see A | B before the output sign("->") then it means that it gets either A or B as argument. If you see this after the output sign then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B before the output sign means that the function gets A and B as arguments. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicates the type of the argument or the return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 

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

<table class="functionsDefined" width=100% border=0px>

<tr>
<td style="border-bottom:1px solid grey;">Function name</td><td style="border-bottom:1px solid grey;">Description</td><td style="border-bottom:1px solid grey;">Input</td><td style="border-bottom:1px solid grey;">Output</td>
</tr>

<tr>
<td>Spring.IsGodModeEnabled</td><td>Check if invincibility mode is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsCheatingEnabled</td><td>Check if cheating is enabled</td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsDevLuaEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.IsEditDefsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.AreHelperAIsEnabled</td><td></td><td></td><td>boolean</td>
</tr>

<tr>
<td>Spring.FixedAllies</td><td></td><td></td><td>nil | boolean</td>
</tr>

<tr>
<td>Spring.IsGameOver</td><td>Check if game has ended</td><td></td><td>boolean</td>
</tr>

</table>

=== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua GLSL Api

2010-11-22T22:45:48Z

Pithikos:

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

These functions are ONLY available if the graphic board supports GLSL. Please test in your scripts if one of them exists before you use them!

'''gl.CreateShader'''
({ [ vertex = "glsl code" ,]
[ geometry = "glsl code" ,]
[ fragment = "glsl code" ,]
[ uniform = { uniformName = number value, ...} ,]
[ uniformInt = { uniformName = number value, ...} ,]
[ uniformMatrix = { uniformName = number value, ...} ,]
[ geoInputType = number inType,]
[ geoOutputType = number outType,]
[ geoOutputVerts = number maxVerts,]
}) -> number shaderID

'''gl.DeleteShader'''
( number shaderID ) -> nil

'''gl.ActiveShader''' can be used in none drawing events (to update uniforms etc.)!
( number shaderID, function [, arg1 [, arg2, ..]] ) -> nil

'''gl.UseShader'''
( number shaderID ) -> boolean linked

'''gl.GetShaderLog'''
( ) -> string "errorLog"

'''gl.SetShaderParameter''' needed by geometry shader programs (check the opengl shader4 extension for glProgramParameteri)
( number shaderID, number param, number value ) -> nil

'''gl.GetActiveUniforms'''
( number shaderID ) -> {
[1] = { name = "name", type = "type", length = number length, size = number size },
...
}

'''gl.GetUniformLocation'''
( number shaderID, name uniformName ) -> number locationID

'''gl.Uniform'''
( number locationID, number f1 [,number f2 [,number f3 [,number f4]]] ) -> nil

'''gl.UniformInt'''
( number locationID, number int1 [,number int2 [,number int3 [,number int4]]] ) -> nil

'''gl.UniformMatrix'''
( number locationID,
"shadow" |
"camera" |
"caminv" |
"camprj" |
number m1, number m2, number m3, number m4 |
number m1, ... , number m9 |
number m1, ... , number m16
) -> nil

[[category: Lua]]

Lua:Main

2010-11-22T22:43:34Z

Pithikos: /* Other useful informations */

[[Engine_Development|Development]] < {{FULLPAGENAME}}

=Lua FAQ=
[[Lua_Beginners_FAQ]] 
[http://spring.clan-sy.com/phpbb/viewtopic.php?f=23&t=15596 Forum topic with some basic information about gadgets] 
[http://spring.clan-sy.com/phpbb/viewtopic.php?f=23&t=16223 Forum topic with a manual on Spring lua scripting] 

=Interfaces (last update: 0.82rc)=
[[:Category:Lua]] (shows which interfaces are loaded by LuaUI,LuaRules,etc.) 
{{LuaInterfaces}}

=Other useful information=
[[LuaCallinReturn]] 
[http://spring.clan-sy.com/wiki/COB_Constants#Custom_Variables COB Custom Variables] 
[http://springrts.com/phpbb/viewtopic.php?f=12&t=19560 Font Drawing System] 
[[UI_commands]] 
synced and unsynced Lua:[[Lua_sync_to_unsync]]

=Official Lua documentation=
[http://www.lua.org/pil/ 'Programming in Lua' book online] 
[http://www.lua.org/manual/5.1/ Lua 5.1 Reference manual] 
[http://lua-users.org/wiki/TutorialDirectory Lua tutorials]
[[Category: Lua]]

Lua UnsyncedRead

2010-11-22T22:41:06Z

Pithikos: /* Unsynced Read */

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

Here follows functions(and some global variables) that can be used to read information rewarding the game. These functions work BOTH in the unsynced environment and the synced environment.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for XOR. So if you see A | B before the output sign("->") then it means that it gets either A or B as argument. If you see this after the output sign then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B before the output sign means that the function gets A and B as arguments. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicates the type of the argument or the return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you have to pass argument A and if you wish you can even pass a second argument, B. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
 
== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z
'''Spring.TraceScreenRay'''
( number mouseX, number mouseY [, boolean onlyCoords [, boolean useMinimap] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean extrapolated ] ) -> nil | boolean
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== UI ==

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "path" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> 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.GetActiveCmdDesc'''
( number index ) -> nil | {
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.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''
( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed
'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number] = boolean,
...
}
'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | { [1] = {[string actionCmd] = string actionExtra}, ... }
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit

== Time ==
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.DiffTimers'''
( timer cur, timer ago) -> number seconds

[[category: Lua]]

Gamedev:Structure

2010-11-22T22:36:37Z

Pithikos: /* Mod structure */

= Mod structure =
The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folders/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mods is as follows:
 
;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations(which are script files) for the 3d models. Animations are not a must but they are necessary in case we make a non-static 3d model. With non-static we mean 3d models that can animate(walk, taget, shoot etc). In the other hand we might have static 3d objects. Examples of that could be decoration objects for a map like stones, trees, etc. Files in this folder can either be of the .cob or .lua format. Lua files are simple text files while .cob files are binary files/executables. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .cob files are compiled .bos files. Bos files are not really executed at any point but are rather in the folder so you can see what each compiled file does.
:*.bos
:: Animation script files. These are source files for .cos and are never executed. They are present in the folder just to give an intuition to developers of what the coresponding .cob file does.
:*.cob
:: Compiled .bos files. These are the files that are being executed ingame.
:*.lua
:: Animation script files. These are executed(interprented) directly ingame.

Gamedev:Structure

2010-11-22T22:35:51Z

Pithikos: /* Mod structure */

= Mod structure =

The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folders/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mods is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations(which are script files) for the 3d models. Animations are not a must but they are necessary in case we make a non-static 3d model. With non-static we mean 3d models that can animate(walk, taget, shoot etc). In the other hand we might have static 3d objects. Examples of that could be decoration objects for a map like stones, trees, etc. Files in this folder can either be of the .cob or .lua format. Lua files are simple text files while .cob files are binary files/executables. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .cob files are compiled .bos files. Bos files are not really executed at any point but are rather in the folder so you can see what each compiled file does.
:*.bos
:: Animation script files. These are source files for .cos and are never executed. They are present in the folder just to give an intuition to developers of what the coresponding .cob file does.
:*.cob
:: Compiled .bos files. These are the files that are being executed ingame.
:*.lua
:: Animation script files. These are executed(interprented) directly ingame.

Lua UnsyncedRead

2010-11-22T22:27:32Z

Pithikos:

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

Here follows functions(and some global variables) that can be used to read information rewarding the game. These functions work BOTH in the unsynced environment and the synced environment.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for XOR. So if you see A | B before the output sign("->") then it means that it gets either A or B as argument. If you see this after the output sign then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B before the output sign means that the function gets A and B as arguments. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicates the type of the argument or the return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 
 
 
== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z
'''Spring.TraceScreenRay'''
( number mouseX, number mouseY [, boolean onlyCoords [, boolean useMinimap] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean extrapolated ] ) -> nil | boolean
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== UI ==

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "path" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> 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.GetActiveCmdDesc'''
( number index ) -> nil | {
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.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''
( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed
'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number] = boolean,
...
}
'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | { [1] = {[string actionCmd] = string actionExtra}, ... }
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit

== Time ==
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.DiffTimers'''
( timer cur, timer ago) -> number seconds

[[category: Lua]]

Lua UnsyncedRead

2010-11-22T22:23:31Z

Pithikos: /* Local Player,Team,Ally */

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

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z
'''Spring.TraceScreenRay'''
( number mouseX, number mouseY [, boolean onlyCoords [, boolean useMinimap] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean extrapolated ] ) -> nil | boolean
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== UI ==

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "path" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> 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.GetActiveCmdDesc'''
( number index ) -> nil | {
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.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''
( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed
'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number] = boolean,
...
}
'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | { [1] = {[string actionCmd] = string actionExtra}, ... }
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit

== Time ==
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.DiffTimers'''
( timer cur, timer ago) -> number seconds

[[category: Lua]]

Lua SyncedRead

2010-11-22T22:20:31Z

Pithikos: /* Game */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for XOR. So if you see A | B before the output sign("->") then it means that it gets either A or B as argument. If you see this after the output sign then it means that either A or B will be returned. Pay attention that ONLY one of the two will be passed/returned. 
*, is to seperate arguments/values. So A, B before the output sign means that the function gets A and B as arguments. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicates the type of the argument or the return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it just means that the table is empty. 

=== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-22T22:15:39Z

Pithikos: /* Game */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

*-> Text following after this shows what the function returns 
*| stands for OR. So if you see "A | B" before the output sign("->") then it means that it gets either A or B as parameter. If you see this after the output sign then it means that either A or B will be returned. 
*, is to seperate parameters/values. So A, B before the output sign means that the function gets A and B as parameters. After the output sign it means that the function returns A and B. 
*number, string, nil, boolean just indicate the type of the parameter or return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
*[] stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
*{..} is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it means that the table is empty. 

=== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-22T22:13:31Z

Pithikos: /* Game */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

"->". Text following after this shows what the function returns 
"|" stands for OR. So if you see "A | B" before the output sign("->") then it means that it gets either A or B as parameter. If you see this after the output sign then it means that either A or B will be returned. 
"," is to seperate parameters/values. So A, B before the output sign means that the function gets A and B as parameters. After the output sign it means that the function returns A and B. 
"number", "string", "nil", "boolean" just indicate the type of the parameter or return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
"[]" stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 
"{..}" is the indication of a table. Tables are usually returned and almost never passed as arguments. If you see {A=number, B=string} then it means that the returned value is a table that has variable A which holds a number and variable B that holds a string. If you just see {} then it means that the table is empty. 

=== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2010-11-22T22:07:46Z

Pithikos: /* Game */

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

== Game ==

Here follows functions(and some variables in the beginning) that can be used to read infromation rewarding the game. Some of these functions work even in the unsynced enviroment but in that case they execute only for the allies and you.
 
 
Reading a function: 
<function>
(number A | string B, number C) -> nil | number, number 

"->". Text following after this shows what the function returns 
"|" stands for OR. So if you see "A | B" before the output sign("->") then it means that it gets either A or B as parameter. If you see this after the output sign then it means that either A or B will be returned. 
"," is to seperate parameters/values. So A, B before the output sign means that the function gets A and B as parameters. After the output sign it means that the function returns A and B. 
"number", "string", "nil", "boolean" just indicate the type of the parameter or return value. So if it stands number A, string B before the output sign then it means that first parameter is a number and second parameter is a string. If it follows after the output sign then it means that the return value A is a number and the second is a string. 
"[]" stands for "optional". If you see number A, [string B] before the output sign then it means that you MUST pass argument A and if you wish even a second argument. 

=== 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''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> number value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = number value2}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number value1}, [ruleIndex2] = {[ruleName2] = 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 ) ->
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)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

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

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
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''' 0.82 and later
( 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
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''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''' Removed from version 0.83.x 
( 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.GetUnitMetalExtraction''' 0.82+ and later
( 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.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 [, 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
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" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( 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
'''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

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

=== 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,
"meta" = 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,
"meta" = 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,
"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 [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [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.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

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

=== 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Gamedev:Structure

2010-11-17T17:12:20Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folders/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mods is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations(which are script files) for the 3d models. Animations are not a must but they are necessary in case we make a non-static 3d model. With non-static we mean 3d models that can animate(walk, taget, shoot etc). In the other hand we might have static 3d objects. Examples of that could be decoration objects for a map like stones, trees, etc. Files in this folder can either be of the .cob or .lua format. Lua files are simple text files while .cob files are binary files/executables. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .cob files are compiled .bos files. Bos files are not really executed at any point but are rather in the folder so you can see what each compiled file does.
:*.bos
:: Animation script files. These are source files for .cos and are never executed. They are present in the folder just to give an intuition to developers of what the coresponding .cob file does.
:*.cob
:: Compiled .bos files. These are the files that are being executed ingame.
:*.lua
:: Animation script files. These are executed(interprented) directly ingame.

Gamedev:Structure

2010-11-17T17:02:03Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folders/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mods is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations(which are script files) for the 3d models. Animations are not a must but they are necessary in case we make a non-static 3d model. With non-static we mean 3d models that can animate(walk, taget, shoot etc). In the other hand we might have static 3d objects. Examples of that could be decoration objects for a map like stones, trees, etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T16:58:52Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folders/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mods is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations(which are script files) for the 3d models. Animations are not a must but they are helpful in case we make a non-static 3d model. With non-static we mean 3d models that are not changing form(walking, shooting etc). In the other hand we might have static 3d objects without animations. Examples of that could be a decoration object for a map like a big stone or some tree. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T16:51:24Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folders/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mods is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map, like stones, trees etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T16:50:58Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folders/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mod is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map, like stones, trees etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T00:47:12Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In this zip file there are actually very few folders and files that are de facto in every mod. For more about the de facto folers/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mod is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map, like stones, trees etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T00:44:09Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In the zip file there are very few folders and files that are the de facto folders and files of a mod. For more about the de facto folers/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mod is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit! Keep in mind that this file just keeps information about each unit. It doesn't contain the actual 3d model of the unit that you see in game. Instead this file among other things tells the spring engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map, like stones, trees etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T00:41:42Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
In the zip file there are very few folders and files that are the de facto folders and files of a mod. For more about the de facto folers/files that are used in every mod you can read further on http://springrts.com/wiki/Mod_specification.
The structure widely used for mod is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:*.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit in the mod. Keep in mind that this file just keeps information about each unit. It doesn't contain the 3d model of the unit. Instead this file among other stuff tells the engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map, like stones, trees etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T00:27:33Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
The structure inside that zip file is as follows:

;units/
:This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
:.fbi
::files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit in the mod. Keep in mind that this file just keeps information about each unit. It doesn't contain the 3d model of the unit. Instead this file among other stuff tells the engine which 3d model to use for each unit.

;Objects3d/
:This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

;Scripts/
:This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map, like stones, trees etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T00:25:19Z

Pithikos: /* Mod structure */

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
The structure inside that zip file is as follows:

*units/
**This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
**.fbi
***files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit in the mod. Keep in mind that this file just keeps information about each unit. It doesn't contain the 3d model of the unit. Instead this file among other stuff tells the engine which 3d model to use for each unit.

*Objects3d/
**This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

*Scripts/
**This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map, like stones, trees etc. Files in this folder can either be of the .cob or .lua format. Both are simple text files. Bos and cob are file formats used in the original Total Annihilation. The relation between them is that the .bos files are compiled .cob files. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Gamedev:Structure

2010-11-17T00:22:54Z

Pithikos: Created page with "== Mod structure == The mod file is just a plain zipped file in the .7z format. The structure inside that zip file is as follows: *units/ **This folder is the main..."

== Mod structure ==

The mod file is just a plain zipped file in the .7z format. 
The structure inside that zip file is as follows:

*units/
**This folder is the main folder for the units in the mod. Every unit in the mod must have its appropriate file in this folder. All files in this folder have the extension .fbi. For convention, the names given to the files are descriptive for the units. For example the arm commander's .fbi file is called "armcom.fbi".
**.fbi
***files inside the â€unitsâ€ folder have the extension .fbi. These files are simple text files with information about each unit used in the mod. No .fbi file, no unit in the mod. Keep in mind that this file just keeps information about each unit. It doesn't contain the 3d model of the unit. Instead this file among other stuff tells the engine which 3d model to use for each unit.

*Objects3d/
**This folder contains the 3d models for each 3d object in the mod. That can be a model of a unit, a wreckage, a map object or something else. For each .fbi file in the â€unitsâ€ folder there must be a corresponding 3d model in the â€Objects3dâ€ folder.

*Scripts/
**This folder contains animations for the 3d models. Files are not necessary for each unit if you don't need one 3d object in the mod to be animated. That could be for example a decoration object for a map like stones, trees etc. Files in this folder can either be cob or lua. Cob files are just compiled .bos files. Boc and cob are file formats used in the original Total Annihilation. Cob files are not really executed at any point but are rather in the folder so you can see what each compiled file does.

Game and Unit development

2010-11-17T00:12:32Z

Pithikos: /* General */

[[Engine_Development|Development]] < {{FULLPAGENAME}}

=Game development=
This information is meant to help newcomers learn how to develop their own games for the Spring Engine.
==General==
*[[Mod structure]] 
*[[Mod specification|Game specification]] 
*[http://springrts.com/phpbb/viewtopic.php?t=6015 What do I need to create a game?]
*[[Simple Mod Tutorial|Simple Game Tutorial]]
*[[Freely available and reusable content|Freely available and reusable content for maps and games]]
*[[The Complete Guide To Making A Spring Game]]

=Modeling (.3do, .s3o)=
Spring supports different 3d representations: '.s3o' and '.3do'. The biggest difference between both formats is the workflow to create a new unit. There are exporter plugins for 'blender' and '3ds-max' so that texturing and modeling can be done using these.
In contrast: when you model an '.3do' you have to use 'UpSpring' currently.

The animation with can either be done using 'lua' or 'COB/BOS' is does not depend on either, see rigging/animation. For new units use 'lua' scripting.

==s3o modeling==
* [[Basic s3o unit making guide]] (using UpSpring)
* [[s3o using blender]] (not using UpSpring)
* [[Trouble-shooting s3o units]]

===Tutorials===
* [http://springrts.com/phpbb/viewtopic.php?t=10612 Wings UV Mapping Tutorial]
* [http://springrts.com/phpbb/viewtopic.php?f=9&t=12354 Saving polygons in Wings3d Tutorial]
* [http://springrts.com/phpbb/viewtopic.php?t=10503 Runecrafter's 3DS Max UV Mapping Tutorial]

===S3O Textures===
* [http://springrts.com/phpbb/viewtopic.php?f=57&t=22392 DDS Textures: How To]
* [http://springrts.com/phpbb/viewtopic.php?t=10947 Greeble Tutorial 1]
* [http://springrts.com/phpbb/viewtopic.php?f=9&t=12356 Greeble Tutorial 2]

==Models - 3do Files==
'''NOTE:''' 3do is an outdated model format used by OTA models (Balanced Annihilation, NOTA, etc.). 
(Note: UpSpring has some problems with empty objects and groundplates)
*use [http://springrts.com/phpbb/viewtopic.php?f=12&t=7208&p=126129&hilit=upspring#p126129 UpSpring] and [http://springfiles.com/1755 3doBuilder] to edit those files
*[http://user.supradigital.org/jcnossen/UpspringInstaller-1.54-EulerAngles.exe Click here to download UpSpring, our content support tool.]
* [http://springrts.com/phpbb/viewtopic.php?f=9&t=15106 Argh's UpSpring Easy Workflow Guide]
* [http://lassie.student.utwente.nl/vliet/springtut.pdf Maestro's tutorial of Upspring and textures- very outdated].

=Scripting/Animations (.cob, .bos, .lua)=
==Lua Animations==
To edit .lua files you need a text editor.
*[[Animation-LuaScripting]]
**[[Animation-LuaCallins]]
**[[Animation-LuaCallouts]]
**[[Animation-CobLuaDifferences]]

==COB Animations==
The binary '.cob' file format is obsolete and some '.cob' files might be copyrighed by cavedog. A '.cob' file can be decompiled to see what it is doing or if you have the source, that is a '.bos' file, you can compile it into a '.cob' file.

To edit .bos files you need a program/compiler. The most famous one is [http://jobjol.nl/1384 Scriptor]
*[[Animation-CobLuaDifferences]]
*[[Animation-CobOverview]]
**[[Animation-CobExamples]]
**[[Animation-CobAnimation]]
**[[Animation-CobCallins]]
**[[Animation-CobConstants]]
**[[Animation-CobThreads]]
**[[Animation-CobHitByWeaponID]]
*[[Units:LuaCOB]] - how to interface COB with LUA
*[[CEG_For_Units|Game Development:Calling basic CEGs from COB]]
* [http://springrts.com/phpbb/viewtopic.php?p=132943#132943 GPL-compliant sourcecode, scripting code examples, and other things.]

=UnitDefs (.fbi, .lua)=
*[[Units:FBI]]
*[[All_FBI-variable_values:_min,_max,_default,_type|Units:FBI (variable datatype list)]]
*[[Unit_Categories]]

=MoveDefs (movedefs.lua)=
*[[Units:MoveTypes]]

=WeaponDefs (.tdf, .lua)=
*[[Weapon Variables]] : This is the most up to date
*[[Units:WeaponMainDir]]
*[[Units:Weapons]] : Various informations about the weapontypes (uncompleted)
*[[Weapons:Antinukes]]: All about antinukes.

=Explosions (.tdf, .lua)=
*[[CEG]]
**[[CEG-Calls]]
**[[CEG-Format]]
**[[CEG-Classes]]
**[[CEG-Operators]]
**[[CEG-Miscellaneous]]
**[[CEG-OldInfo]]

=Misc=
*[[Units:Design]]
*[[Units:Textures]]
*[[Units:Buildpics]]
*[[Units:SideData TDF]]
*[[Units:Download TDF]]
*[[Units:FlankingBonus]]
*[[Mod Development:Armor|Game Development:Armor]]
*[[Mod Development:Cursors|Game Development:Cursors]]
*[[Mod Development:Archives|Game Development:Archives]]
*[[Mod Development:Sidepics|Game Development:Sidepics]]
*[[CustomUnitIcons|Game Development:Custom unit icons]]

=Legacy Porting Tools=
==Automated Game Creation==
* [[TA2Spring]] - Automatically adds and converts Total Annihilation unit packs (.ufo files, etc..) into Spring games (requires a base game for the game rules, XTA is recommended, it is probably not properly supported by current Spring)

[[Category: Unit_development]]
[[Category: Mod_development]]

Lua sync to unsync

2010-11-16T21:33:10Z

Pithikos:

== synced and unsynced lua ==
 
 
<center>Using globals</center>
 
When making a gadget you will sometimes want to combine synced and unsynced code. 
For example if you do some things with units, that code will need to be synced. 
The UnitDestroyed, UnitFinished etc. callins can only be called in synced code. Using them inside unsynced code is not going to work. 
If you want to draw on the screen (for example to mark units) then the drawing will have to happen in unsynced code.
 
 
The following example demonstrates how to change the value inside the synced block of code and read the value in the unsynced block of code:
 

<pre>
if (gadgetHandler:IsSyncedCode()) then
--SYNCED CODE
local number = 10 -- declaring local variable 'number'
function gadget:SomeSyncedCallin(...)
number=number+1 -- increment variable's value by one
_G.number=number -- save the new value into a global variable
end
else
--UNSYNCED CODE
function gadget:SomeUnsyncedCallin(...)
Spring.Echo(SYNCED.number) -- print the global variable's value on screen
end
end
</pre>

 
 
 
 

<center>Using special functions</center>
 
Another way is to use the SendToUnsynced callin. 
Here is an example by quantum: 
http://pastebin.com/hMHv3Lrf 

<pre>[LCC]quantum[0K] every time there is a new target, i send "addTarget" and its number to unsynced
[LCC]quantum[0K] when a target is removed from the list, i send "removeTarget" and its number
[LCC]quantum[0K] this wierd stuff:
[LCC]quantum[0K] _G.laserEventArgs = eventArgs
[LCC]quantum[0K] SendToUnsynced("LaserEvent")
[LCC]quantum[0K] _G.laserEventArgs = nil
[LCC]quantum[0K] puts the eventArgs table somewhere were unsynced can find it
[LCC]quantum[0K] sends a signal to unsynced called "LaserEvent"
[LCC]quantum[0K] and removes the table
[LCC]quantum[0K] on the unsynced side, _G.laserEventArgs becomes SYNCED.laserEventArgs
[LCC]quantum[0K] this copies it to another table, ready for reuse: for k, v in spairs(SYNCED.laserEventArgs) do
[LCC]quantum[0K] eventArgs[k] = v
[LCC]quantum[0K] end
[LCC]quantum[0K] also, this: gadgetHandler:AddSyncAction("LaserEvent", HandleLaserEvent)
LCC]quantum[0K] means that i want the HandleLaserEvent function to be called every time i do SendToUnsynced("LaserEvent")<pre>

Lua sync to unsync

2010-11-16T19:22:15Z

Pithikos: /* synced and unsynced lua */

== synced and unsynced lua ==
 
 
<center>Using globals</center>
 
When making a gadget you will sometimes want to combine synced and unsynced code. 
For example if you do some things with units, that code will need to be synced. 
The UnitDestroyed, UnitFinished etc. callins can only be called in synced code. Using them inside unsynced code is not going to work. 
If you want to draw on the screen (for example to mark units) then the drawing will have to happen in unsynced code.
 
 
The following example demonstrates how to change the value inside the synced block of code and read the value in the unsynced block of code:
 
<pre>
if (gadgetHandler:IsSyncedCode()) then
--SYNCED CODE
local number = 10 -- declaring local variable 'number'
function gadget:SomeSyncedCallin(...)
number=number+1 -- increment variable's value by one
_G.number=number -- save the new value into a global variable
end
else
--UNSYNCED CODE
function gadget:SomeUnsyncedCallin(...)
Spring.Echo(SYNCED.number) -- print the global variable's value on screen
end
end
</pre>
 
 
 
 

<center>Using special functions</center>
 
Another way is to use the SendToUnsynced callin. 
Here is an example by quantum: 
http://pastebin.com/hMHv3Lrf 

<pre>[LCC]quantum[0K] every time there is a new target, i send "addTarget" and its number to unsynced
[LCC]quantum[0K] when a target is removed from the list, i send "removeTarget" and its number
[LCC]quantum[0K] this wierd stuff:
[LCC]quantum[0K] _G.laserEventArgs = eventArgs
[LCC]quantum[0K] SendToUnsynced("LaserEvent")
[LCC]quantum[0K] _G.laserEventArgs = nil
[LCC]quantum[0K] puts the eventArgs table somewhere were unsynced can find it
[LCC]quantum[0K] sends a signal to unsynced called "LaserEvent"
[LCC]quantum[0K] and removes the table
[LCC]quantum[0K] on the unsynced side, _G.laserEventArgs becomes SYNCED.laserEventArgs
[LCC]quantum[0K] this copies it to another table, ready for reuse: for k, v in spairs(SYNCED.laserEventArgs) do
[LCC]quantum[0K] eventArgs[k] = v
[LCC]quantum[0K] end
[LCC]quantum[0K] also, this: gadgetHandler:AddSyncAction("LaserEvent", HandleLaserEvent)
LCC]quantum[0K] means that i want the HandleLaserEvent function to be called every time i do SendToUnsynced("LaserEvent")<pre>

Lua sync to unsync

2010-11-16T19:15:05Z

Pithikos: /* synced and unsynced lua */

== synced and unsynced lua ==
 
 
<center>Using globals</center>
 
When making a gadget you will sometimes want to combine synced and unsynced code. 
For example if you do some things with units, that code will need to be synced. 
The UnitDestroyed, UnitFinished etc. callins can only be called in synced code. Using them inside unsynced code is not going to work. 
If you want to draw on the screen (for example to mark units) then the drawing will have to happen in unsynced code.
 
 
The following example demonstrates how to change the value inside the synced block of code and read the value in the unsynced block of code:
 
<code>
if (gadgetHandler:IsSyncedCode()) then

local number = 10 -- declaring variable 'number'

function gadget:SomeSyncedCallin(...)
number=number+1 -- increment variable's value by one
_G.number=number -- save the new value into a global variable
end

else

function gadget:SomeUnsyncedCallin(...)
Spring.Echo(SYNCED.number) -- print the global variable's value on screen
end

end
</code>
 
 
 
 

<center>Using special functions</center>
 
Another way is to use SendToUnsynced 
Here is an example by quantum: 
http://pastebin.com/hMHv3Lrf 

<pre>[LCC]quantum[0K] every time there is a new target, i send "addTarget" and its number to unsynced
[LCC]quantum[0K] when a target is removed from the list, i send "removeTarget" and its number
[LCC]quantum[0K] this wierd stuff:
[LCC]quantum[0K] _G.laserEventArgs = eventArgs
[LCC]quantum[0K] SendToUnsynced("LaserEvent")
[LCC]quantum[0K] _G.laserEventArgs = nil
[LCC]quantum[0K] puts the eventArgs table somewhere were unsynced can find it
[LCC]quantum[0K] sends a signal to unsynced called "LaserEvent"
[LCC]quantum[0K] and removes the table
[LCC]quantum[0K] on the unsynced side, _G.laserEventArgs becomes SYNCED.laserEventArgs
[LCC]quantum[0K] this copies it to another table, ready for reuse: for k, v in spairs(SYNCED.laserEventArgs) do
[LCC]quantum[0K] eventArgs[k] = v
[LCC]quantum[0K] end
[LCC]quantum[0K] also, this: gadgetHandler:AddSyncAction("LaserEvent", HandleLaserEvent)
LCC]quantum[0K] means that i want the HandleLaserEvent function to be called every time i do SendToUnsynced("LaserEvent")<pre>