Module UnsyncedRead

Callouts to get state


See also:

Decals

Spring.GetAllGroundDecals
Spring.GetGroundDecalMiddlePos
Spring.GetDecalQuadPos
Spring.GetGroundDecalSizeAndHeight
Spring.GetGroundDecalRotation
Spring.GetGroundDecalTexture
Spring.GetDecalTextures
Spring.SetGroundDecalTextureParams
Spring.GetGroundDecalAlpha
Spring.GetGroundDecalNormal
Spring.GetGroundDecalTint
Spring.GetGroundDecalMisc
Spring.GetGroundDecalCreationFrame
Spring.GetGroundDecalOwner
Spring.GetGroundDecalType

Misc

Spring.GetUnitTransformMatrix
Spring.GetFeatureTransformMatrix
Spring.GetSyncedGCInfo

Replay

Spring.IsReplay
Spring.GetReplayLength

Game/Menu Name

Spring.GetGameName
Spring.GetMenuName

Profiling

Spring.GetProfilerTimeRecord
Spring.GetProfilerRecordNames
Spring.GetLuaMemUsage
Spring.GetVidMemUsage

Class Timer

Spring.GetTimer
Get a timer with millisecond resolution
Spring.GetTimerMicros
Get a timer with microsecond resolution
Spring.GetFrameTimer
Get a timer for the start of the frame
Spring.DiffTimers

Screen/Rendering Info

Spring.GetNumDisplays
Spring.GetViewGeometry
Get main view geometry (map and game rendering)
Spring.GetDualViewGeometry
Get dual view geometry (minimap when enabled)
Spring.GetWindowGeometry
Get main window geometry
Spring.GetWindowDisplayMode
Get main window display mode
Spring.GetScreenGeometry
Get screen geometry
Spring.GetMiniMapGeometry
Get minimap geometry
Spring.GetMiniMapRotation
Get minimap rotation
Spring.GetMiniMapDualScreen
Spring.GetSelectionBox
Get vertices from currently active selection box
Spring.GetDrawSelectionInfo
Spring.IsAboveMiniMap
Spring.GetDrawFrame
Spring.GetFrameTimeOffset
Spring.GetLastUpdateSeconds
Spring.GetVideoCapturingMode

Unit attributes

Spring.IsUnitAllied
Spring.IsUnitSelected
Spring.GetUnitLuaDraw
Spring.GetUnitNoDraw
Spring.GetUnitEngineDrawMask
Spring.GetUnitAlwaysUpdateMatrix
Spring.GetUnitDrawFlag
Spring.GetUnitNoMinimap
Spring.GetUnitNoSelect
Spring.UnitIconGetDraw
Spring.GetUnitSelectionVolumeData

Feature attributes

Spring.GetFeatureLuaDraw
Spring.GetFeatureNoDraw
Spring.GetFeatureEngineDrawMask
Spring.GetFeatureAlwaysUpdateMatrix
Spring.GetFeatureDrawFlag
Spring.GetFeatureSelectionVolumeData

Inview

Spring.IsUnitInView
Spring.IsUnitVisible
Spring.IsUnitIcon
Spring.IsAABBInView
Spring.IsSphereInView
Spring.GetUnitViewPosition
Spring.GetVisibleUnits
Spring.GetVisibleFeatures
Spring.GetVisibleProjectiles
Spring.GetRenderUnits
Spring.GetRenderUnitsDrawFlagChanged
Spring.GetRenderFeatures
Spring.GetRenderFeaturesDrawFlagChanged
Spring.ClearUnitsPreviousDrawFlag
Spring.ClearFeaturesPreviousDrawFlag
Spring.GetUnitsInScreenRectangle
Get units inside a rectangle area on the map
Spring.GetFeaturesInScreenRectangle
Get features inside a rectangle area on the map
Spring.GetLocalPlayerID
Spring.GetLocalTeamID
Spring.GetLocalAllyTeamID
Spring.GetSpectatingState
Spring.GetSelectedUnits
Spring.GetSelectedUnitsSorted
Get selected units aggregated by unitDefID
Spring.GetSelectedUnitsCounts
Get an aggregate count of selected units per unitDefID
Spring.GetSelectedUnitsCount
Returns the amount of selected units
Spring.GetBoxSelectionByEngine
Get if selection box is handled by engine
Spring.IsGUIHidden
Spring.HaveShadows
Spring.HaveAdvShading
Spring.GetWaterMode
Spring.GetMapDrawMode
Spring.GetMapSquareTexture
rgb
Color triple (RGB)
Spring.GetLosViewColors
Spring.GetNanoProjectileParams
Spring.GetCameraNames
Get available cameras
camState
Parameters for camera state
Spring.GetCameraState
Spring.GetCameraPosition
Spring.GetCameraDirection
Spring.GetCameraRotation
Spring.GetCameraFOV
xyz
Cartesian triple (XYZ)
Spring.GetCameraVectors
Spring.WorldToScreenCoords
Spring.TraceScreenRay
Get information about a ray traced from screen to world position
Spring.GetPixelDir
Spring.GetTeamColor
Spring.GetTeamOrigColor
Spring.GetDrawSeconds

