Lua UnsyncedRead

Development < Lua Scripting < Lua UnsyncedRead

Unsynced Read

Replay/Spectating

Spring.IsReplay ( )
return: nil | bool isReplay

Spring.GetReplayLength ( )
return: nil | number timeInSeconds

New in version 92.0

Spring.GetSpectatingState ( )
return: bool spectating, bool fullView, bool fullSelect

Game/Menu Name

Spring.GetGameName ( )
return: string name

New in version 104.0
Apparently returns name .. version from Modinfo.lua. E.g. "Spring: 1944 test-5640-ac2d15b".

Spring.GetMenuName ( )
return: string name

New in version 104.0

ModUI

Spring.GetModUICtrl ( )
return: bool ModUICtrl

MyInfo

Spring.GetMyAllyTeamID ( )
return: number allyTeamID

Spring.GetMyTeamID ( )
return: number teamID

Spring.GetMyPlayerID ( )
return: number playerID

Local Player,Team,Ally

Redundant same as the GetMyXYZ functions!

Spring.GetLocalPlayerID ( )
return: number playerID

Spring.GetLocalTeamID ( )
return: number teamID

Spring.GetLocalTeamID ( )
return: number allyID

Team/Player Info

Spring.GetPlayerRoster ( [number sortType] | [number sortType], [bool showPathingPlayers] )
return: nil | table playerTable

"playerTable" contains:

playerTable = {
            [1] = {
              string  name,
              number  playerID,
              number  teamID,
              number  allyTeamID,
              boolean spectator,
              number  cpuUsage,
              number  pingTime
            },
            etc...
          }

   if pingTime == -1, the player is pathfinding, in order to find the progress, use:
   cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
   for the progress
  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 )
return: nil | number r, number g, number b, number a

Spring.GetTeamOrigColor ( number teamID )
return: nil | number r, number g, number b, number a

Spring.GetPlayerTraffic ( number playerID [, number packetID ] )
return: number traffic

Sound

Spring.GetSoundStreamTime ( )
return: number playedTime, number totalTime,

Camera

Spring.GetCameraNames ( )
return: { [camName] = number camNum, ... }

Spring.GetCameraState ( )
return: { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See Lua_camState for details about Spring.GetCameraState output.

Spring.GetCameraPosition ( )
return: number x, number y, number z

Spring.GetCameraDirection ( )
return: number forward_x, number forward_y, number forward_z

Spring.GetCameraFOV ( )
return: number vFov, number hFov

Spring.GetCameraVectors ( )
return: table vectorTable

vectorTable contains:

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 [, bool Icons = true ]]] )
return: nil | table unitTable = { [1] = number unitID, ... }

Spring.GetVisibleFeatures ( [number allyTeamID = -1 [, number radius = 30 [, bool Icons = true [, bool geos = true ]]]] )
return: nil | table featureTable = { [1] = number featureID, ... }

Spring.IsAABBInView ( number minX, number minY, number minZ, number maxX, number maxY, number maxZ )
return: nil | bool isInView

Spring.IsSphereInView ( number x, number y, number z [, number radius ] )
return: nil | bool isInView

Spring.IsUnitIcon ( number unitID )
return: nil | bool isUnitIcon

Spring.IsUnitInView ( number unitID )
return: nil | bool isUnitInView

Spring.IsUnitVisible ( number unitID [, number radius [, bool checkIcons ]] )
return: nil | bool isVisible

Screen Trace

Spring.WorldToScreenCoords ( number x, number y, number z )
return: number x, number y, number z

Spring.TraceScreenRay ( number mouseX, number mouseY, number mouseZ [, bool onlyCoords [, bool useMinimap [, bool includeSky [, bool ignoreWater [, number D ]]]]] )
return: nil | string unit, number unitID | string feature, number featureID | string ground, table coords = { [1] = number x, [2] = number y, [3] = number z }

New in version 101.0

Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
   local mouseX, mouseY = Spring.GetMouseState()
   print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
   local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
   if nil == desc then return end -- off map
   local x = args[1]
   local y = args[2]
   local z = args[3]
   print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")

Spring.GetPixelDir ( number x, number y )
return: number dirX, number dirY, number dirZ

New in version 95.0

Screen & Window Geometry

Spring.GetViewGeometry ( )
return: number viewSizeX, number viewSizeY, number viewPosX, number viewPosY

Spring.GetWindowGeometry ( )
return: number winSizeX, number winSizeY, number winPosX, number winPosY

