Lua UnsyncedRead

Development < Lua Scripting < Lua UnsyncedRead

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