Sound

Spring.GetSoundStreamTime
Spring.GetSoundEffectParams

Game Speed

Spring.GetFPS
Spring.GetGameSpeed
Spring.GetGameState

Commands

Spring.GetActiveCommand
Spring.GetDefaultCommand
cmdDesc
Command Description
Spring.GetActiveCmdDescs
Spring.GetActiveCmdDesc
Spring.GetCmdDescIndex
Spring.GetBuildFacing
Spring.GetBuildSpacing
Spring.GetGatherMode
Spring.GetActivePage

Mouse State

Spring.GetMouseState
Spring.GetMouseCursor
Spring.GetMouseStartPosition

Text

Spring.GetClipboard
Spring.IsUserWriting

Console

Spring.GetLastMessagePositions
Spring.GetConsoleBuffer
Spring.GetCurrentTooltip

Key Input

Spring.GetKeyFromScanSymbol
Spring.GetKeyState
Spring.GetModKeyState
Spring.GetPressedKeys
Spring.GetPressedScans
Spring.GetInvertQueueKey
Spring.GetKeyCode
Spring.GetKeySymbol
Spring.GetScanSymbol
keybindingSpec
Keybinding spec
Spring.GetKeyBindings
Spring.GetActionHotKeys

Unit Groups

Spring.GetGroupList
Spring.GetSelectedGroup
Spring.GetUnitGroup
Spring.GetGroupUnits
Spring.GetGroupUnitsSorted
Spring.GetGroupUnitsCounts
Spring.GetGroupUnitsCount

Team/Player Info

rosterSpec
Roster spec
Spring.GetPlayerRoster
Spring.GetPlayerTraffic
Spring.GetPlayerStatistics

Configuration

configSpec
Configuration spec
Spring.GetConfigParams
Spring.GetConfigInt
Spring.GetConfigFloat
Spring.GetConfigString
Spring.GetLogSections

Decals


Spring.GetAllGroundDecals()

Returns:

  1. {[number],...} decalIDs