Spring.GetScreenGeometry ( )
return: number screenSizeX, number screenSizeY, number ZERO, number ZERO

Is missing multiscreen support!

Unit

Spring.IsUnitAllied ( number unitID )
return: nil | bool isAllied

Spring.GetUnitViewPosition ( number unitID [, bool midPos = false ] )
return: nil | number x, number y, number z

Spring.GetUnitTransformMatrix ( number unitID [, bool invert = false ] )
return: nil | number a11, number a12 ..., number a44 (4x4 matrix)

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

Selected Units

Spring.GetSelectedUnits ( )
return: { [1] = number unitID, ... }

Spring.GetSelectedUnitsSorted ( )
return: { [number unitDefID] = { [1] = [number unitID], etc... }, ... }

Spring.GetSelectedUnitsCounts ( )
return: { [number unitDefID] = number count, etc... }

Spring.GetSelectedUnitsCount ( )
return: number count

Spring.IsUnitSelected ( number unitID )
return: nil | bool isSelected

Unit Groups

Spring.GetUnitGroup ( number unitID )
return: nil | number groupNumber

Spring.GetGroupList ( )
return: nil | { [number] = number unitCount, ... }

Spring.GetSelectedGroup ( )
return: number groupNumber

Spring.GetGroupAIName ( number groupID )
return: string aiName

Spring.GetGroupAIList ( )
return: { [1] = string aiName, ... }

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

Spring.GetGroupUnitsSorted ( number groupID )
return: nil | { [number unitDefID] = { number unitID, ... }, ... }

Spring.GetGroupUnitsCounts ( number groupID )
return: nil | { [number unitDefID] = number count, ... }

Spring.GetGroupUnitsCount ( number groupID )
return: nil | number count

Feature

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

Projectiles

Spring.GetVisibleProjectiles ( [ number allyTeamID = -1 [, bool addSyncedProjectiles = true [, bool addWeaponProjectiles = true [, bool addPieceProjectiles = true ]]]] )
return: nil | { [1] = number projectileID, ... }

UI

Spring.GetUICommands ( )
return: nil | { [1] = { command=string, description=string, synced=bool, cheat=bool}, ... }

New in version 101.0
Returns a list of available UI commands.

GUI Settings

Spring.IsGUIHidden ( )
return: nil | bool isHidden

Spring.HaveShadows ( )
return: nil | bool haveShadows

Spring.HaveAdvShading ( )
return: nil | bool haveShading

Spring.GetWaterMode ( )
return: nil | number mode, string mode

  mode numbers:
      0 - basic
      1 - reflective
      2 - dynamic
      3 - refractive
      4 - bumpwater
      default - unknown

Spring.GetMapDrawMode ( )
return: nil | string "normal" | string "height" | string "metal" | string "pathTraversability" | string "los"

Spring.GetDrawSelectionInfo ( )
return: bool drawSelectInfo

Returns whether "Selected units" text is displayed.

Unit & Feature GUI States

Spring.GetUnitLuaDraw ( number unitID )
return: nil | bool unitDraw

Spring.GetUnitNoDraw ( number unitID )
return: nil | bool noDraw

Spring.GetUnitNoMinimap ( number unitID )
return: nil | bool noMinimap

Spring.GetUnitNoSelect ( number unitID )
return: nil | bool noSelect

Spring.GetFeatureLuaDraw ( number featureID )
return: nil | bool featureDraw

Spring.GetFeatureNoDraw ( number featureID )
return: nil | bool noDraw

Minimap

Spring.GetMiniMapGeometry ( )
return: number posX, number posY, number sizeX, number sizeY, bool minimized, bool maximized

Spring.GetMiniMapDualScreen ( )
return: bool false | string "left" | string "right"

Spring.IsAboveMiniMap ( number x, number y )
return: nil | bool isAbove

(Build-)Menu

Spring.GetActiveCommand ( )
return: nil | number index [, number cmd_id, number cmd_type, string cmd_name ]

Spring.GetDefaultCommand ( )
return: nil | number index [, number cmd_id, number cmd_type, string cmd_name ]

Spring.GetActiveCmdDescs ( )
return: nil | table cmdDesc

cmdDesc contains:

cmdDesc = {
    [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 ( )
return: nil | table cmdDesc

cmdDesc contains:

cmdDesc = {
      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 )
return: nil | number index

Spring.GetActivePage ( )
return: nil | number pageNum, number maxPages

Build Facing

Spring.GetBuildFacing ( )
return: nil | number facing

Spring.GetBuildSpacing ( )
return: nil | number spacing

GatherMode & InvertQueueKey

Spring.GetGatherMode ( )
return: nil | number gatherMode

Spring.GetInvertQueueKey ( )
return: nil | number queueKey

Mouse States

Spring.GetMouseState ( )
return: number x, number y, bool leftPressed, bool middlePressed, bool rightPressed, bool offscreen

New in version 104.0 Sixth return value offscreen.
X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner. For world coordinates see Spring.TraceScreenRay.

Spring.GetMouseCursor ( )
return: string name, number scale

Spring.GetMouseStartPosition ( number mouseButton )
return: nil | number pressedX, number pressedY, number camPosX, number camPosY, number camPosZ, number dirX, number dirY, number dirZ

(Hot-)Keys

Spring.GetKeyState ( number key )
return: nil | bool keyState

Spring.GetModKeyState ( )
return: bool alt, bool ctrl, bool meta, bool shift

Spring.GetPressedKeys ( )
return: { [number code] = bool, [string name] = bool, ... }

New in version 99.0: string name

Spring.GetKeyCode ( string keysym )
return: number keyCode

Spring.GetKeySymbol ( number key )
return: string "keysym1", string "keysym2"

Spring.GetKeyBindings ( string keyset )
return: nil | table keyBindings

keyBindings contains:

keyBindings = {
    [1] = {
      [string actionCmd] = string actionExtra,
      command   = string actionCmd,    {{new|97}}
      boundWith = string boundWith,    {{new|97}}
      extra     = string actionExtra,  {{new|97}}
    }, ...
  }

Spring.GetActionHotKeys ( string action )
return: nil | { [1] = string hotKey, ... }

Console

Spring.GetLastMessagePositions ( )
return: nil | { [1] = { number x, number y, number z }, ... }

Spring.GetConsoleBuffer ( [number maxLines] )
return: nil | { [1] = { text = string, priority = number }, ... }

Spring.GetCurrentTooltip ( )
return: string tooltip

LOS Colors

Spring.GetLosViewColors ( )
return: table always = {r,g,b}, table LOS = {r,g,b}, table radar = {r,g,b}, table jam = {r,g,b}, table radar2 = {r,g,b}

New in version 100

Config

Spring.GetConfigParams ( )
return: table configParams

Same information as spring --list-config-vars
configParams contains:

configParams = {
    {
      name = string,
      type = string,
      [ description = string, ]
      [ defaultValue = string, ]
      [ minimumValue = string, ]
      [ maximumValue = string, ]
      [ safemodeValue = string, ]
      [ declarationFile = string, ]
      [ declarationLine = number, ]
      [ readOnly = bool, ]
    },
    ...
  }

Spring.GetConfigInt ( string name [, number default ] )
return: nil | number configInt

Spring.GetConfigFloat ( string name [, number default ] )
return: nil | number configFloat

New in version 104.0

Spring.GetConfigString ( string name [, number default ] )
return: nil | string configString

FPS & GetDrawFrame

Spring.GetFPS ( )
return: number fps

Spring.GetDrawFrame ( )
return: number low_16bit, number high_16bit

Spring.GetVideoCapturingMode ( )
return: bool videoCaptureAllowed

New in version 104.0

Time

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

New in version 98.0

Spring.GetGameState ( )
return: bool finishedLoading, bool loadedFromSave, bool locallyPaused, bool laggingWrtExpectedFromSimtime

New in version 105.0

Spring.GetFrameTimeOffset ( )
return: nil | number offset

Spring.GetLastUpdateSeconds ( )
return: nil | number lastUpdateSeconds

Spring.GetHasLag ( )
return: bool hasLag

Spring.GetTimer ( )
return: timer

Spring.GetFrameTimer ( )
return: timer

New in version 102.0
Get a timer for the start of the frame, this should give better results for camera interpolations.

Spring.DiffTimers ( timer cur, timer ago [, bool inMilliseconds ] )
return: number seconds

New in version 95.0
Optional third argument (boolean) to return dt in milliseconds.

Rendering

Spring.GetMapSquareTexture ( number texSqrX, number texSqrY, number texMipLvl, string luaTexName )
return: bool success

Logging

Spring.GetLogSections ( )
return: table logSections = { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }

Misc

Spring.GetClipboard ( )
return: string text

New in version 98.0