Spring.GetGroundDecalMiddlePos(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or number posX
  2. number posZ

Spring.GetDecalQuadPos(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or number posTL.x
  2. number posTL.z
  3. number posTR.x
  4. number posTR.z
  5. number posBR.x
  6. number posBR.z
  7. number posBL.x
  8. number posBL.z

Spring.GetGroundDecalSizeAndHeight(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or number sizeX
  2. number sizeY
  3. number projCubeHeight

Spring.GetGroundDecalRotation(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or number rotation in radians

Spring.GetGroundDecalTexture(decalID[, isMainTex=true])

Parameters:

  1. decalID number
  2. isMainTex bool If false, it gets the normals/glow map (default true)

Returns:

  1. nil or string texture

Spring.GetDecalTextures([isMainTex=true])

Parameters:

  1. isMainTex bool If false, it gets the texture for normals/glow maps (default true)

Returns:

  1. {[string],...} textureNames All textures on the atlas and available for use in SetGroundDecalTexture

Spring.SetGroundDecalTextureParams(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or number texWrapDistance if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos
  2. number texTraveledDistance shifts the texture repetition defined by texWrapFactor so the texture of a next line in the continuous multiline can start where the previous finished. For that it should collect all elmo lengths of the previously set multiline segments.

Spring.GetGroundDecalAlpha(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or number alpha Between 0 and 1
  2. number alphaFalloff Between 0 and 1, per second

Spring.GetGroundDecalNormal(decalID)

If all three equal 0, the decal follows the normals of ground at midpoint

Parameters:

  1. decalID number

Returns:

  1. nil or number normal.x
  2. number normal.y
  3. number normal.z

Spring.GetGroundDecalTint(decalID)

Gets the tint of the ground decal. A color of (0.5, 0.5, 0.5, 0.5) is effectively no tint

Parameters:

  1. decalID number

Returns:

  1. nil or number tintR
  2. number tintG
  3. number tintB
  4. number tintA

Spring.GetGroundDecalMisc(decalID)

Returns less important parameters of a ground decal

Parameters:

  1. decalID number

Returns:

  1. nil or number dotElimExp
  2. number refHeight
  3. number minHeight
  4. number maxHeight
  5. number forceHeightMode

Spring.GetGroundDecalCreationFrame(decalID)

Min can be not equal to max for "gradient" style decals, e.g. unit tracks

Parameters:

  1. decalID number

Returns:

  1. nil or number creationFrameMin
  2. number creationFrameMax

Spring.GetGroundDecalOwner(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or number unitID|number featureID(+MAX_UNITS)

Spring.GetGroundDecalType(decalID)

Parameters:

  1. decalID number

Returns:

  1. nil or string type "explosion"|"plate"|"lua"|"track"|"unknown"

Misc


Spring.GetUnitTransformMatrix(unitID)

Parameters:

  1. unitID number

Returns:

  1. number or nil m11 nil when unitID cannot be parsed
  2. number m12
  3. number m13
  4. number m14
  5. number m21
  6. number m22
  7. number m23
  8. number m24
  9. number m31
  10. number m32
  11. number m33
  12. number m34
  13. number m41
  14. number m42
  15. number m43
  16. number m44

Spring.GetFeatureTransformMatrix(featureID)

Parameters:

  1. featureID number

Returns:

  1. number or nil m11 nil when featureID cannot be parsed
  2. number m12
  3. number m13
  4. number m14
  5. number m21
  6. number m22
  7. number m23
  8. number m24
  9. number m31
  10. number m32
  11. number m33
  12. number m34
  13. number m41
  14. number m42
  15. number m43
  16. number m44

Spring.GetSyncedGCInfo([collectGC=false])

Parameters:

  1. collectGC bool collect before returning metric (default false)

Returns:

  1. nil or number GC values are expressed in Kbytes: #bytes/2^10

Replay


Spring.IsReplay()

Returns:

  1. nil or bool isReplay

Spring.GetReplayLength()

Returns:

  1. nil or number timeInSeconds

Game/Menu Name


Spring.GetGameName()

Returns:

  1. string name

Spring.GetMenuName()

Returns:

  1. string name name .. version from Modinfo.lua. E.g. "Spring: 1944 test-5640-ac2d15b".

Profiling


Spring.GetProfilerTimeRecord(profilerName[, frameData=false])

Parameters:

  1. profilerName string
  2. frameData bool (default false)

Returns:

  1. number total in ms
  2. number current in ms
  3. number max_dt
  4. number time_pct
  5. number peak_pct
  6. nil or {[number]=number,...} frameData where key is the frame index and value is duration

Spring.GetProfilerRecordNames()

Returns:

  1. {string,...} profilerNames

Spring.GetLuaMemUsage()

Returns:

  1. number luaHandleAllocedMem in kilobytes
  2. number luaHandleNumAllocs divided by 1000
  3. number luaGlobalAllocedMem in kilobytes
  4. number luaGlobalNumAllocs divided by 1000
  5. number luaUnsyncedGlobalAllocedMem in kilobytes
  6. number luaUnsyncedGlobalNumAllocs divided by 1000
  7. number luaSyncedGlobalAllocedMem in kilobytes
  8. number luaSyncedGlobalNumAllocs divided by 1000

Spring.GetVidMemUsage()

Returns:

  1. number usedMem in MB
  2. number availableMem in MB

Class Timer

Spring.GetTimer()

Get a timer with millisecond resolution

Returns:

  1. Timer

Spring.GetTimerMicros()

Get a timer with microsecond resolution

Returns:

  1. Timer

Spring.GetFrameTimer([lastFrameTime=false])

Get a timer for the start of the frame

This should give better results for camera interpolations

Parameters:

  1. lastFrameTime bool whether to use last frame time instead of last frame start (default false)

Returns:

  1. Timer

Spring.DiffTimers(endTimer, startTimer[, returnMs=false[, fromMicroSecs=false]])

Parameters:

  1. endTimer Timer
  2. startTimer Timer
  3. returnMs bool whether to return timeAmount in milliseconds as opposed to seconds (default false)
  4. fromMicroSecs bool whether timers are in microseconds instead of milliseconds (default false)

Returns:

  1. number timeAmount

Screen/Rendering Info


Spring.GetNumDisplays()

Returns:

  1. number numDisplays as returned by SDL_GetNumVideoDisplays

Spring.GetViewGeometry()

Get main view geometry (map and game rendering)

Returns:

  1. number viewSizeX in px
  2. number viewSizeY in px
  3. number viewPosX offset from leftmost screen left border in px
  4. number viewPosY offset from bottommost screen bottom border in px

Spring.GetDualViewGeometry()

Get dual view geometry (minimap when enabled)

Returns:

  1. number dualViewSizeX in px
  2. number dualViewSizeY in px
  3. number dualViewPosX offset from leftmost screen left border in px
  4. number dualViewPosY offset from bottommost screen bottom border in px

Spring.GetWindowGeometry()

Get main window geometry

Returns:

  1. number winSizeX in px
  2. number winSizeY in px
  3. number winPosX in px
  4. number winPosY in px
  5. number windowBorderTop in px
  6. number windowBorderLeft in px
  7. number windowBorderBottom in px
  8. number windowBorderRight in px

Spring.GetWindowDisplayMode()

Get main window display mode

Returns:

  1. number width in px
  2. number height in px
  3. number bits per pixel
  4. number refresh rate in Hz

Spring.GetScreenGeometry([displayIndex=-1[, queryUsable=false]])

Get screen geometry

Parameters:

  1. displayIndex number (default -1)
  2. queryUsable bool (default false)

Returns:

  1. number screenSizeX in px
  2. number screenSizeY in px
  3. number screenPosX in px
  4. number screenPosY in px
  5. number windowBorderTop in px
  6. number windowBorderLeft in px
  7. number windowBorderBottom in px
  8. number windowBorderRight in px
  9. nil or number screenUsableSizeX in px
  10. nil or number screenUsableSizeY in px
  11. nil or number screenUsablePosX in px
  12. nil or number screenUsablePosY in px

Spring.GetMiniMapGeometry()

Get minimap geometry

Returns:

  1. number minimapPosX in px
  2. number minimapPosY in px
  3. number minimapSizeX in px
  4. number minimapSizeY in px
  5. bool minimized
  6. bool maximized

Spring.GetMiniMapRotation()

Get minimap rotation

Returns:

  1. number amount in radians

Spring.GetMiniMapDualScreen()

Returns:

  1. string or false position "left"|"right" when dual screen is enabled, false when not

Spring.GetSelectionBox()

Get vertices from currently active selection box

Returns nil when selection box is inactive

Returns:

  1. nil or number left
  2. nil or number top
  3. nil or number right
  4. nil or number bottom

See also:

Spring.GetDrawSelectionInfo()

Returns:

  1. bool

Spring.IsAboveMiniMap(x, y)

Parameters:

  1. x number
  2. y number

Returns:

  1. bool isAbove

Spring.GetDrawFrame()

Returns:

  1. number low_16bit
  2. number high_16bit

Spring.GetFrameTimeOffset()

Ideally, when running 30hz sim, and 60hz rendering, the draw frames should have and offset of either 0.0 frames, or 0.5 frames. When draw frames are not integer multiples of sim frames, some interpolation happens, and this timeoffset shows how far along it is.

Returns:

  1. nil or number offset of the current draw frame from the last sim frame, expressed in fractions of a frame

Spring.GetLastUpdateSeconds()

Returns:

  1. nil or number lastUpdateSeconds

Spring.GetVideoCapturingMode()

Returns:

  1. bool allowRecord

Unit attributes


Spring.IsUnitAllied(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool isAllied nil with unitID cannot be parsed

Spring.IsUnitSelected(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool isSelected nil when unitID cannot be parsed

Spring.GetUnitLuaDraw(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool draw nil when unitID cannot be parsed

Spring.GetUnitNoDraw(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool nil when unitID cannot be parsed

Spring.GetUnitEngineDrawMask(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool nil when unitID cannot be parsed

Spring.GetUnitAlwaysUpdateMatrix(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool nil when unitID cannot be parsed

Spring.GetUnitDrawFlag(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or number nil when unitID cannot be parsed

Spring.GetUnitNoMinimap(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool nil when unitID cannot be parsed

Spring.GetUnitNoSelect(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool nil when unitID cannot be parsed

Spring.UnitIconGetDraw(unitID, nil)

Parameters:

  1. unitID number
  2. nil nil or bool when unitID is invalid

Spring.GetUnitSelectionVolumeData(unitID)

Parameters:

  1. unitID number

Returns:

  1. number or nil scaleX nil when unitID cannot be parsed
  2. number scaleY
  3. number scaleZ
  4. number offsetX
  5. number offsetY
  6. number offsetZ
  7. number volumeType
  8. number useContHitTest
  9. number getPrimaryAxis
  10. bool ignoreHits

Feature attributes


Spring.GetFeatureLuaDraw(featureID)

Parameters:

  1. featureID number

Returns:

  1. nil or bool nil when featureID cannot be parsed

Spring.GetFeatureNoDraw(featureID)

Parameters:

  1. featureID number

Returns:

  1. nil or bool nil when featureID cannot be parsed

Spring.GetFeatureEngineDrawMask(featureID)

Parameters:

  1. featureID number

Returns:

  1. nil or bool nil when featureID cannot be parsed

Spring.GetFeatureAlwaysUpdateMatrix(featureID)

Parameters:

  1. featureID number

Returns:

  1. nil or bool nil when featureID cannot be parsed

Spring.GetFeatureDrawFlag(featureID)

Parameters:

  1. featureID number

Returns:

  1. nil or number nil when featureID cannot be parsed

Spring.GetFeatureSelectionVolumeData(featureID)

Parameters:

  1. featureID number

Returns:

  1. number or nil scaleX nil when unitID cannot be parsed
  2. number scaleY
  3. number scaleZ
  4. number offsetX
  5. number offsetY
  6. number offsetZ
  7. number volumeType
  8. number useContHitTest
  9. number getPrimaryAxis
  10. bool ignoreHits

Inview


Spring.IsUnitInView(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool inView nil when unitID cannot be parsed

Spring.IsUnitVisible(unitID[, radius], checkIcon)

Parameters:

  1. unitID number
  2. radius number unitRadius when not specified (optional)
  3. checkIcon bool

Returns:

  1. nil or bool isVisible nil when unitID cannot be parsed

Spring.IsUnitIcon(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or bool isUnitIcon nil when unitID cannot be parsed

Spring.IsAABBInView(minX, minY, minZ, maxX, maxY, maxZ)

Parameters:

  1. minX number
  2. minY number
  3. minZ number
  4. maxX number
  5. maxY number
  6. maxZ number

Returns:

  1. bool inView

Spring.IsSphereInView(posX, posY, posZ[, radius=0])

Parameters:

  1. posX number
  2. posY number
  3. posZ number
  4. radius number (default 0)

Returns:

  1. bool inView

Spring.GetUnitViewPosition(unitID[, midPos=false])

Parameters:

  1. unitID number
  2. midPos bool (default false)

Returns:

  1. number or nil x nil when unitID cannot be parsed
  2. number y
  3. number z

Spring.GetVisibleUnits([teamID=-1[, radius=30[, icons=true]]])

Parameters:

  1. teamID number (default -1)
  2. radius number (default 30)
  3. icons bool (default true)

Returns:

  1. nil or {[number],...} unitIDs

Spring.GetVisibleFeatures([teamID=-1[, radius=30[, icons=true[, geos=true]]]])

Parameters:

  1. teamID number (default -1)
  2. radius number (default 30)
  3. icons bool (default true)
  4. geos bool (default true)

Returns:

  1. nil or {[number],...} featureIDs

Spring.GetVisibleProjectiles([allyTeamID=-1[, addSyncedProjectiles=true[, addWeaponProjectiles=true[, addPieceProjectiles=true]]]])

Parameters:

  1. allyTeamID number (default -1)
  2. addSyncedProjectiles bool (default true)
  3. addWeaponProjectiles bool (default true)
  4. addPieceProjectiles bool (default true)

Returns:

  1. nil or {[number],...} projectileIDs

Spring.GetRenderUnits()

Spring.GetRenderUnitsDrawFlagChanged()

Spring.GetRenderFeatures()

Spring.GetRenderFeaturesDrawFlagChanged()

Spring.ClearUnitsPreviousDrawFlag()

Returns:

  1. nil

Spring.ClearFeaturesPreviousDrawFlag()

Returns:

  1. nil

Spring.GetUnitsInScreenRectangle(left, top, right, bottom[, allegiance=-1])

Get units inside a rectangle area on the map

Parameters:

  1. left number
  2. top number
  3. right number
  4. bottom number
  5. allegiance number teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4 (default -1)

Returns:

  1. nil or {[number],...} unitIDs

Spring.GetFeaturesInScreenRectangle(left, top, right, bottom)

Get features inside a rectangle area on the map

Parameters:

  1. left number
  2. top number
  3. right number
  4. bottom number

Returns:

  1. nil or {[number],...} featureIDs

Spring.GetLocalPlayerID()

Returns:

  1. number playerID

Spring.GetLocalTeamID()

Returns:

  1. number teamID

Spring.GetLocalAllyTeamID()

Returns:

  1. number allyTeamID

Spring.GetSpectatingState()

Returns:

  1. bool spectating
  2. bool spectatingFullView
  3. bool spectatingFullSelect

Spring.GetSelectedUnits()

Returns:

  1. {[number],...} unitIDs

Spring.GetSelectedUnitsSorted()

Get selected units aggregated by unitDefID

Returns:

  1. {[number]={number,...},...} where keys are unitDefIDs and values are unitIDs
  2. n the number of unitDefIDs

Spring.GetSelectedUnitsCounts()

Get an aggregate count of selected units per unitDefID

Returns:

  1. {[number]=number,...} unitsCounts where keys are unitDefIDs and values are counts
  2. n the number of unitDefIDs

Spring.GetSelectedUnitsCount()

Returns the amount of selected units

Returns:

  1. number selectedUnitsCount

Spring.GetBoxSelectionByEngine()

Get if selection box is handled by engine

Returns:

  1. bool when true engine won't select units inside selection box when released

See also:

Spring.IsGUIHidden()

Returns:

  1. bool

Spring.HaveShadows()

Returns:

  1. shadowsLoaded

Spring.HaveAdvShading()

Returns:

  1. bool useAdvShading
  2. bool groundUseAdvShading

Spring.GetWaterMode()

Returns:

  1. number waterRendererID
  2. string waterRendererName

See also:

Spring.GetMapDrawMode()

Returns:

  1. nil or string "normal"|"height"|"metal"|"pathTraversability"|"los"

Spring.GetMapSquareTexture(texSquareX, texSquareY, lodMin, luaTexName[, lodMax=lodMin])

Parameters:

  1. texSquareX number
  2. texSquareY number
  3. lodMin number
  4. luaTexName string
  5. lodMax number (default lodMin)

Returns:

  1. nil or bool success

rgb

Color triple (RGB)

Fields:

  1. r number
  2. g number
  3. b number

Spring.GetLosViewColors()

Returns:

  1. { always=rgb, LOS=rgb, radar=rgb, jam=rgb, radar2=rgb }

Spring.GetNanoProjectileParams()

Returns:

  1. number rotVal in degrees
  2. number rotVel in degrees
  3. number rotAcc in degrees
  4. number rotValRng in degrees
  5. number rotVelRng in degrees
  6. number rotAccRng in degrees

Spring.GetCameraNames()

Get available cameras

Returns:

  1. {[string] = number} where keys are names and values are indices

camState

Parameters for camera state

Highly dependent on the type of the current camera controller

Fields:

  1. name string "ta"|"spring"|"rot"|"ov"|"free"|"fps"|"dummy"
  2. mode number the camera mode: 0 (fps), 1 (ta), 2 (spring), 3 (rot), 4 (free), 5 (ov), 6 (dummy)
  3. fov number
  4. px number Position X of the ground point in screen center
  5. py number Position Y of the ground point in screen center
  6. pz number Position Z of the ground point in screen center
  7. dx number Camera direction vector X
  8. dy number Camera direction vector Y
  9. dz number Camera direction vector Z
  10. rx number Camera rotation angle on X axis (spring)
  11. ry number Camera rotation angle on Y axis (spring)
  12. rz number Camera rotation angle on Z axis (spring)
  13. angle number Camera rotation angle on X axis (aka tilt/pitch) (ta)
  14. flipped number -1 for when south is down, 1 for when north is down (ta)
  15. dist number Camera distance from the ground (spring)
  16. height number Camera distance from the ground (ta)
  17. oldHeight number Camera distance from the ground, cannot be changed (rot)

Spring.GetCameraState([useReturns=true])

Parameters:

  1. useReturns bool when true return multiple values instead of table (default true)

Returns:

  1. any or camState ret1
  2. any or nil ret2
  3. any or nil retn

Spring.GetCameraPosition()

Returns:

  1. posX
  2. posY
  3. posZ

Spring.GetCameraDirection()

Returns:

  1. dirX
  2. dirY
  3. dirZ

Spring.GetCameraRotation()

Returns:

  1. rotX in radians
  2. rotY in radians
  3. rotZ in radians

Spring.GetCameraFOV()

Returns:

  1. number vFOV
  2. number hFOV

xyz

Cartesian triple (XYZ)

Fields:

  1. x number
  2. y number
  3. z number

Spring.GetCameraVectors()

Returns:

  1. { forward = xyz, up = xyz, right = xyz, topFrustumPlane = xyz, botFrustumPlane = xyz, lftFrustumPlane = xyz, rgtFrustumPlane = xyz }

Spring.WorldToScreenCoords(x, y, z)

Parameters:

  1. x number
  2. y number
  3. z number

Returns:

  1. viewPortX
  2. viewPortY
  3. viewPortZ

Spring.TraceScreenRay(screenX, screenY[, onlyCoords=false[, useMinimap=false[, includeSky=false[, ignoreWater=false[, heightOffset=0]]]]])

Get information about a ray traced from screen to world position

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.

Parameters:

  1. screenX number position on x axis in mouse coordinates (origin on left border of view)
  2. screenY number position on y axis in mouse coordinates (origin on top border of view)
  3. onlyCoords bool return only description (1st return value) and coordinates (2nd return value) (default false)
  4. useMinimap bool if position arguments are contained by minimap, use the minimap corresponding world position (default false)
  5. includeSky bool (default false)
  6. ignoreWater bool (default false)
  7. heightOffset number (default 0)

Returns:

  1. nil or string description of traced position
  2. nil, number, string or xyz unitID or feature, position triple when onlyCoords=true
  3. nil, number or string featureID or ground
  4. nil or xyz coords

Spring.GetPixelDir(x, y)

Parameters:

  1. x number
  2. y number

Returns:

  1. dirX
  2. dirY
  3. dirZ

Spring.GetTeamColor(teamID)

Parameters:

  1. teamID number

Returns:

  1. nil or number r factor from 0 to 1
  2. nil or number g factor from 0 to 1
  3. nil or number b factor from 0 to 1
  4. nil or number a factor from 0 to 1

Spring.GetTeamOrigColor(teamID)

Parameters:

  1. teamID number

Returns:

  1. nil or number r factor from 0 to 1
  2. nil or number g factor from 0 to 1
  3. nil or number b factor from 0 to 1
  4. nil or number a factor from 0 to 1

Spring.GetDrawSeconds()

Returns:

  1. time in seconds

Sound


Spring.GetSoundStreamTime()

Returns:

  1. number playTime
  2. number time

Spring.GetSoundEffectParams()

Game Speed


Spring.GetFPS()

Returns:

  1. number fps

Spring.GetGameSpeed()

Returns:

  1. number wantedSpeedFactor
  2. number speedFactor
  3. bool paused

Spring.GetGameState([maxLatency=500])

Parameters:

  1. maxLatency number used for isSimLagging return parameter (default 500)

Returns:

  1. bool doneLoading
  2. bool isSavedGame
  3. bool isClientPaused
  4. bool isSimLagging

Commands


Spring.GetActiveCommand()

Returns:

  1. nil or number cmdIndex
  2. nil or number cmdID
  3. nil or number cmdType
  4. nil or string cmdName

Spring.GetDefaultCommand()

Returns:

  1. nil or number cmdIndex
  2. nil or number cmdID
  3. nil or number cmdType
  4. nil or string cmdName

cmdDesc

Command Description

Contains data about a command

Fields:

  1. id number
  2. type number
  3. name string
  4. action string
  5. tooltip string
  6. texture string
  7. cursor string
  8. queueing bool
  9. hidden bool
  10. disabled bool
  11. showUnique bool
  12. onlyTexture bool
  13. params {[string],...}

Spring.GetActiveCmdDescs()

Returns:

  1. {[cmdDesc],...} cmdDescs

Spring.GetActiveCmdDesc(cmdIndex)

Parameters:

  1. cmdIndex number

Returns:

  1. nil or cmdDesc

Spring.GetCmdDescIndex(cmdID)

Parameters:

  1. cmdID number

Returns:

  1. nil or number cmdDescIndex

Spring.GetBuildFacing()

Returns:

  1. number buildFacing

Spring.GetBuildSpacing()

Returns:

  1. number buildSpacing

Spring.GetGatherMode()

Returns:

  1. number gatherMode

Spring.GetActivePage()

Returns:

  1. number activePage
  2. number maxPage

Mouse State


Spring.GetMouseState()

Returns:

  1. number x
  2. number y
  3. number lmbPressed left mouse button pressed
  4. number mmbPressed middle mouse button pressed
  5. number rmbPressed right mouse button pressed
  6. bool offscreen
  7. bool mmbScroll

Spring.GetMouseCursor()

Returns:

  1. string cursorName
  2. number cursorScale

Spring.GetMouseStartPosition(button)

Parameters:

  1. button number

Returns:

  1. number x
  2. number y
  3. number camPosX
  4. number camPosY
  5. number camPosZ
  6. number dirX
  7. number dirY
  8. number dirZ

Text


Spring.GetClipboard()

Returns:

  1. string text

Spring.IsUserWriting()

Returns:

  1. bool

Console


Spring.GetLastMessagePositions()

Returns:

  1. {xyz,...} message positions

Spring.GetConsoleBuffer(maxLines)

Parameters:

  1. maxLines number

Returns:

  1. nil or {{text=string,priority=number},...} pair array of (text, priority)

Spring.GetCurrentTooltip()

Returns:

  1. string tooltip

Key Input


Spring.GetKeyFromScanSymbol(scanSymbol)

Parameters:

  1. scanSymbol string

Returns:

  1. string keyName

Spring.GetKeyState(keyCode)

Parameters:

  1. keyCode number

Returns:

  1. bool pressed

Spring.GetModKeyState()

Returns:

  1. bool alt
  2. bool ctrl
  3. bool meta
  4. bool shift

Spring.GetPressedKeys()

Returns:

  1. {[number or string]=true,...} where keys are keyCodes or key names

Spring.GetPressedScans()

Returns:

  1. {[number or string]=true,...} where keys are scanCodes or scan names

Spring.GetInvertQueueKey()

Returns:

  1. nil or number queueKey

Spring.GetKeyCode(keySym)

Parameters:

  1. keySym string

Returns:

  1. number keyCode

Spring.GetKeySymbol(keyCode)

Parameters:

  1. keyCode number

Returns:

  1. string keyCodeName
  2. string keyCodeDefaultName name when there are not aliases

Spring.GetScanSymbol(scanCode)

Parameters:

  1. scanCode number

Returns:

  1. string scanCodeName
  2. string scanCodeDefaultName name when there are not aliases

keybindingSpec

Keybinding spec

Contains data about a keybinding

Fields:

  1. command string
  2. extra string
  3. boundWith string

Spring.GetKeyBindings([keySet1[, keySet2]])

Parameters:

  1. keySet1 string filters keybindings bound to this keyset (optional)
  2. keySet2 string OR bound to this keyset (optional)

Returns:

  1. {[keybindingSpec],...}

Spring.GetActionHotKeys(actionName)

Parameters:

  1. actionName string

Returns:

  1. nil or {[string],...} hotkeys

Unit Groups


Spring.GetGroupList()

Returns:

  1. nil or {[number]=number,...} where keys are groupIDs and values are counts

Spring.GetSelectedGroup()

Returns:

  1. number groupID -1 when no group selected

Spring.GetUnitGroup(unitID)

Parameters:

  1. unitID number

Returns:

  1. nil or number groupID

Spring.GetGroupUnits(groupID)

Parameters:

  1. groupID number

Returns:

  1. nil or {[number],...} unitIDs

Spring.GetGroupUnitsSorted(groupID)

Parameters:

  1. groupID number

Returns:

  1. nil or {[number]={[number],...},...} where keys are unitDefIDs and values are unitIDs

Spring.GetGroupUnitsCounts(groupID)

Parameters:

  1. groupID number

Returns:

  1. nil or {[number]=number,...} where keys are unitDefIDs and values are counts

Spring.GetGroupUnitsCount(groupID)

Parameters:

  1. groupID number

Returns:

  1. nil or number groupSize

Team/Player Info


rosterSpec

Roster spec

Contains data about a player

Fields:

  1. name string
  2. playerID number
  3. teamID number
  4. allyTeamID number
  5. spectator bool
  6. cpuUsage number 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
  7. pingTime number if -1, the player is pathfinding

Spring.GetPlayerRoster([sortType[, showPathingPlayers=false]])

Parameters:

  1. sortType number return unsorted if unspecified. Disabled = 0, Allies = 1, TeamID = 2, PlayerName = 3, PlayerCPU = 4, PlayerPing = 5 (optional)
  2. showPathingPlayers bool (default false)

Returns:

  1. nil or {[rosterSpec],...} playerTable

Spring.GetPlayerTraffic(playerID, packetID)

Parameters:

  1. playerID number
  2. packetID number [opt]

Returns:

  1. number traffic

Spring.GetPlayerStatistics(playerID)

Parameters:

  1. playerID number

Returns:

  1. nil or number mousePixels nil when invalid playerID
  2. number mouseClicks
  3. number keyPresses
  4. number numCommands
  5. number unitCommands

Configuration


configSpec

Configuration spec

Contains data about a configuration, only name and type are guaranteed

Fields:

  1. name string
  2. type string
  3. description string
  4. defaultValue string
  5. minimumValue string
  6. maximumValue string
  7. safemodeValue string
  8. declarationFile string
  9. declarationLine string
  10. readOnly bool

Spring.GetConfigParams()

Spring.GetConfigInt(name[, default=0])

Parameters:

  1. name string
  2. default number or nil (default 0)

Returns:

  1. nil or number configInt

Spring.GetConfigFloat(name[, default=0])

Parameters:

  1. name string
  2. default number or nil (default 0)

Returns:

  1. nil or number configFloat

Spring.GetConfigString(name[, default=""])

Parameters:

  1. name string
  2. default string or nil (default "")

Returns:

  1. nil or number configString

Spring.GetLogSections()

Returns:

  1. {[string]=number,...} sections where keys are names and loglevel are values. E.g. { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }