global Spring

---

methods

---

Spring.IsReplay

---

function Spring.IsReplay() -> isReplay boolean?

[source]

Spring.GetReplayLength

---

function Spring.GetReplayLength() -> timeInSeconds number?

[source]

Spring.GetGameName

---

function Spring.GetGameName() -> name string

[source]

Spring.GetMenuName

---

function Spring.GetMenuName() -> name string

@return name - name .. version from Modinfo.lua. E.g. “Spring: 1944 test-5640-ac2d15b”.

[source]

Spring.GetProfilerTimeRecord

---

function Spring.GetProfilerTimeRecord(
  profilerName: string,
  frameData: boolean?
)
 -> total number
 -> current number
 -> max_dt number
 -> time_pct number
 -> peak_pct number
 -> frameData table<number,number>?

@param frameData - (Default: false)

@return total - in ms

@return current - in ms

@return frameData - Table where key is the frame index and value is duration.

[source]

Spring.GetProfilerRecordNames

---

function Spring.GetProfilerRecordNames() -> profilerNames string[]

[source]

Spring.GetLuaMemUsage

---

function Spring.GetLuaMemUsage()
 -> luaHandleAllocedMem number
 -> luaHandleNumAllocs number
 -> luaGlobalAllocedMem number
 -> luaGlobalNumAllocs number
 -> luaUnsyncedGlobalAllocedMem number
 -> luaUnsyncedGlobalNumAllocs number
 -> luaSyncedGlobalAllocedMem number
 -> luaSyncedGlobalNumAllocs number

@return luaHandleAllocedMem - in kilobytes

@return luaHandleNumAllocs - divided by 1000

@return luaGlobalAllocedMem - in kilobytes

@return luaGlobalNumAllocs - divided by 1000

@return luaUnsyncedGlobalAllocedMem - in kilobytes

@return luaUnsyncedGlobalNumAllocs - divided by 1000

@return luaSyncedGlobalAllocedMem - in kilobytes

@return luaSyncedGlobalNumAllocs - divided by 1000

[source]

Spring.GetVidMemUsage

---

function Spring.GetVidMemUsage()
 -> usedMem number
 -> availableMem number

@return usedMem - in MB

@return availableMem - in MB

[source]

Spring.GetTimer

---

function Spring.GetTimer() ->  integer

Get a timer with millisecond resolution

[source]

Spring.GetTimerMicros

---

function Spring.GetTimerMicros() ->  integer

Get a timer with microsecond resolution

[source]

Spring.GetFrameTimer

---

function Spring.GetFrameTimer(lastFrameTime: boolean?) ->  integer

@param lastFrameTime - (Default: false) whether to use last frame time instead of last frame start

Get a timer for the start of the frame

[source]

This should give better results for camera interpolations

Spring.DiffTimers

---

function Spring.DiffTimers(
  endTimer: integer,
  startTimer: integer,
  returnMs: boolean?,
  fromMicroSecs: boolean?
) -> timeAmount number

@param returnMs - (Default: false) whether to return timeAmount in milliseconds as opposed to seconds

@param fromMicroSecs - (Default: false) whether timers are in microseconds instead of milliseconds

[source]

Spring.GetNumDisplays

---

function Spring.GetNumDisplays() -> numDisplays number

@return numDisplays - as returned by SDL_GetNumVideoDisplays

[source]

Spring.GetViewGeometry

---

function Spring.GetViewGeometry()
 -> viewSizeX number
 -> viewSizeY number
 -> viewPosX number
 -> viewPosY number

@return viewSizeX - in px

@return viewSizeY - in px

@return viewPosX - offset from leftmost screen left border in px

@return viewPosY - offset from bottommost screen bottom border in px

Get main view geometry (map and game rendering)

[source]

Spring.GetDualViewGeometry

---

function Spring.GetDualViewGeometry()
 -> dualViewSizeX number
 -> dualViewSizeY number
 -> dualViewPosX number
 -> dualViewPosY number

@return dualViewSizeX - in px

@return dualViewSizeY - in px

@return dualViewPosX - offset from leftmost screen left border in px

@return dualViewPosY - offset from bottommost screen bottom border in px

Get dual view geometry (minimap when enabled)

[source]

Spring.GetWindowGeometry

---

function Spring.GetWindowGeometry()
 -> winSizeX number
 -> winSizeY number
 -> winPosX number
 -> winPosY number
 -> windowBorderTop number
 -> windowBorderLeft number
 -> windowBorderBottom number
 -> windowBorderRight number

@return winSizeX - in px

@return winSizeY - in px

@return winPosX - in px

@return winPosY - in px

@return windowBorderTop - in px

@return windowBorderLeft - in px

@return windowBorderBottom - in px

@return windowBorderRight - in px

Get main window geometry

[source]

Spring.GetWindowDisplayMode

---

function Spring.GetWindowDisplayMode()
 -> width number
 -> height number
 -> bits number
 -> refresh number

@return width - in px

@return height - in px

@return bits - per pixel

@return refresh - rate in Hz

Get main window display mode

[source]

Spring.GetScreenGeometry

---

function Spring.GetScreenGeometry(
  displayIndex: number?,
  queryUsable: boolean?
)
 -> screenSizeX number
 -> screenSizeY number
 -> screenPosX number
 -> screenPosY number
 -> windowBorderTop number
 -> windowBorderLeft number
 -> windowBorderBottom number
 -> windowBorderRight number
 -> screenUsableSizeX number?
 -> screenUsableSizeY number?
 -> screenUsablePosX number?
 -> screenUsablePosY number?

@param displayIndex - (Default: -1)

@param queryUsable - (Default: false)

@return screenSizeX - in px

@return screenSizeY - in px

@return screenPosX - in px

@return screenPosY - in px

@return windowBorderTop - in px

@return windowBorderLeft - in px

@return windowBorderBottom - in px

@return windowBorderRight - in px

@return screenUsableSizeX - in px

@return screenUsableSizeY - in px

@return screenUsablePosX - in px

@return screenUsablePosY - in px

Get screen geometry

[source]

Spring.GetMiniMapGeometry

---

function Spring.GetMiniMapGeometry()
 -> minimapPosX number
 -> minimapPosY number
 -> minimapSizeX number
 -> minimapSizeY number
 -> minimized boolean
 -> maximized boolean

@return minimapPosX - in px

@return minimapPosY - in px

@return minimapSizeX - in px

@return minimapSizeY - in px

Get minimap geometry

[source]

Spring.GetMiniMapRotation

---

function Spring.GetMiniMapRotation() -> amount number

@return amount - in radians

Get minimap rotation

[source]

Spring.GetMiniMapDualScreen

---

function Spring.GetMiniMapDualScreen() -> position ("left"|"right"|false)

@return position - "left" or "right" when dual screen is enabled, otherwise false.

[source]

Spring.GetSelectionBox

---

function Spring.GetSelectionBox()
 -> left number?
 -> top number?
 -> right number?
 -> bottom number?

Get vertices from currently active selection box

[source]

Returns nil when selection box is inactive

@see Spring.GetUnitsInScreenRectangle

Spring.GetDrawSelectionInfo

---

function Spring.GetDrawSelectionInfo() ->  boolean

[source]

Spring.IsAboveMiniMap

---

function Spring.IsAboveMiniMap(
  x: number,
  y: number
) -> isAbove boolean

[source]

Spring.GetDrawFrame

---

function Spring.GetDrawFrame()
 -> low_16bit number
 -> high_16bit number

[source]

Spring.GetFrameTimeOffset

---

function Spring.GetFrameTimeOffset() -> offset number?

@return offset - of the current draw frame from the last sim frame, expressed in fractions of a frame

[source]

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.

Spring.GetLastUpdateSeconds

---

function Spring.GetLastUpdateSeconds() -> lastUpdateSeconds number?

[source]

Spring.GetVideoCapturingMode

---

function Spring.GetVideoCapturingMode() -> allowRecord boolean

[source]

Spring.IsUnitAllied

---

function Spring.IsUnitAllied(unitID: integer) -> isAllied boolean?

@return isAllied - nil with unitID cannot be parsed

[source]

Spring.IsUnitSelected

---

function Spring.IsUnitSelected(unitID: integer) -> isSelected boolean?

@return isSelected - nil when unitID cannot be parsed

[source]

Spring.GetUnitLuaDraw

---

function Spring.GetUnitLuaDraw(unitID: integer) -> draw boolean?

@return draw - nil when unitID cannot be parsed

[source]

Spring.GetUnitNoDraw

---

function Spring.GetUnitNoDraw(unitID: integer) -> nil boolean?

@return nil - when unitID cannot be parsed

[source]

Spring.GetUnitEngineDrawMask

---

function Spring.GetUnitEngineDrawMask(unitID: integer) -> nil boolean?

@return nil - when unitID cannot be parsed

[source]

Spring.GetUnitAlwaysUpdateMatrix

---

function Spring.GetUnitAlwaysUpdateMatrix(unitID: integer) -> nil boolean?

@return nil - when unitID cannot be parsed

[source]

Spring.GetUnitDrawFlag

---

function Spring.GetUnitDrawFlag(unitID: integer) -> nil number?

@return nil - when unitID cannot be parsed

[source]

Spring.GetUnitNoMinimap

---

function Spring.GetUnitNoMinimap(unitID: integer) -> nil boolean?

@return nil - when unitID cannot be parsed

[source]

Spring.GetUnitNoGroup

---

function Spring.GetUnitNoGroup(unitID: integer) -> noGroup boolean?

@return noGroup - true if the unit is not allowed to be added to a group, false if it is allowed to be added to a group, or nil when unitID is not valid.

Check if a unit is not allowed to be added to a group by a player.

[source]

Spring.GetUnitNoSelect

---

function Spring.GetUnitNoSelect(unitID: integer) -> noSelect boolean?

@return noSelect - nil when unitID cannot be parsed.

[source]

Spring.UnitIconGetDraw

---

function Spring.UnitIconGetDraw(unitID: integer) -> drawIcon boolean?

@return drawIcon - true if icon is being drawn, nil when unitID is invalid, otherwise false.

[source]

Spring.GetUnitSelectionVolumeData

---

function Spring.GetUnitSelectionVolumeData(unitID: integer)
 -> scaleX number?
 -> scaleY number
 -> scaleZ number
 -> offsetX number
 -> offsetY number
 -> offsetZ number
 -> volumeType number
 -> useContHitTest number
 -> getPrimaryAxis number
 -> ignoreHits boolean

@return scaleX - nil when unitID cannot be parsed

[source]

Spring.GetFeatureLuaDraw

---

function Spring.GetFeatureLuaDraw(featureID: integer) -> nil boolean?

@return nil - when featureID cannot be parsed

[source]

Spring.GetFeatureNoDraw

---

function Spring.GetFeatureNoDraw(featureID: integer) -> nil boolean?

@return nil - when featureID cannot be parsed

[source]

Spring.GetFeatureEngineDrawMask

---

function Spring.GetFeatureEngineDrawMask(featureID: integer) -> nil boolean?

@return nil - when featureID cannot be parsed

[source]

Spring.GetFeatureAlwaysUpdateMatrix

---

function Spring.GetFeatureAlwaysUpdateMatrix(featureID: integer) -> nil boolean?

@return nil - when featureID cannot be parsed

[source]

Spring.GetFeatureDrawFlag

---

function Spring.GetFeatureDrawFlag(featureID: integer) -> nil number?

@return nil - when featureID cannot be parsed

[source]

Spring.GetFeatureSelectionVolumeData

---

function Spring.GetFeatureSelectionVolumeData(featureID: integer)
 -> scaleX number?
 -> scaleY number
 -> scaleZ number
 -> offsetX number
 -> offsetY number
 -> offsetZ number
 -> volumeType number
 -> useContHitTest number
 -> getPrimaryAxis number
 -> ignoreHits boolean

@return scaleX - nil when unitID cannot be parsed

[source]

Spring.GetUnitTransformMatrix

---

function Spring.GetUnitTransformMatrix(unitID: integer)
 -> m11 number?
 -> m12 number
 -> m13 number
 -> m14 number
 -> m21 number
 -> m22 number
 -> m23 number
 -> m24 number
 -> m31 number
 -> m32 number
 -> m33 number
 -> m34 number
 -> m41 number
 -> m42 number
 -> m43 number
 -> m44 number

@return m11 - nil when unitID cannot be parsed

[source]

Spring.GetFeatureTransformMatrix

---

function Spring.GetFeatureTransformMatrix(featureID: integer)
 -> m11 number?
 -> m12 number
 -> m13 number
 -> m14 number
 -> m21 number
 -> m22 number
 -> m23 number
 -> m24 number
 -> m31 number
 -> m32 number
 -> m33 number
 -> m34 number
 -> m41 number
 -> m42 number
 -> m43 number
 -> m44 number

@return m11 - nil when featureID cannot be parsed

[source]

Spring.IsUnitInView

---

function Spring.IsUnitInView(unitID: integer) -> inView boolean?

@return inView - nil when unitID cannot be parsed

[source]

Spring.IsUnitVisible

---

function Spring.IsUnitVisible(
  unitID: integer,
  radius: number?,
  checkIcon: boolean
) -> isVisible boolean?

@param radius - unitRadius when not specified

@return isVisible - nil when unitID cannot be parsed

[source]

Spring.IsUnitIcon

---

function Spring.IsUnitIcon(unitID: integer) -> isUnitIcon boolean?

@return isUnitIcon - nil when unitID cannot be parsed

[source]

Spring.IsAABBInView

---

function Spring.IsAABBInView(
  minX: number,
  minY: number,
  minZ: number,
  maxX: number,
  maxY: number,
  maxZ: number
) -> inView boolean

[source]

Spring.IsSphereInView

---

function Spring.IsSphereInView(
  posX: number,
  posY: number,
  posZ: number,
  radius: number?
) -> inView boolean

@param radius - (Default: 0)

[source]

Spring.GetUnitViewPosition

---

function Spring.GetUnitViewPosition(
  unitID: integer,
  midPos: boolean?
)
 -> x number?
 -> y number
 -> z number

@param midPos - (Default: false)

@return x - nil when unitID cannot be parsed

[source]

Spring.GetVisibleUnits

---

function Spring.GetVisibleUnits(
  teamID: integer?,
  radius: number?,
  icons: boolean?
) -> unitIDs number[]?

@param teamID - (Default: -1)

@param radius - (Default: 30)

@param icons - (Default: true)

[source]

Spring.GetVisibleFeatures

---

function Spring.GetVisibleFeatures(
  teamID: integer?,
  radius: number?,
  icons: boolean?,
  geos: boolean?
) -> featureIDs number[]?

@param teamID - (Default: -1)

@param radius - (Default: 30)

@param icons - (Default: true)

@param geos - (Default: true)

[source]

Spring.GetVisibleProjectiles

---

function Spring.GetVisibleProjectiles(
  allyTeamID: integer?,
  addSyncedProjectiles: boolean?,
  addWeaponProjectiles: boolean?,
  addPieceProjectiles: boolean?
) -> projectileIDs number[]?

@param allyTeamID - (Default: -1)

@param addSyncedProjectiles - (Default: true)

@param addWeaponProjectiles - (Default: true)

@param addPieceProjectiles - (Default: true)

[source]

Spring.GetRenderUnits

---

function Spring.GetRenderUnits(
  drawMask: DrawMask,
  sendMask: true
)
 -> featureIDs integer[]
 -> drawFlags DrawFlag[]

@param drawMask - (Default: 0) Filter objects by their draw flags.

@param sendMask - Whether to send objects draw flags as second return

[source]

Spring.GetRenderUnits

---

function Spring.GetRenderUnits(
  drawMask: DrawMask,
  sendMask: false?
) -> featureIDs integer[]

@param drawMask - (Default: 0) Filter objects by their draw flags.

@param sendMask - Whether to send objects draw flags as second return

[source]

Spring.GetRenderUnitsDrawFlagChanged

---

function Spring.GetRenderUnitsDrawFlagChanged(sendMask: true)
 -> ids integer[]
 -> unitDrawFlags DrawFlag[]

@param sendMask - Whether to send objects draw flags as second return.

[source]

Gets a list of IDs of units that have had their draw flags changed, and the corresponding flags.

Spring.GetRenderUnitsDrawFlagChanged

---

function Spring.GetRenderUnitsDrawFlagChanged(sendMask: false?) -> ids integer[]

@param sendMask - Whether to send objects draw flags as second return.

[source]

Gets a list of IDs of units that have had their draw flags changed, and the corresponding flags.

Spring.GetRenderFeatures

---

function Spring.GetRenderFeatures(
  drawMask: DrawMask,
  sendMask: true
)
 -> featureIDs integer[]
 -> drawFlags DrawFlag[]

@param drawMask - (Default: 0) Filter objects by their draw flags.

@param sendMask - Whether to send objects draw flags as second return

[source]

Spring.GetRenderFeatures

---

function Spring.GetRenderFeatures(
  drawMask: DrawMask,
  sendMask: false?
) -> featureIDs integer[]

@param drawMask - (Default: 0) Filter objects by their draw flags.

@param sendMask - Whether to send objects draw flags as second return

[source]

Spring.GetRenderFeaturesDrawFlagChanged

---

function Spring.GetRenderFeaturesDrawFlagChanged(sendMask: true)
 -> ids integer[]
 -> unitDrawFlags DrawFlag[]

@param sendMask - Whether to send objects draw flags as second return.

[source]

Gets a list of IDs of features that have had their draw flags changed, and the corresponding flags.

Spring.GetRenderFeaturesDrawFlagChanged

---

function Spring.GetRenderFeaturesDrawFlagChanged(sendMask: false?) -> ids integer[]

@param sendMask - Whether to send objects draw flags as second return.

[source]

Gets a list of IDs of features that have had their draw flags changed, and the corresponding flags.

Spring.ClearUnitsPreviousDrawFlag

---

function Spring.ClearUnitsPreviousDrawFlag()

[source]

Spring.ClearFeaturesPreviousDrawFlag

---

function Spring.ClearFeaturesPreviousDrawFlag()

[source]

Spring.GetUnitsInScreenRectangle

---

function Spring.GetUnitsInScreenRectangle(
  left: number,
  top: number,
  right: number,
  bottom: number,
  allegiance: number?
) -> unitIDs number[]?

@param allegiance - (Default: -1) teamID when > 0, when < 0 one of AllUnits = -1, MyUnits = -2, AllyUnits = -3, EnemyUnits = -4

Get units inside a rectangle area on the map

[source]

Spring.GetFeaturesInScreenRectangle

---

function Spring.GetFeaturesInScreenRectangle(
  left: number,
  top: number,
  right: number,
  bottom: number
) -> featureIDs number[]?

Get features inside a rectangle area on the map

[source]

Spring.GetLocalPlayerID

---

function Spring.GetLocalPlayerID() -> playerID integer

[source]

Spring.GetLocalTeamID

---

function Spring.GetLocalTeamID() -> teamID integer

[source]

Spring.GetLocalAllyTeamID

---

function Spring.GetLocalAllyTeamID() -> allyTeamID integer

[source]

Spring.GetSpectatingState

---

function Spring.GetSpectatingState()
 -> spectating boolean
 -> spectatingFullView boolean
 -> spectatingFullSelect boolean

[source]

Spring.GetSelectedUnits

---

function Spring.GetSelectedUnits() -> unitIDs number[]

[source]

Spring.GetSelectedUnitsSorted

---

function Spring.GetSelectedUnitsSorted()
 -> where table<number,number[]>
 -> the integer

@return where - keys are unitDefIDs and values are unitIDs

@return the - number of unitDefIDs

Get selected units aggregated by unitDefID

[source]

Spring.GetSelectedUnitsCounts

---

function Spring.GetSelectedUnitsCounts()
 -> unitsCounts table<number,number>
 -> the integer

@return unitsCounts - where keys are unitDefIDs and values are counts

@return the - number of unitDefIDs

Get an aggregate count of selected units per unitDefID

[source]

Spring.GetSelectedUnitsCount

---

function Spring.GetSelectedUnitsCount() -> selectedUnitsCount number

Returns the amount of selected units

[source]

Spring.GetBoxSelectionByEngine

---

function Spring.GetBoxSelectionByEngine() -> isHandledByEngine boolean

@return isHandledByEngine - true if the engine will select units inside selection box on release, otherwise false.

Get if selection box is handled by engine.

[source]

@see Spring.SetBoxSelectionByEngine

Spring.IsGUIHidden

---

function Spring.IsGUIHidden() ->  boolean

[source]

Spring.HaveShadows

---

function Spring.HaveShadows() -> shadowsLoaded boolean

[source]

Spring.HaveAdvShading

---

function Spring.HaveAdvShading()
 -> useAdvShading boolean
 -> groundUseAdvShading boolean

[source]

Spring.GetWaterMode

---

function Spring.GetWaterMode()
 -> waterRendererID integer
 -> waterRendererName string

[source]

@see rts/Rendering/Env/IWater.h

Spring.GetMapDrawMode

---

function Spring.GetMapDrawMode() ->  ("normal"|"height"|"metal"|"pathTraversability"|"los")

[source]

Spring.GetMapSquareTexture

---

function Spring.GetMapSquareTexture(
  texSquareX: number,
  texSquareY: number,
  lodMin: number,
  luaTexName: string,
  lodMax: number?
) -> success boolean?

@param lodMax - (Default: lodMin)

[source]

Spring.GetLosViewColors

---

function Spring.GetLosViewColors()
 -> always rgb
 -> LOS rgb
 -> radar rgb
 -> jam rgb
 -> radar2 rgb

[source]

Spring.GetNanoProjectileParams

---

function Spring.GetNanoProjectileParams()
 -> rotVal number
 -> rotVel number
 -> rotAcc number
 -> rotValRng number
 -> rotVelRng number
 -> rotAccRng number

@return rotVal - in degrees

@return rotVel - in degrees

@return rotAcc - in degrees

@return rotValRng - in degrees

@return rotVelRng - in degrees

@return rotAccRng - in degrees

[source]

Spring.GetCameraNames

---

function Spring.GetCameraNames() -> indexByName table<string,integer>

@return indexByName - Table where where keys are names and values are indices.

Get available cameras.

[source]

Spring.GetCameraState

---

function Spring.GetCameraState(useReturns: false) -> cameraState CameraState

[source]

Spring.GetCameraState

---

function Spring.GetCameraState(useReturns: true?)
 -> name CameraName
 -> Fields any

@param useReturns - (Default: true) Return multiple values instead of a table.

@return Fields - depending on current controller mode.

[source]

Spring.GetCameraPosition

---

function Spring.GetCameraPosition()
 -> posX number
 -> posY number
 -> posZ number

[source]

Spring.GetCameraDirection

---

function Spring.GetCameraDirection()
 -> dirX number
 -> dirY number
 -> dirZ number

[source]

Spring.GetCameraRotation

---

function Spring.GetCameraRotation()
 -> rotX number
 -> rotY number
 -> rotZ number

@return rotX - Rotation around X axis in radians.

@return rotY - Rotation around Y axis in radians.

@return rotZ - Rotation around Z axis in radians.

Get camera rotation in radians.

[source]

Spring.GetCameraFOV

---

function Spring.GetCameraFOV()
 -> vFOV number
 -> hFOV number

[source]

Spring.GetCameraVectors

---

function Spring.GetCameraVectors() ->  CameraVectors

[source]

Spring.WorldToScreenCoords

---

function Spring.WorldToScreenCoords(
  x: number,
  y: number,
  z: number
)
 -> viewPortX number
 -> viewPortY number
 -> viewPortZ number

[source]

Spring.TraceScreenRay

---

function Spring.TraceScreenRay(
  screenX: number,
  screenY: number,
  onlyCoords: boolean?,
  useMinimap: boolean?,
  includeSky: boolean?,
  ignoreWater: boolean?,
  heightOffset: number?
)
 -> description string?
 -> unitID (number|string|xyz)?
 -> featureID (number|string)?
 -> coords xyz?

@param screenX - position on x axis in mouse coordinates (origin on left border of view)

@param screenY - position on y axis in mouse coordinates (origin on top border of view)

@param onlyCoords - (Default: false) return only description (1st return value) and coordinates (2nd return value)

@param useMinimap - (Default: false) if position arguments are contained by minimap, use the minimap corresponding world position

@param includeSky - (Default: false)

@param ignoreWater - (Default: false)

@param heightOffset - (Default: 0)

@return description - of traced position

@return unitID - or feature, position triple when onlyCoords=true

@return featureID - or ground

Get information about a ray traced from screen to world position

[source]

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 collision sphere. Per Piece collision and custom collision objects are not supported.

The unit must be selectable, to appear to a screen trace ray.

Spring.GetPixelDir

---

function Spring.GetPixelDir(
  x: number,
  y: number
)
 -> dirX number
 -> dirY number
 -> dirZ number

[source]

Spring.GetTeamColor

---

function Spring.GetTeamColor(teamID: integer)
 -> r number?
 -> g number?
 -> b number?
 -> a number?

@return r - factor from 0 to 1

@return g - factor from 0 to 1

@return b - factor from 0 to 1

@return a - factor from 0 to 1

[source]

Spring.GetTeamOrigColor

---

function Spring.GetTeamOrigColor(teamID: integer)
 -> r number?
 -> g number?
 -> b number?
 -> a number?

@return r - factor from 0 to 1

@return g - factor from 0 to 1

@return b - factor from 0 to 1

@return a - factor from 0 to 1

[source]

Spring.GetDrawSeconds

---

function Spring.GetDrawSeconds() -> time integer

@return time - Time in seconds.

[source]

Spring.GetSoundDevices

---

function Spring.GetSoundDevices() -> devices SoundDeviceSpec[]

@return devices - Sound devices.

[source]

Spring.GetSoundStreamTime

---

function Spring.GetSoundStreamTime()
 -> playTime number
 -> time number

[source]

Spring.GetSoundEffectParams

---

function Spring.GetSoundEffectParams()

[source]

Spring.GetFPS

---

function Spring.GetFPS() -> fps number

[source]

Spring.GetGameSpeed

---

function Spring.GetGameSpeed()
 -> wantedSpeedFactor number
 -> speedFactor number
 -> paused boolean

[source]

Spring.GetGameState

---

function Spring.GetGameState(maxLatency: number?)
 -> doneLoading boolean
 -> isSavedGame boolean
 -> isClientPaused boolean
 -> isSimLagging boolean

@param maxLatency - (Default: 500) used for isSimLagging return parameter

[source]

Spring.GetActiveCommand

---

function Spring.GetActiveCommand()
 -> cmdIndex number?
 -> cmdID integer?
 -> cmdType number?
 -> cmdName string?

[source]

Spring.GetDefaultCommand

---

function Spring.GetDefaultCommand()
 -> cmdIndex integer?
 -> cmdID integer?
 -> cmdType integer?
 -> cmdName string?

[source]

Spring.GetActiveCmdDescs

---

function Spring.GetActiveCmdDescs() -> cmdDescs CommandDescription[]

[source]

Spring.GetActiveCmdDesc

---

function Spring.GetActiveCmdDesc(cmdIndex: integer) ->  CommandDescription?

[source]

Spring.GetCmdDescIndex

---

function Spring.GetCmdDescIndex(cmdID: integer) -> cmdDescIndex integer?

[source]

Spring.GetBuildFacing

---

function Spring.GetBuildFacing() -> buildFacing FacingInteger

[source]

Spring.GetBuildSpacing

---

function Spring.GetBuildSpacing() -> buildSpacing number

[source]

Spring.GetGatherMode

---

function Spring.GetGatherMode() -> gatherMode number

[source]

Spring.GetActivePage

---

function Spring.GetActivePage()
 -> activePage number
 -> maxPage number

[source]

Spring.GetMouseState

---

function Spring.GetMouseState()
 -> x number
 -> y number
 -> lmbPressed number
 -> mmbPressed number
 -> rmbPressed number
 -> offscreen boolean
 -> mmbScroll boolean

@return lmbPressed - left mouse button pressed

@return mmbPressed - middle mouse button pressed

@return rmbPressed - right mouse button pressed

[source]

Spring.GetMouseCursor

---

function Spring.GetMouseCursor()
 -> cursorName string
 -> cursorScale number

[source]

Spring.GetMouseStartPosition

---

function Spring.GetMouseStartPosition(button: number)
 -> x number
 -> y number
 -> camPosX number
 -> camPosY number
 -> camPosZ number
 -> dirX number
 -> dirY number
 -> dirZ number

[source]

Spring.GetMouseButtonsPressed

---

function Spring.GetMouseButtonsPressed(
  button1: integer,
  ...: integer
) -> Pressed boolean ...

@param button1 - Index of the first button.

@param ... - Indices for more buttons.

@return Pressed - status for the buttons.

[source]

Get pressed status for specific buttons.

Spring.GetClipboard

---

function Spring.GetClipboard() -> text string

[source]

Spring.IsUserWriting

---

function Spring.IsUserWriting() ->  boolean

[source]

Spring.GetLastMessagePositions

---

function Spring.GetLastMessagePositions() -> message xyz[]

@return message - positions

[source]

Spring.GetConsoleBuffer

---

function Spring.GetConsoleBuffer(maxLines: number) -> buffer { priority: integer, text: string }[]

[source]

Spring.GetCurrentTooltip

---

function Spring.GetCurrentTooltip() -> tooltip string

[source]

Spring.GetKeyFromScanSymbol

---

function Spring.GetKeyFromScanSymbol(scanSymbol: string) -> keyName string

[source]

Spring.GetKeyState

---

function Spring.GetKeyState(keyCode: number) -> pressed boolean

[source]

Spring.GetModKeyState

---

function Spring.GetModKeyState()
 -> alt boolean
 -> ctrl boolean
 -> meta boolean
 -> shift boolean

[source]

Spring.GetPressedKeys

---

function Spring.GetPressedKeys() -> where table<(number|string),true>

@return where - keys are keyCodes or key names

[source]

Spring.GetPressedScans

---

function Spring.GetPressedScans() -> where table<(number|string),true>

@return where - keys are scanCodes or scan names

[source]

Spring.GetInvertQueueKey

---

function Spring.GetInvertQueueKey() -> queueKey number?

[source]

Spring.GetKeyCode

---

function Spring.GetKeyCode(keySym: string) -> keyCode number

[source]

Spring.GetKeySymbol

---

function Spring.GetKeySymbol(keyCode: number)
 -> keyCodeName string
 -> keyCodeDefaultName string

@return keyCodeDefaultName - name when there are not aliases

[source]

Spring.GetScanSymbol

---

function Spring.GetScanSymbol(scanCode: number)
 -> scanCodeName string
 -> scanCodeDefaultName string

@return scanCodeDefaultName - name when there are not aliases

[source]

Spring.GetKeyBindings

---

function Spring.GetKeyBindings(
  keySet1: string?,
  keySet2: string?
) ->  KeyBinding[]

@param keySet1 - filters keybindings bound to this keyset

@param keySet2 - OR bound to this keyset

[source]

Spring.GetActionHotKeys

---

function Spring.GetActionHotKeys(actionName: string) -> hotkeys string[]?

[source]

Spring.GetGroupList

---

function Spring.GetGroupList() -> where table<number,number>?

@return where - keys are groupIDs and values are counts

[source]

Spring.GetSelectedGroup

---

function Spring.GetSelectedGroup() -> groupID integer

[source]

Spring.GetUnitGroup

---

function Spring.GetUnitGroup(unitID: integer) -> groupID integer?

[source]

Spring.GetGroupUnits

---

function Spring.GetGroupUnits(groupID: integer) -> unitIDs number[]?

[source]

Spring.GetGroupUnitsSorted

---

function Spring.GetGroupUnitsSorted(groupID: integer) -> where table<number,number[]>?

@return where - keys are unitDefIDs and values are unitIDs

[source]

Spring.GetGroupUnitsCounts

---

function Spring.GetGroupUnitsCounts(groupID: integer) -> where table<number,number>?

@return where - keys are unitDefIDs and values are counts

[source]

Spring.GetGroupUnitsCount

---

function Spring.GetGroupUnitsCount(groupID: integer) -> groupSize number?

[source]

Spring.GetPlayerRoster

---

function Spring.GetPlayerRoster(
  sortType: number?,
  showPathingPlayers: boolean?
) -> playerTable Roster[]?

@param sortType - return unsorted if unspecified. Disabled = 0, Allies = 1, TeamID = 2, PlayerName = 3, PlayerCPU = 4, PlayerPing = 5

@param showPathingPlayers - (Default: false)

[source]

Spring.GetPlayerTraffic

---

function Spring.GetPlayerTraffic(
  playerID: integer,
  packetID: integer?
) -> traffic number

[source]

Spring.GetPlayerStatistics

---

function Spring.GetPlayerStatistics(playerID: integer)
 -> mousePixels number?
 -> mouseClicks number
 -> keyPresses number
 -> numCommands number
 -> unitCommands number

@return mousePixels - nil when invalid playerID

[source]

Spring.GetConfigParams

---

function Spring.GetConfigParams() ->  Configuration[]

[source]

Spring.GetConfigInt

---

function Spring.GetConfigInt(
  name: string,
  default: number?
) -> configInt number?

@param default - (Default: 0)

[source]

Spring.GetConfigFloat

---

function Spring.GetConfigFloat(
  name: string,
  default: number?
) -> configFloat number?

@param default - (Default: 0)

[source]

Spring.GetConfigString

---

function Spring.GetConfigString(
  name: string,
  default: string?
) -> configString number?

@param default - (Default: "")

[source]

Spring.GetLogSections

---

function Spring.GetLogSections() -> sections table<string,number>

@return sections - where keys are names and loglevel are values. E.g. { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }

[source]

Spring.GetAllGroundDecals

---

function Spring.GetAllGroundDecals() -> decalIDs number[]

[source]

Spring.GetGroundDecalMiddlePos

---

function Spring.GetGroundDecalMiddlePos(decalID: integer)
 -> posX number?
 -> posZ number

[source]

Spring.GetDecalQuadPos

---

function Spring.GetDecalQuadPos(decalID: integer)
 -> posTL.x number?
 -> posTL.z number
 -> posTR.x number
 -> posTR.z number
 -> posBR.x number
 -> posBR.z number
 -> posBL.x number
 -> posBL.z number

[source]

Spring.GetGroundDecalSizeAndHeight

---

function Spring.GetGroundDecalSizeAndHeight(decalID: integer)
 -> sizeX number?
 -> sizeY number
 -> projCubeHeight number

[source]

Spring.GetGroundDecalRotation

---

function Spring.GetGroundDecalRotation(decalID: integer) -> rotation number?

@return rotation - Rotation in radians.

[source]

Spring.GetGroundDecalTexture

---

function Spring.GetGroundDecalTexture(
  decalID: integer,
  isMainTex: boolean?
) -> texture string?

@param isMainTex - (Default: true) If false, return the normal/glow map.

[source]

Spring.GetDecalTextures

---

function Spring.GetDecalTextures(isMainTex: boolean?) -> textureNames string[]

@param isMainTex - (Default: true) If false, return the texture for normal/glow maps.

@return textureNames - All textures on the atlas and available for use in SetGroundDecalTexture.

[source]

@see Spring.GetGroundDecalTexture

Spring.SetGroundDecalTextureParams

---

function Spring.SetGroundDecalTextureParams(decalID: integer)
 -> texWrapDistance number?
 -> texTraveledDistance number

@return texWrapDistance - If non-zero, sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos.

@return 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.

[source]

Spring.GetGroundDecalAlpha

---

function Spring.GetGroundDecalAlpha(decalID: integer)
 -> alpha number?
 -> alphaFalloff number

@return alpha - Between 0 and 1

@return alphaFalloff - Between 0 and 1, per second

[source]

Spring.GetGroundDecalNormal

---

function Spring.GetGroundDecalNormal(decalID: integer)
 -> normal.x number?
 -> normal.y number
 -> normal.z number

[source]

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

Spring.GetGroundDecalTint

---

function Spring.GetGroundDecalTint(decalID: integer)
 -> tintR number?
 -> tintG number
 -> tintB number
 -> tintA number

[source]

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

Spring.GetGroundDecalMisc

---

function Spring.GetGroundDecalMisc(decalID: integer)
 -> dotElimExp number?
 -> refHeight number
 -> minHeight number
 -> maxHeight number
 -> forceHeightMode number

[source]

Returns less important parameters of a ground decal

Spring.GetGroundDecalCreationFrame

---

function Spring.GetGroundDecalCreationFrame(decalID: integer)
 -> creationFrameMin number?
 -> creationFrameMax number

[source]

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

Spring.GetGroundDecalOwner

---

function Spring.GetGroundDecalOwner(decalID: integer) -> value integer?

@return value - If owner is a unit, then this is unitID, if owner is a feature it is featureID + MAX_UNITS. If there is no owner, then nil.

[source]

Spring.GetGroundDecalType

---

function Spring.GetGroundDecalType(decalID: integer) -> type ("explosion"|"plate"|"lua"|"track"|"unknown")?

[source]

Spring.GetSyncedGCInfo

---

function Spring.GetSyncedGCInfo(collectGC: boolean?) -> GC number?

@param collectGC - (Default: false) collect before returning metric

@return GC - values are expressed in Kbytes: #bytes/2^10

[source]

Spring.SolveNURBSCurve

---

function Spring.SolveNURBSCurve(groupID: integer) -> unitIDs number[]?

[source]

Spring.IsCheatingEnabled

---

function Spring.IsCheatingEnabled() -> enabled boolean

[source]

Spring.IsGodModeEnabled

---

function Spring.IsGodModeEnabled() -> enabled boolean

[source]

Spring.IsDevLuaEnabled

---

function Spring.IsDevLuaEnabled() -> enabled boolean

[source]

Spring.IsEditDefsEnabled

---

function Spring.IsEditDefsEnabled() -> enabled boolean

[source]

Spring.IsNoCostEnabled

---

function Spring.IsNoCostEnabled() -> enabled boolean

[source]

Spring.GetGlobalLos

---

function Spring.GetGlobalLos(teamID: integer?) -> enabled boolean

[source]

Spring.AreHelperAIsEnabled

---

function Spring.AreHelperAIsEnabled() -> enabled boolean

[source]

Spring.FixedAllies

---

function Spring.FixedAllies() -> enabled boolean?

[source]

Spring.IsGameOver

---

function Spring.IsGameOver() -> isGameOver boolean

[source]

Spring.GetGameFrame

---

function Spring.GetGameFrame()
 -> t1 number
 -> t2 number

@return t1 - frameNum % dayFrames

@return t2 - frameNum / dayFrames

[source]

Spring.GetGameSeconds

---

function Spring.GetGameSeconds() -> seconds number

[source]

Spring.GetTidal

---

function Spring.GetTidal() -> tidalStrength number

[source]

Spring.GetWind

---

function Spring.GetWind()
 -> windSpeedX number
 -> windSpeedY number
 -> windSpeedZ number
 -> windStrength number
 -> windDirX number
 -> windDirY number
 -> windDirZ number

@return windSpeedY - (Always 0)

@return windStrength - (Length of windSpeed)

@return windDirX - (Normalized windSpeed)

@return windDirY - (Always 0)

[source]

Spring.GetGameRulesParams

---

function Spring.GetGameRulesParams() -> rulesParams RulesParams

@return rulesParams - map with rules names as key and values as values

[source]

Spring.GetTeamRulesParams

---

function Spring.GetTeamRulesParams(teamID: integer) -> rulesParams RulesParams

@return rulesParams - map with rules names as key and values as values

[source]

Spring.GetPlayerRulesParams

---

function Spring.GetPlayerRulesParams(playerID: integer) -> rulesParams RulesParams

@return rulesParams - map with rules names as key and values as values

[source]

Spring.GetUnitRulesParams

---

function Spring.GetUnitRulesParams(unitID: integer) -> rulesParams RulesParams

@return rulesParams - map with rules names as key and values as values

[source]

Spring.GetFeatureRulesParams

---

function Spring.GetFeatureRulesParams(featureID: integer) -> rulesParams RulesParams

@return rulesParams - map with rules names as key and values as values

[source]

Spring.GetGameRulesParam

---

function Spring.GetGameRulesParam(ruleRef: (number|string)) ->  number?

@param ruleRef - the rule index or name

@return -

string value

[source]

Spring.GetTeamRulesParam

---

function Spring.GetTeamRulesParam(
  teamID: integer,
  ruleRef: (number|string)
) -> value (number|string)?

@param ruleRef - the rule index or name

[source]

Spring.GetPlayerRulesParam

---

function Spring.GetPlayerRulesParam(
  playerID: integer,
  ruleRef: (number|string)
) -> value (number|string)?

@param ruleRef - the rule index or name

[source]

Spring.GetUnitRulesParam

---

function Spring.GetUnitRulesParam(
  unitID: integer,
  ruleRef: (number|string)
) -> value (number|string)?

@param ruleRef - the rule index or name

[source]

Spring.GetFeatureRulesParam

---

function Spring.GetFeatureRulesParam(
  featureID: integer,
  ruleRef: (number|string)
) -> value (number|string)?

@param ruleRef - the rule index or name

[source]

Spring.GetMapOption

---

function Spring.GetMapOption(mapOption: string) -> value string

@return value - Value of modOption.

[source]

Spring.GetMapOptions

---

function Spring.GetMapOptions() -> mapOptions table<string,string>

@return mapOptions - Table with options names as keys and values as values.

[source]

Spring.GetModOption

---

function Spring.GetModOption(modOption: string) -> value string

@return value - Value of modOption.

[source]

Spring.GetModOptions

---

function Spring.GetModOptions() -> modOptions table<string,string>

@return modOptions - Table with options names as keys and values as values.

[source]

Spring.GetHeadingFromVector

---

function Spring.GetHeadingFromVector(
  x: number,
  z: number
) -> heading number

[source]

Spring.GetVectorFromHeading

---

function Spring.GetVectorFromHeading(heading: number)
 -> x number
 -> z number

[source]

Spring.GetFacingFromHeading

---

function Spring.GetFacingFromHeading(heading: number) -> facing FacingInteger

[source]

Spring.GetHeadingFromFacing

---

function Spring.GetHeadingFromFacing(facing: FacingInteger) -> heading number

[source]

Spring.GetSideData

---

function Spring.GetSideData(sideName: string)
 -> startUnit string?
 -> caseName string?

@param sideName - Case-insensitive side name.

@return caseName - Original case side name.

[source]

Spring.GetSideData

---

function Spring.GetSideData(sideID: integer)
 -> sideName string?
 -> startUnit string?
 -> caseName string?

@return sideName - Lowercase side name.

@return caseName - Original case side name.

[source]

Spring.GetSideData

---

function Spring.GetSideData() -> sideArray SideSpec[]

[source]

Spring.GetGaiaTeamID

---

function Spring.GetGaiaTeamID() -> teamID integer

[source]

Spring.GetAllyTeamStartBox

---

function Spring.GetAllyTeamStartBox(allyID: integer)
 -> xMin number?
 -> zMin number?
 -> xMax number?
 -> zMax number?

[source]

Spring.GetTeamStartPosition

---

function Spring.GetTeamStartPosition(teamID: integer)
 -> x number?
 -> y number?
 -> x number?

[source]

Spring.GetMapStartPositions

---

function Spring.GetMapStartPositions() -> array float3[]

@return array - of positions indexed by teamID

[source]

Spring.GetAllyTeamList

---

function Spring.GetAllyTeamList() -> allyTeamIDs integer[]

[source]

Spring.GetTeamList

---

function Spring.GetTeamList(allyTeamID: unknown) -> teamIDs number[]

@param allyTeamID - (Default: -1)

@return teamIDs - List of team IDs.

Get all team IDs.

[source]

Spring.GetTeamList

---

function Spring.GetTeamList(allyTeamID: integer) -> teamIDs number[]?

@param allyTeamID - The ally team ID to filter teams by. A value less than 0 will return all teams.

@return teamIDs - List of team IDs or nil if allyTeamID is invalid.

Get team IDs in a specific ally team.

[source]

Spring.GetPlayerList

---

function Spring.GetPlayerList(
  teamID: integer?,
  active: boolean?
) -> list number[]?

@param teamID - (Default: -1) to filter by when >= 0

@param active - (Default: false) whether to filter only active teams

@return list - of playerIDs

[source]

Spring.GetTeamInfo

---

function Spring.GetTeamInfo(
  teamID: integer,
  getTeamKeys: boolean?
)
 -> teamID integer?
 -> leader number
 -> isDead number
 -> hasAI number
 -> side string
 -> allyTeam number
 -> incomeMultiplier number
 -> customTeamKeys table<string,string>

@param getTeamKeys - (Default: true) whether to return the customTeamKeys table

@return customTeamKeys - when getTeamKeys is true, otherwise nil

[source]

Spring.GetTeamAllyTeamID

---

function Spring.GetTeamAllyTeamID(teamID: integer) -> allyTeamID integer?

[source]

Spring.GetTeamResources

---

function Spring.GetTeamResources(
  teamID: integer,
  resource: ResourceName
)
 -> currentLevel number?
 -> storage number
 -> pull number
 -> income number
 -> expense number
 -> share number
 -> sent number
 -> received number
 -> excess number

[source]

Spring.GetTeamUnitStats

---

function Spring.GetTeamUnitStats(teamID: integer)
 -> killed number?
 -> died number
 -> capturedBy number
 -> capturedFrom number
 -> received number
 -> sent number

[source]

Spring.GetTeamResourceStats

---

function Spring.GetTeamResourceStats(
  teamID: integer,
  resource: ResourceName
)
 -> used number?
 -> produced number
 -> excessed number
 -> received number
 -> sent number

[source]

Spring.GetTeamDamageStats

---

function Spring.GetTeamDamageStats(teamID: integer)
 -> damageDealt number
 -> damageReceived number

Gets team damage dealt/received totals

[source]

Returns a team’s damage stats. Note that all damage is counted, including self-inflicted and unconfirmed out-of-sight.

Spring.GetTeamStatsHistory

---

function Spring.GetTeamStatsHistory(teamID: integer) -> historyCount integer?

@return historyCount - The number of history entries, or nil if unable to resolve team.

Get the number of history entries.

[source]

Spring.GetTeamStatsHistory

---

function Spring.GetTeamStatsHistory(
  teamID: integer,
  startIndex: integer,
  endIndex: integer?
) -> The TeamStats[]

@param endIndex - (Default: startIndex)

@return The - team stats history, or nil if unable to resolve team.

Get team stats history.

[source]

Spring.GetTeamLuaAI

---

function Spring.GetTeamLuaAI(teamID: integer) ->  string

[source]

Spring.GetTeamMaxUnits

---

function Spring.GetTeamMaxUnits(teamID: integer)
 -> maxUnits number
 -> currentUnits number?

Returns a team’s unit cap.

Also returns the current unit count for readable teams as the 2nd value.

[source]

Spring.GetPlayerInfo

---

function Spring.GetPlayerInfo(
  playerID: integer,
  getPlayerOpts: boolean?
)
 -> name string
 -> active boolean
 -> spectator boolean
 -> teamID integer
 -> allyTeamID integer
 -> pingTime number
 -> cpuUsage number
 -> country string
 -> rank number
 -> hasSkirmishAIsInTeam boolean
 -> playerOpts { [string]: string }
 -> desynced boolean

@param getPlayerOpts - (Default: true) whether to return custom player options

@return playerOpts - when playerOpts is true

[source]

Spring.GetPlayerControlledUnit

---

function Spring.GetPlayerControlledUnit(playerID: integer) ->  number?

Returns unit controlled by player on FPS mode

[source]

Spring.GetAIInfo

---

function Spring.GetAIInfo(teamID: integer)
 -> skirmishAIID integer
 -> name string
 -> hostingPlayerID integer
 -> shortName string
 -> version string
 -> options table<string,string>

@return shortName - When synced "SYNCED_NOSHORTNAME", otherwise the AI shortname or "UNKNOWN".

@return version - When synced "SYNCED_NOVERSION", otherwise the AI version or "UNKNOWN".

[source]

Spring.GetAllyTeamInfo

---

function Spring.GetAllyTeamInfo(allyTeamID: integer) ->  table<string,string>?

[source]

Spring.AreTeamsAllied

---

function Spring.AreTeamsAllied(
  teamID1: number,
  teamID2: number
) ->  boolean?

[source]

Spring.ArePlayersAllied

---

function Spring.ArePlayersAllied(
  playerID1: number,
  playerID2: number
) ->  boolean?

[source]

Spring.GetAllUnits

---

function Spring.GetAllUnits() -> unitIDs number[]

Get a list of all unitIDs

[source]

Note that when called from a widget, this also returns units that are only radar blips.

For units that are radar blips, you may want to check if they are in los, as GetUnitDefID() will still return true if they have previously been seen.

@see UnsyncedRead.GetVisibleUnits

Spring.GetTeamUnits

---

function Spring.GetTeamUnits(teamID: integer) -> unitIDs number[]?

[source]

Spring.GetTeamUnitsSorted

---

function Spring.GetTeamUnitsSorted(teamID: integer) -> unitsByDef table<integer,integer>

@return unitsByDef - A table where keys are unitDefIDs and values are unitIDs

[source]

Spring.GetTeamUnitsCounts

---

function Spring.GetTeamUnitsCounts(teamID: integer) -> countByUnit table<number,number>?

@return countByUnit - A table where keys are unitDefIDs and values are counts.

[source]

Spring.GetTeamUnitsByDefs

---

function Spring.GetTeamUnitsByDefs(
  teamID: integer,
  unitDefIDs: (number|number[])
) -> unitIDs number[]?

[source]

Spring.GetTeamUnitDefCount

---

function Spring.GetTeamUnitDefCount(
  teamID: integer,
  unitDefID: integer
) -> count number?

[source]

Spring.GetTeamUnitCount

---

function Spring.GetTeamUnitCount(teamID: integer) -> count number?

[source]

Spring.GetUnitsInRectangle

---

function Spring.GetUnitsInRectangle(
  xmin: number,
  zmin: number,
  xmax: number,
  zmax: number,
  allegiance: number?
) -> unitIDs number[]

[source]

Spring.GetUnitsInBox

---

function Spring.GetUnitsInBox(
  xmin: number,
  ymin: number,
  zmin: number,
  xmax: number,
  ymax: number,
  zmax: number,
  allegiance: number?
) -> unitIDs number[]

[source]

Spring.GetUnitsInCylinder

---

function Spring.GetUnitsInCylinder(
  x: number,
  z: number,
  radius: number
) -> unitIDs number[]

[source]

Spring.GetUnitsInSphere

---

function Spring.GetUnitsInSphere(
  x: number,
  y: number,
  z: number,
  radius: number
) -> unitIDs number[]

[source]

Spring.GetUnitsInPlanes

---

function Spring.GetUnitsInPlanes(
  planes: Plane[],
  allegiance: integer?
) -> unitIDs integer[]

[source]

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

---

function Spring.GetUnitArrayCentroid(units: table)
 -> centerX number
 -> centerY number
 -> centerZ number

@param units - { unitID, unitID, … }

Returns the centroid of an array of units

Returns nil for an empty array

[source]

Spring.GetUnitMapCentroid

---

function Spring.GetUnitMapCentroid(units: table)
 -> centerX number
 -> centerY number
 -> centerZ number

@param units - { [unitID] = true, [unitID] = true, … }

Returns the centroid of a map of units

Returns nil for an empty map

[source]

Spring.GetUnitNearestAlly

---

function Spring.GetUnitNearestAlly(
  unitID: integer,
  range: number?
) -> unitID integer?

@param range - (Default: 1.0e9)

[source]

Spring.GetUnitNearestEnemy

---

function Spring.GetUnitNearestEnemy(
  unitID: integer,
  range: number?,
  useLOS: boolean?
) -> unitID integer?

@param range - (Default: 1.0e9)

@param useLOS - (Default: true)

[source]

Spring.GetFeaturesInRectangle

---

function Spring.GetFeaturesInRectangle(
  xmin: number,
  zmin: number,
  xmax: number,
  zmax: number
) -> featureIDs number[]

[source]

Spring.GetFeaturesInSphere

---

function Spring.GetFeaturesInSphere(
  x: number,
  y: number,
  z: number,
  radius: number
) -> featureIDs number[]

[source]

Spring.GetFeaturesInCylinder

---

function Spring.GetFeaturesInCylinder(
  x: number,
  z: number,
  radius: number,
  allegiance: number?
) -> featureIDs number[]

[source]

Spring.GetProjectilesInRectangle

---

function Spring.GetProjectilesInRectangle(
  xmin: number,
  zmin: number,
  xmax: number,
  zmax: number,
  excludeWeaponProjectiles: boolean?,
  excludePieceProjectiles: boolean?
) -> projectileIDs number[]

@param excludeWeaponProjectiles - (Default: false)

@param excludePieceProjectiles - (Default: false)

[source]

Spring.GetProjectilesInSphere

---

function Spring.GetProjectilesInSphere(
  x: number,
  y: number,
  z: number,
  radius: number,
  excludeWeaponProjectiles: boolean?,
  excludePieceProjectiles: boolean?
) -> projectileIDs number[]

@param excludeWeaponProjectiles - (Default: false)

@param excludePieceProjectiles - (Default: false)

[source]

Spring.ValidUnitID

---

function Spring.ValidUnitID(unitID: integer) ->  boolean

[source]

Spring.GetUnitStates

---

function Spring.GetUnitStates(unitID: integer) ->  UnitState

[source]

Spring.GetUnitArmored

---

function Spring.GetUnitArmored(unitID: integer)
 -> armored boolean?
 -> armorMultiple number

[source]

Spring.GetUnitIsActive

---

function Spring.GetUnitIsActive(unitID: integer) -> isActive boolean?

[source]

Spring.GetUnitIsCloaked

---

function Spring.GetUnitIsCloaked(unitID: integer) -> isCloaked boolean?

[source]

Spring.GetUnitSeismicSignature

---

function Spring.GetUnitSeismicSignature(unitID: integer) -> seismicSignature number?

[source]

Spring.GetUnitSelfDTime

---

function Spring.GetUnitSelfDTime(unitID: integer) -> selfDTime integer?

[source]

Spring.GetUnitStockpile

---

function Spring.GetUnitStockpile(unitID: integer)
 -> numStockpiled integer?
 -> numStockpileQued integer?
 -> buildPercent number?

[source]

Spring.GetUnitSensorRadius

---

function Spring.GetUnitSensorRadius(
  unitID: integer,
  type: string
) -> radius number?

@param type - one of los, airLos, radar, sonar, seismic, radarJammer, sonarJammer

[source]

Spring.GetUnitPosErrorParams

---

function Spring.GetUnitPosErrorParams(
  unitID: integer,
  allyTeamID: integer?
)
 -> posErrorVectorX number?
 -> posErrorVectorY number
 -> posErrorVectorZ number
 -> posErrorDeltaX number
 -> posErrorDeltaY number
 -> posErrorDeltaZ number
 -> nextPosErrorUpdatebaseErrorMult number
 -> posErrorBit boolean

[source]

Spring.GetUnitTooltip

---

function Spring.GetUnitTooltip(unitID: integer) ->  string?

[source]

Spring.GetUnitDefID

---

function Spring.GetUnitDefID(unitID: integer) ->  number?

[source]

Spring.GetUnitTeam

---

function Spring.GetUnitTeam(unitID: integer) ->  number?

[source]

Spring.GetUnitAllyTeam

---

function Spring.GetUnitAllyTeam(unitID: integer) ->  number?

[source]

Spring.GetUnitNeutral

---

function Spring.GetUnitNeutral(unitID: integer) ->  boolean?

Checks if a unit is neutral (NOT Gaia!)

[source]

Note that a “neutral” unit can belong to any ally-team (ally, enemy, Gaia). To check if a unit is Gaia, check its owner team.

Spring.GetUnitHealth

---

function Spring.GetUnitHealth(unitID: integer)
 -> health number?
 -> maxHealth number
 -> paralyzeDamage number
 -> captureProgress number
 -> buildProgress number

@return buildProgress - between 0.0-1.0

[source]

Spring.GetUnitIsDead

---

function Spring.GetUnitIsDead(unitID: integer) ->  boolean?

[source]

Spring.GetUnitIsStunned

---

function Spring.GetUnitIsStunned(unitID: integer)
 -> stunnedOrBuilt boolean?
 -> stunned boolean
 -> beingBuilt boolean

@return stunnedOrBuilt - unit is disabled

@return stunned - unit is either stunned via EMP or being transported by a non-fireplatform

@return beingBuilt - unit is under construction

Checks whether a unit is disabled and can’t act

The first return value is a simple OR of the following ones, any of those conditions is sufficient to disable the unit.

Note that EMP and being transported are mechanically the same and thus lumped together. Use other callouts to differentiate them if you need to.

[source]

Spring.GetUnitIsBeingBuilt

---

function Spring.GetUnitIsBeingBuilt(unitID: integer)
 -> beingBuilt boolean
 -> buildProgress number

[source]

Spring.GetUnitResources

---

function Spring.GetUnitResources(unitID: integer)
 -> metalMake number?
 -> metalUse number
 -> energyMake number
 -> energyUse number

[source]

Spring.GetUnitStorage

---

function Spring.GetUnitStorage(unitID: integer)
 -> Unit number
 -> Unit number

@return Unit - ‘s metal storage

@return Unit - ‘s energy storage

[source]

Spring.GetUnitCosts

---

function Spring.GetUnitCosts(unitID: integer)
 -> buildTime number?
 -> metalCost number
 -> energyCost number

[source]

Spring.GetUnitCostTable

---

function Spring.GetUnitCostTable(unitID: integer)
 -> cost ResourceCost?
 -> buildTime number?

@return cost - The cost of the unit, or nil if invalid.

@return buildTime - The build time the unit, or nil if invalid.

[source]

Spring.GetUnitMetalExtraction

---

function Spring.GetUnitMetalExtraction(unitID: integer) -> metalExtraction number?

[source]

Spring.GetUnitExperience

---

function Spring.GetUnitExperience(unitID: integer)
 -> xp number
 -> limXp number

@return xp - [0.0; +∞)

@return limXp - [0.0; 1.0) as experience approaches infinity

[source]

Spring.GetUnitHeight

---

function Spring.GetUnitHeight(unitID: integer) ->  number?

[source]

Spring.GetUnitRadius

---

function Spring.GetUnitRadius(unitID: integer) ->  number?

[source]

Spring.GetUnitBuildeeRadius

---

function Spring.GetUnitBuildeeRadius(unitID: integer) ->  number?

[source]

Gets the unit’s radius for when targeted by build, repair, reclaim-type commands.

Spring.GetUnitMass

---

function Spring.GetUnitMass(unitID: integer) ->  number?

[source]

Spring.GetUnitPosition

---

function Spring.GetUnitPosition(
  unitID: integer,
  midPos: boolean?,
  aimPos: boolean?
)
 -> basePointX number?
 -> basePointY number
 -> basePointZ number
 -> midPointX number?
 -> midPointY number
 -> midPointZ number
 -> aimPointX number?
 -> aimPointY number
 -> aimPointZ number

@param midPos - (Default: false) return midpoint as well

@param aimPos - (Default: false) return aimpoint as well

[source]

Spring.GetUnitBasePosition

---

function Spring.GetUnitBasePosition(unitID: integer)
 -> posX number?
 -> posY number?
 -> posZ number?

[source]

The same as Spring.GetUnitPosition, but without the optional midpoint calculations.

@see Spring.GetUnitPosition

Spring.GetUnitVectors

---

function Spring.GetUnitVectors(unitID: integer)
 -> front float3?
 -> up float3
 -> right float3

[source]

Spring.GetUnitRotation

---

function Spring.GetUnitRotation(unitID: integer)
 -> pitch number
 -> yaw number
 -> roll number

@return pitch - Rotation in X axis

@return yaw - Rotation in Y axis

@return roll - Rotation in Z axis

[source]

Note: PYR order

Spring.GetUnitDirection

---

function Spring.GetUnitDirection(unitID: integer)
 -> frontDirX number
 -> frontDirY number
 -> frontDirZ number
 -> rightDirX number
 -> rightDirY number
 -> rightDirZ number
 -> upDirX number
 -> upDirY number
 -> upDirZ number

[source]

Spring.GetUnitHeading

---

function Spring.GetUnitHeading(
  unitID: integer,
  convertToRadians: boolean?
) -> heading number

@param convertToRadians - (Default: false)

[source]

Spring.GetUnitVelocity

---

function Spring.GetUnitVelocity(unitID: integer)

[source]

Spring.GetUnitBuildFacing

---

function Spring.GetUnitBuildFacing(unitID: integer)

[source]

Spring.GetUnitIsBuilding

---

function Spring.GetUnitIsBuilding(unitID: integer) -> buildeeUnitID integer

@return buildeeUnitID - or nil

Checks whether a unit is currently building another (NOT for checking if it’s a structure)

[source]

Works for both mobile builders and factories.

Spring.GetUnitWorkerTask

---

function Spring.GetUnitWorkerTask(unitID: integer)
 -> cmdID integer
 -> targetID integer

@return cmdID - of the relevant command

@return targetID - if applicable (all except RESTORE)

Checks a builder’s current task

[source]

Checks what a builder is currently doing. This is not the same as Spring.GetUnitCurrentCommand, because you can have a command at the front of the queue and not be doing it (for example because the target is still too far away), and on the other hand you can also be doing a task despite not having it in front of the queue (for example you’re Guarding another builder who does). Also, it resolves the Repair command into either actual repair, or construction assist (in which case it returns the appropriate “build” command). Only build-related commands are returned (no Move or any custom commands).

The possible commands returned are repair, reclaim, resurrect, capture, restore, and build commands (negative buildee unitDefID).

Spring.GetUnitEffectiveBuildRange

---

function Spring.GetUnitEffectiveBuildRange(
  unitID: integer,
  buildeeDefID: integer
) -> effectiveBuildRange number

@param buildeeDefID - or nil

@return effectiveBuildRange - counted to the center of prospective buildee; buildRange if buildee nil

[source]

Useful for setting move goals manually.

Spring.GetUnitCurrentBuildPower

---

function Spring.GetUnitCurrentBuildPower(unitID: integer)

[source]

Spring.GetUnitHarvestStorage

---

function Spring.GetUnitHarvestStorage(unitID: integer)
 -> storedMetal number
 -> maxStoredMetal number
 -> storedEnergy number
 -> maxStoredEnergy number

Get a unit’s carried resources

[source]

Checks resources being carried internally by the unit.

Spring.GetUnitBuildParams

---

function Spring.GetUnitBuildParams(unitID: integer)

[source]

Spring.GetUnitInBuildStance

---

function Spring.GetUnitInBuildStance(unitID: integer) -> inBuildStance boolean

Is builder in build stance

[source]

Checks if a builder is in build stance, i.e. can create nanoframes. Returns nil for non-builders.

Spring.GetUnitNanoPieces

---

function Spring.GetUnitNanoPieces(unitID: integer) -> pieceArray integer[]

Get construction FX attachment points

[source]

Returns an array of pieces which represent construction points. Default engine construction FX (nano spray) will originate there.

Only works on builders and factories, returns nil (NOT empty table) for other units.

Spring.GetUnitTransporter

---

function Spring.GetUnitTransporter(unitID: integer) -> transportUnitID integer?

Get the transport carrying the unit

[source]

Returns the unit ID of the transport, if any. Returns nil if the unit is not being transported.

Spring.GetUnitIsTransporting

---

function Spring.GetUnitIsTransporting(unitID: integer) -> transporteeArray integer[]?

@return transporteeArray - An array of unitIDs being transported by this unit, or nil if not a transport.

Get units being transported

[source]

Spring.GetUnitShieldState

---

function Spring.GetUnitShieldState(
  unitID: integer,
  weaponNum: number?
)
 -> isEnabled number
 -> currentPower number

@param weaponNum - Optional if the unit has just one shield

@return isEnabled - Warning, number not boolean. 0 or 1

[source]

Spring.GetUnitFlanking

---

function Spring.GetUnitFlanking(unitID: integer)

[source]

Spring.GetUnitMaxRange

---

function Spring.GetUnitMaxRange(unitID: integer) -> maxRange number

Get a unit’s engagement range

[source]

Returns the range at which a unit will stop to engage. By default this is the highest among the unit’s weapon ranges (hence name), but can be changed dynamically. Also note that unarmed units ignore this.

Spring.GetUnitWeaponState

---

function Spring.GetUnitWeaponState(
  unitID: integer,
  weaponNum: number,
  stateName: string
) -> stateValue number

Check the state of a unit’s weapon

[source]

Available states to poll: “reloadFrame” (frame on which the weapon will be ready to fire), “reloadSpeed” (reload time in seconds), “range” (in elmos), “autoTargetRangeBoost” (predictive aiming range buffer, in elmos), “projectileSpeed” (in elmos/frame), “reloadTimeXP” (reload time after XP bonus, in seconds), “reaimTime” (frames between AimWeapon calls), “burst” (shots in a burst), “burstRate” (delay between shots in a burst, in seconds), “projectiles” (projectiles per shot), “salvoLeft” (shots remaining in ongoing burst), “nextSalvo” (simframe of the next shot in an ongoing burst), “accuracy” (INaccuracy after XP bonus), “sprayAngle” (spray angle after XP bonus), “targetMoveError” (extra inaccuracy against moving targets, after XP bonus) “avoidFlags” (bitmask for targeting avoidance), “ttl” (number of seconds a projectile should live) “collisionFlags” (bitmask for collisions).

The state “salvoError” is an exception and returns a table: {x, y, z}, which represents the inaccuracy error of the ongoing burst.

Spring.GetUnitWeaponDamages

---

function Spring.GetUnitWeaponDamages(unitID: integer)

[source]

Spring.GetUnitWeaponVectors

---

function Spring.GetUnitWeaponVectors(unitID: integer)

[source]

Spring.GetUnitWeaponTryTarget

---

function Spring.GetUnitWeaponTryTarget(unitID: integer)

[source]

Spring.GetUnitWeaponTestTarget

---

function Spring.GetUnitWeaponTestTarget(unitID: integer)

[source]

Spring.GetUnitWeaponTestRange

---

function Spring.GetUnitWeaponTestRange(unitID: integer)

[source]

Spring.GetUnitWeaponHaveFreeLineOfFire

---

function Spring.GetUnitWeaponHaveFreeLineOfFire(unitID: integer)

[source]

Spring.GetUnitWeaponCanFire

---

function Spring.GetUnitWeaponCanFire(unitID: integer)

[source]

Spring.GetUnitWeaponTarget

---

function Spring.GetUnitWeaponTarget(
  unitID: integer,
  weaponNum: integer
)
 -> TargetType 0
 -> isUserTarget boolean

@return TargetType - none

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

Spring.GetUnitWeaponTarget

---

function Spring.GetUnitWeaponTarget(
  unitID: integer,
  weaponNum: integer
)
 -> TargetType 1
 -> isUserTarget boolean
 -> targetUnitID integer

@return TargetType - unit

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

Spring.GetUnitWeaponTarget

---

function Spring.GetUnitWeaponTarget(
  unitID: integer,
  weaponNum: integer
)
 -> TargetType 2
 -> isUserTarget boolean
 -> targetPosition float3

@return TargetType - position

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

Spring.GetUnitWeaponTarget

---

function Spring.GetUnitWeaponTarget(
  unitID: integer,
  weaponNum: integer
)
 -> TargetType 3
 -> isUserTarget boolean
 -> targetProjectileId integer

@return TargetType - projectileID

Checks a weapon’s target

Note that this doesn’t need to reflect the unit’s Attack orders or such, and that weapons can aim individually unless slaved.

[source]

Spring.GetUnitEstimatedPath

---

function Spring.GetUnitEstimatedPath(unitID: integer)

[source]

Spring.GetUnitLastAttacker

---

function Spring.GetUnitLastAttacker(unitID: integer)

[source]

Spring.GetUnitLastAttackedPiece

---

function Spring.GetUnitLastAttackedPiece(unitID: integer)

[source]

Spring.GetUnitCollisionVolumeData

---

function Spring.GetUnitCollisionVolumeData(unitID: integer)

[source]

Spring.GetUnitSeparation

---

function Spring.GetUnitSeparation(
  unitID1: number,
  unitID2: number,
  direction: boolean?,
  subtractRadii: boolean?
) ->  number?

@param direction - (Default: false) to subtract from, default unitID1 - unitID2

@param subtractRadii - (Default: false) whether units radii should be subtracted from the total

[source]

Spring.GetUnitFeatureSeparation

---

function Spring.GetUnitFeatureSeparation(unitID: integer)

[source]

Spring.GetUnitDefDimensions

---

function Spring.GetUnitDefDimensions(unitDefID: integer) -> dimensions UnitDefDimensions?

[source]

Spring.GetCEGID

---

function Spring.GetCEGID()

[source]

Spring.GetUnitBlocking

---

function Spring.GetUnitBlocking(unitID: integer)
 -> isBlocking boolean?
 -> isSolidObjectCollidable boolean
 -> isProjectileCollidable boolean
 -> isRaySegmentCollidable boolean
 -> crushable boolean
 -> blockEnemyPushing boolean
 -> blockHeightChanges boolean

[source]

Spring.GetUnitMoveTypeData

---

function Spring.GetUnitMoveTypeData(unitID: integer)

[source]

Spring.GetUnitCurrentCommand

---

function Spring.GetUnitCurrentCommand(
  unitID: integer,
  cmdIndex: integer?
)
 -> cmdID CMD?
 -> options (integer|CommandOptionBit)?
 -> tag integer?
 -> Command number? ...

@param unitID - unitID when invalid this function returns nil.

@param cmdIndex - (Default: 0) Command index to get. If negative will count from the end of the queue, e.g. -1 will be the last command.

@return Command - parameters.

Get a command from a units command queue.

For factories, this function uses the command queue automatically assigned to new units.

[source]

@see Spring.GetFactoryCommands for getting factory build queue commands

Spring.GetUnitCommands

---

function Spring.GetUnitCommands(
  unitID: integer,
  count: integer
) -> commands Command[]

@param count - Maximum amount of commands to return, -1 returns all commands.

Get the commands for a unit.

[source]

Same as Spring.GetCommandQueue

Spring.GetUnitCommands

---

function Spring.GetUnitCommands(
  unitID: integer,
  count: 0
) -> The integer

@param count - Returns the number of commands in the units queue.

@return The - number of commands in the unit queue.

Get the count of commands for a unit.

[source]

@deprecated This overload is deprecated, use Spring.GetUnitCommandCount(unitId) instead.

Spring.GetFactoryCommands

---

function Spring.GetFactoryCommands(
  unitID: integer,
  count: integer
) -> commands Command[]

@param count - Maximum amount of commands to return, -1 returns all commands.

Get the number or list of commands for a factory

[source]

@see Spring.GetFactoryCounts to get command counts grouped by cmdID.

Spring.GetFactoryCommands

---

function Spring.GetFactoryCommands(
  unitID: integer,
  count: 0
) -> The integer

@param count - Returns the number of commands in the factory queue.

@return The - number of commands in the factory queue.

Get the count of commands for a factory.

[source]

@deprecated This overload is deprecated, use Spring.GetFactoryCommandCount(unitId) instead.

@see Spring.GetFactoryCommandCount for replacement function.

Spring.GetUnitCommandCount

---

function Spring.GetUnitCommandCount(unitID: integer) -> The integer

@return The - number of commands in the unit’s queue.

Get the number of commands in a unit’s queue.

[source]

Spring.GetFactoryCommandCount

---

function Spring.GetFactoryCommandCount(unitID: integer) -> The integer

@return The - number of commands in the factory queue.

Get the number of commands in a factory queue.

[source]

@see Spring.GetFactoryCounts to get command counts grouped by cmdID.

Spring.GetFactoryBuggerOff

---

function Spring.GetFactoryBuggerOff(unitID: integer)

[source]

Spring.GetFactoryCounts

---

function Spring.GetFactoryCounts(
  unitID: integer,
  count: integer?,
  addCmds: boolean?
) -> counts table<number,number>?

@param count - (Default: -1) Number of commands to retrieve, -1 for all.

@param addCmds - (Default: false) Retrieve commands other than buildunit

@return counts - Build queue count by unitDefID or -cmdID, or nil if unit is not found.

Gets the build queue of a factory

[source]

Spring.GetCommandQueue

---

function Spring.GetCommandQueue(
  unitID: integer,
  count: integer
) -> commands Command[]

@param count - Number of commands to return, -1 returns all commands, 0 returns command count.

Get the commands for a unit.

[source]

Same as Spring.GetUnitCommands

@deprecated Use Spring.GetUnitCommands instead.

Spring.GetCommandQueue

---

function Spring.GetCommandQueue(
  unitID: integer,
  count: 0
) -> The integer

@param count - Returns the number of commands in the units queue.

@return The - number of commands in the unit queue.

Get the count of commands for a unit.

[source]

Same as Spring.GetUnitCommands

@deprecated Use Spring.GetUnitCommandCount instead.

Spring.GetFullBuildQueue

---

function Spring.GetFullBuildQueue(unitID: integer) -> buildqueue table<number,number>?

@return buildqueue - indexed by unitDefID with count values

Returns the build queue

[source]

Spring.GetRealBuildQueue

---

function Spring.GetRealBuildQueue(unitID: integer) -> buildqueue table<number,number>?

@return buildqueue - indexed by unitDefID with count values

Returns the build queue cleaned of things the unit can’t build itself

[source]

Spring.GetUnitCmdDescs

---

function Spring.GetUnitCmdDescs(unitID: integer)

[source]

Spring.FindUnitCmdDesc

---

function Spring.FindUnitCmdDesc(unitID: integer)

[source]

Spring.ValidFeatureID

---

function Spring.ValidFeatureID(featureID: integer) ->  boolean

[source]

Spring.GetAllFeatures

---

function Spring.GetAllFeatures() -> featureIDs integer[]

[source]

Spring.GetFeatureDefID

---

function Spring.GetFeatureDefID(featureID: integer) ->  number?

[source]

Spring.GetFeatureTeam

---

function Spring.GetFeatureTeam(featureID: integer) ->  number?

[source]

Spring.GetFeatureAllyTeam

---

function Spring.GetFeatureAllyTeam(featureID: integer) ->  number?

[source]

Spring.GetFeatureHealth

---

function Spring.GetFeatureHealth(featureID: integer)
 -> health number?
 -> defHealth number
 -> resurrectProgress number

[source]

Spring.GetFeatureHeight

---

function Spring.GetFeatureHeight(featureID: integer) ->  number?

[source]

Spring.GetFeatureRadius

---

function Spring.GetFeatureRadius(featureID: integer) ->  number?

[source]

Spring.GetFeatureMass

---

function Spring.GetFeatureMass(featureID: integer) ->  number?

[source]

Spring.GetFeaturePosition

---

function Spring.GetFeaturePosition(featureID: integer)
 -> x number?
 -> y number?
 -> z number?

[source]

Spring.GetFeatureSeparation

---

function Spring.GetFeatureSeparation(
  featureID1: number,
  featureID2: number,
  direction: boolean?
) ->  number?

@param direction - (Default: false) to subtract from, default featureID1 - featureID2

[source]

Spring.GetFeatureRotation

---

function Spring.GetFeatureRotation(featureID: integer)
 -> pitch number?
 -> yaw number?
 -> roll number?

@return pitch - Rotation in X axis

@return yaw - Rotation in Y axis

@return roll - Rotation in Z axis

[source]

Note: PYR order

Spring.GetFeatureDirection

---

function Spring.GetFeatureDirection(featureID: integer)
 -> frontDirX number?
 -> frontDirY number?
 -> frontDirZ number?
 -> rightDirX number?
 -> rightDirY number?
 -> rightDirZ number?
 -> upDirX number?
 -> upDirY number?
 -> upDirZ number?

[source]

Spring.GetFeatureVelocity

---

function Spring.GetFeatureVelocity(featureID: integer)
 -> x number?
 -> y number?
 -> z number?
 -> w number?

[source]

Returns nil if no feature found with ID.

Spring.GetFeatureHeading

---

function Spring.GetFeatureHeading(featureID: integer)

[source]

Spring.GetFeatureResources

---

function Spring.GetFeatureResources(featureID: integer)
 -> metal number?
 -> defMetal number
 -> energy number
 -> defEnergy number
 -> reclaimLeft number
 -> reclaimTime number

[source]

Spring.GetFeatureBlocking

---

function Spring.GetFeatureBlocking(featureID: integer)
 -> isBlocking boolean?
 -> isSolidObjectCollidable boolean?
 -> isProjectileCollidable boolean?
 -> isRaySegmentCollidable boolean?
 -> crushable boolean?
 -> blockEnemyPushing boolean?
 -> blockHeightChanges boolean?

[source]

Spring.GetFeatureNoSelect

---

function Spring.GetFeatureNoSelect(featureID: integer) ->  boolean?

[source]

Spring.GetFeatureResurrect

---

function Spring.GetFeatureResurrect(featureID: integer)
 -> featureDefName (string|"")?
 -> buildFacing FacingInteger

@return buildFacing - facing of footprint, 0 - 3

[source]

Returns nil if no feature found with ID.

Spring.GetFeatureLastAttackedPiece

---

function Spring.GetFeatureLastAttackedPiece(featureID: integer)
 -> Last (string|"")?
 -> frame integer

@return Last - hit piece name

@return frame - it was last hit on

[source]

Returns nil if no feature found with ID.

Spring.GetFeatureCollisionVolumeData

---

function Spring.GetFeatureCollisionVolumeData(featureID: integer) ->  CollisionVolumeData?

[source]

Spring.GetFeaturePieceCollisionVolumeData

---

function Spring.GetFeaturePieceCollisionVolumeData(featureID: integer) ->  CollisionVolumeData?

[source]

Spring.GetProjectilePosition

---

function Spring.GetProjectilePosition(projectileID: integer)
 -> posX number?
 -> posY number?
 -> posZ number?

[source]

Spring.GetProjectileDirection

---

function Spring.GetProjectileDirection(projectileID: integer)
 -> dirX number?
 -> dirY number?
 -> dirZ number?

[source]

Spring.GetProjectileVelocity

---

function Spring.GetProjectileVelocity(projectileID: integer)
 -> velX number?
 -> velY number?
 -> velZ number?
 -> velW number?

[source]

Spring.GetProjectileGravity

---

function Spring.GetProjectileGravity(projectileID: integer) ->  number?

[source]

Spring.GetPieceProjectileParams

---

function Spring.GetPieceProjectileParams(projectileID: integer)
 -> explosionFlags number?
 -> spinAngle number
 -> spinSpeed number
 -> spinVectorX number
 -> spinVectorY number
 -> spinVectorZ number

@return explosionFlags - encoded bitwise with SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128

[source]

Spring.GetProjectileTarget

---

function Spring.GetProjectileTarget(projectileID: integer)
 -> targetTypeInt number?
 -> target (number|float3)

@return targetTypeInt - where string.byte(‘g’) := GROUND string.byte(‘u’) := UNIT string.byte(‘f’) := FEATURE string.byte(‘p’) := PROJECTILE

@return target - targetID or targetPos when targetTypeInt == string.byte(‘g’)

[source]

Spring.GetProjectileIsIntercepted

---

function Spring.GetProjectileIsIntercepted(projectileID: integer) ->  boolean?

[source]

Spring.GetProjectileTimeToLive

---

function Spring.GetProjectileTimeToLive(projectileID: integer) ->  number?

[source]

Spring.GetProjectileOwnerID

---

function Spring.GetProjectileOwnerID(projectileID: integer) ->  number?

[source]

Spring.GetProjectileTeamID

---

function Spring.GetProjectileTeamID(projectileID: integer) ->  number?

[source]

Spring.GetProjectileAllyTeamID

---

function Spring.GetProjectileAllyTeamID(projectileID: integer) ->  number?

[source]

Spring.GetProjectileType

---

function Spring.GetProjectileType(projectileID: integer)
 -> weapon boolean?
 -> piece boolean

[source]

Spring.GetProjectileDefID

---

function Spring.GetProjectileDefID(projectileID: integer) ->  number?

[source]

Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

Spring.GetProjectileDamages

---

function Spring.GetProjectileDamages(
  projectileID: integer,
  tag: string
) ->  number?

@param tag - one of: “paralyzeDamageTime” “impulseFactor” “impulseBoost” “craterMult” “craterBoost” “dynDamageExp” “dynDamageMin” “dynDamageRange” “dynDamageInverted” “craterAreaOfEffect” “damageAreaOfEffect” “edgeEffectiveness” “explosionSpeed”

• or - an armor type index to get the damage against it.

[source]

Spring.IsPosInMap

---

function Spring.IsPosInMap(
  x: number,
  z: number
)
 -> inPlayArea boolean
 -> inMap boolean

@return inPlayArea - whether the position is in the active play area

@return inMap - whether the position is in the full map area (currently this is the same as above)

[source]

Spring.GetGroundHeight

---

function Spring.GetGroundHeight(
  x: number,
  z: number
) ->  number

Get ground height

On sea, this returns the negative depth of the seafloor

[source]

Spring.GetWaterPlaneLevel

---

function Spring.GetWaterPlaneLevel() -> waterPlaneLevel number

Get water plane height

Water may at some point become shaped (rivers etc) but for now it is always a flat plane. Use this function instead of GetWaterLevel to denote you are relying on that assumption.

[source]

@see Spring.GetWaterLevel

Spring.GetWaterLevel

---

function Spring.GetWaterLevel(
  x: number,
  z: number
) -> waterLevel number

Get water level in a specific position

Water is currently a flat plane, so this returns the same value regardless of XZ. However water may become more dynamic at some point so by using this you are future-proof.

[source]

Spring.GetGroundOrigHeight

---

function Spring.GetGroundOrigHeight(
  x: number,
  z: number
) ->  number

Get ground height as it was at game start

Returns the original height before the ground got deformed

[source]

Spring.GetGroundNormal

---

function Spring.GetGroundNormal(
  x: number,
  z: number,
  smoothed: boolean?
)
 -> normalX number
 -> normalY number
 -> normalZ number
 -> slope number

@param smoothed - (Default: false) raw or smoothed center normal

[source]

Spring.GetGroundInfo

---

function Spring.GetGroundInfo(
  x: number,
  z: number
)
 -> ix number
 -> iz number
 -> terrainTypeIndex number
 -> name string
 -> metalExtraction number
 -> hardness number
 -> tankSpeed number
 -> kbotSpeed number
 -> hoverSpeed number
 -> shipSpeed number
 -> receiveTracks boolean

[source]

Spring.GetGroundBlocked

---

function Spring.GetGroundBlocked()

[source]

Spring.GetGroundExtremes

---

function Spring.GetGroundExtremes()
 -> initMinHeight number
 -> initMaxHeight number
 -> currMinHeight number
 -> currMaxHeight number

[source]

Spring.GetTerrainTypeData

---

function Spring.GetTerrainTypeData(terrainTypeInfo: number)
 -> index number
 -> name string
 -> hardness number
 -> tankSpeed number
 -> kbotSpeed number
 -> hoverSpeed number
 -> shipSpeed number
 -> receiveTracks boolean

[source]

Spring.GetGrass

---

function Spring.GetGrass(
  x: number,
  z: number
) ->  number

[source]

Spring.GetSmoothMeshHeight

---

function Spring.GetSmoothMeshHeight(
  x: number,
  z: number
) -> height number

[source]

Spring.TestMoveOrder

---

function Spring.TestMoveOrder(
  unitDefID: integer,
  posX: number,
  posY: number,
  posZ: number,
  dirX: number?,
  dirY: number?,
  dirZ: number?,
  testTerrain: boolean?,
  testObjects: boolean?,
  centerOnly: boolean?
) ->  boolean

@param dirX - (Default: 0.0)

@param dirY - (Default: 0.0)

@param dirZ - (Default: 0.0)

@param testTerrain - (Default: true)

@param testObjects - (Default: true)

@param centerOnly - (Default: false)

[source]

Spring.TestBuildOrder

---

function Spring.TestBuildOrder(
  unitDefID: integer,
  x: number,
  y: number,
  z: number,
  facing: Facing
)
 -> blocking BuildOrderBlockedStatus
 -> featureID integer?

@return featureID - A reclaimable feature in the way.

[source]

Spring.Pos2BuildPos

---

function Spring.Pos2BuildPos(
  unitDefID: integer,
  posX: number,
  posY: number,
  posZ: number,
  buildFacing: number?
)
 -> buildPosX number
 -> buildPosY number
 -> buildPosZ number

@param buildFacing - (Default: 0) one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3

Snaps a position to the building grid

[source]

Spring.ClosestBuildPos

---

function Spring.ClosestBuildPos(
  teamID: integer,
  unitDefID: integer,
  posX: number,
  posY: number,
  posZ: number,
  searchRadius: number,
  minDistance: number,
  buildFacing: number
)
 -> buildPosX number
 -> buildPosY number
 -> buildPosZ number

@param buildFacing - one of SOUTH = 0, EAST = 1, NORTH = 2, WEST = 3

[source]

Spring.GetPositionLosState

---

function Spring.GetPositionLosState(
  posX: number,
  posY: number,
  posZ: number,
  allyTeamID: integer?
)
 -> inLosOrRadar boolean
 -> inLos boolean
 -> inRadar boolean
 -> inJammer boolean

[source]

Spring.IsPosInLos

---

function Spring.IsPosInLos(
  posX: number,
  posY: number,
  posZ: number,
  allyTeamID: integer?
) ->  boolean

[source]

Spring.IsPosInRadar

---

function Spring.IsPosInRadar(
  posX: number,
  posY: number,
  posZ: number,
  allyTeamID: integer?
) ->  boolean

[source]

Spring.IsPosInAirLos

---

function Spring.IsPosInAirLos(
  posX: number,
  posY: number,
  posZ: number,
  allyTeamID: integer?
) ->  boolean

[source]

Spring.GetUnitLosState

---

function Spring.GetUnitLosState(
  unitID: integer,
  allyTeamID: integer?,
  raw: true
) -> bitmask integer?

@param raw - Return a bitmask.

@return bitmask - A bitmask integer, or nil if unitID is invalid.

Bitmask bits:

• 1: LOS_INLOS the unit is currently in the los of the allyteam,
• 2: LOS_INRADAR the unit is currently in radar from the allyteam,
• 4: LOS_PREVLOS the unit has previously been in los from the allyteam,
• 8: LOS_CONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam

[source]

Spring.GetUnitLosState

---

function Spring.GetUnitLosState(
  unitID: integer,
  allyTeamID: integer?,
  raw: false?
) -> los { los: boolean, radar: boolean, ... }?

@param raw - Return a bitmask.

@return los - A table of LOS state, or nil if unitID is invalid.

[source]

Spring.IsUnitInLos

---

function Spring.IsUnitInLos(
  unitID: integer,
  allyTeamID: integer
) -> inLos boolean

[source]

Spring.IsUnitInAirLos

---

function Spring.IsUnitInAirLos(
  unitID: integer,
  allyTeamID: integer
) -> inAirLos boolean

[source]

Spring.IsUnitInRadar

---

function Spring.IsUnitInRadar(
  unitID: integer,
  allyTeamID: integer
) -> inRadar boolean

[source]

Spring.IsUnitInJammer

---

function Spring.IsUnitInJammer(
  unitID: integer,
  allyTeamID: integer
) -> inJammer boolean

[source]

Spring.GetModelRootPiece

---

function Spring.GetModelRootPiece(modelName: string) -> index number

@return index - of the root piece

[source]

Spring.GetModelPieceMap

---

function Spring.GetModelPieceMap(modelName: string) -> pieceInfos table<string,number>?

@return pieceInfos - where keys are piece names and values are indices

[source]

Spring.GetModelPieceList

---

function Spring.GetModelPieceList(modelName: string) -> pieceNames string[]?

[source]

Spring.GetUnitRootPiece

---

function Spring.GetUnitRootPiece(unitID: integer) -> index number

@return index - of the root piece

[source]

Spring.GetUnitPieceMap

---

function Spring.GetUnitPieceMap(unitID: integer) -> pieceInfos table<string,number>?

@return pieceInfos - where keys are piece names and values are indices

[source]

Spring.GetUnitPieceList

---

function Spring.GetUnitPieceList(unitID: integer) -> pieceNames string[]

[source]

Spring.GetUnitPieceInfo

---

function Spring.GetUnitPieceInfo(
  unitID: integer,
  pieceIndex: integer
) -> pieceInfo PieceInfo?

[source]

Spring.GetUnitPiecePosDir

---

function Spring.GetUnitPiecePosDir(
  unitID: integer,
  pieceIndex: integer
)
 -> posX number?
 -> posY number
 -> posZ number
 -> dirX number
 -> dirY number
 -> dirZ number

[source]

Spring.GetUnitPiecePosition

---

function Spring.GetUnitPiecePosition(
  unitID: integer,
  pieceIndex: integer
)
 -> posX number?
 -> posY number
 -> posZ number

[source]

Spring.GetUnitPieceDirection

---

function Spring.GetUnitPieceDirection(
  unitID: integer,
  pieceIndex: integer
)
 -> dirX number?
 -> dirY number
 -> dirZ number

[source]

Spring.GetUnitPieceMatrix

---

function Spring.GetUnitPieceMatrix(unitID: integer)
 -> m11 number?
 -> m12 number
 -> m13 number
 -> m14 number
 -> m21 number
 -> m22 number
 -> m23 number
 -> m24 number
 -> m31 number
 -> m32 number
 -> m33 number
 -> m34 number
 -> m41 number
 -> m42 number
 -> m43 number
 -> m44 number

[source]

Spring.GetFeatureRootPiece

---

function Spring.GetFeatureRootPiece(featureID: integer) -> index number

@return index - of the root piece

[source]

Spring.GetFeaturePieceMap

---

function Spring.GetFeaturePieceMap(featureID: integer) -> pieceInfos table<string,number>

@return pieceInfos - where keys are piece names and values are indices

[source]

Spring.GetFeaturePieceList

---

function Spring.GetFeaturePieceList(featureID: integer) -> pieceNames string[]

[source]

Spring.GetFeaturePieceInfo

---

function Spring.GetFeaturePieceInfo(
  featureID: integer,
  pieceIndex: integer
) -> pieceInfo PieceInfo?

[source]

Spring.GetFeaturePiecePosDir

---

function Spring.GetFeaturePiecePosDir(
  featureID: integer,
  pieceIndex: integer
)
 -> posX number?
 -> posY number
 -> posZ number
 -> dirX number
 -> dirY number
 -> dirZ number

[source]

Spring.GetFeaturePiecePosition

---

function Spring.GetFeaturePiecePosition(
  featureID: integer,
  pieceIndex: integer
)
 -> posX number?
 -> posY number
 -> posZ number

[source]

Spring.GetFeaturePieceDirection

---

function Spring.GetFeaturePieceDirection(
  featureID: integer,
  pieceIndex: integer
)
 -> dirX number?
 -> dirY number
 -> dirZ number

[source]

Spring.GetFeaturePieceMatrix

---

function Spring.GetFeaturePieceMatrix(featureID: integer)
 -> m11 number?
 -> m12 number
 -> m13 number
 -> m14 number
 -> m21 number
 -> m22 number
 -> m23 number
 -> m24 number
 -> m31 number
 -> m32 number
 -> m33 number
 -> m34 number
 -> m41 number
 -> m42 number
 -> m43 number
 -> m44 number

[source]

Spring.GetUnitScriptPiece

---

function Spring.GetUnitScriptPiece(unitID: integer) -> pieceIndices integer[]

[source]

Spring.GetUnitScriptPiece

---

function Spring.GetUnitScriptPiece(
  unitID: integer,
  scriptPiece: integer
) -> pieceIndex integer

[source]

Spring.GetUnitScriptNames

---

function Spring.GetUnitScriptNames(unitID: integer) -> where table<string,number>

@return where - keys are piece names and values are piece indices

[source]

Spring.TraceRayGroundInDirection

---

function Spring.TraceRayGroundInDirection(
  posX: number,
  posY: number,
  posZ: number,
  dirX: number,
  dirY: number,
  dirZ: number,
  testWater: boolean?
)
 -> rayLength number
 -> posX number
 -> posY number
 -> posZ number

@param testWater - (Default: true)

Checks for a ground collision in given direction

[source]

Checks if there is surface (ground, optionally water) towards a vector and returns the distance to the closest hit and its position, if any.

Spring.TraceRayGroundBetweenPositions

---

function Spring.TraceRayGroundBetweenPositions(
  startX: number,
  startY: number,
  startZ: number,
  endX: number,
  endY: number,
  endZ: number,
  testWater: boolean?
)
 -> rayLength number
 -> posX number
 -> posY number
 -> posZ number

@param testWater - (Default: true)

Checks for a ground collision between two positions

[source]

Checks if there is surface (ground, optionally water) between two positions and returns the distance to the closest hit and its position, if any.

Spring.GetRadarErrorParams

---

function Spring.GetRadarErrorParams(allyTeamID: integer)
 -> radarErrorSize number?
 -> baseRadarErrorSize number
 -> baseRadarErrorMult number

@return radarErrorSize - actual radar error size (when allyTeamID is allied to current team) or base radar error size

[source]

Spring.SetAlly

---

function Spring.SetAlly(
  firstAllyTeamID: integer,
  secondAllyTeamID: integer,
  ally: boolean
) ->  nil

Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.

[source]

Spring.SetAllyTeamStartBox

---

function Spring.SetAllyTeamStartBox(
  allyTeamID: integer,
  xMin: number,
  zMin: number,
  xMax: number,
  zMax: number
) ->  nil

@param xMin - left start box boundary (elmos)

@param zMin - top start box boundary (elmos)

@param xMax - right start box boundary (elmos)

@param zMax - bottom start box boundary (elmos)

Changes the start box position of an allyTeam.

[source]

Spring.AssignPlayerToTeam

---

function Spring.AssignPlayerToTeam(
  playerID: integer,
  teamID: integer
) ->  nil

Assigns a player to a team.

[source]

Spring.SetGlobalLos

---

function Spring.SetGlobalLos(
  allyTeamID: integer,
  globallos: boolean
) ->  nil

Changes access to global line of sight for a team and its allies.

[source]

Spring.KillTeam

---

function Spring.KillTeam(teamID: integer) ->  nil

Will declare a team to be dead (no further orders can be assigned to such teams units).

[source]

Gaia team cannot be killed.

Spring.GameOver

---

function Spring.GameOver(winningAllyTeamIDs: integer[])

@param winningAllyTeamIDs - A list of winning ally team IDs. Pass multiple winners to declare a draw. Pass no arguments if undecided (e.g. when dropped from the host).

Declare game over.

[source]

@returns integer Number of accepted (valid) ally teams.

Spring.SetTidal

---

function Spring.SetTidal(strength: number) ->  nil

Set tidal strength

[source]

Spring.SetWind

---

function Spring.SetWind(
  minStrength: number,
  maxStrength: number
) ->  nil

Set wind strength

[source]

Spring.AddTeamResource

---

function Spring.AddTeamResource(
  teamID: integer,
  type: ResourceName,
  amount: number
) ->  nil

Adds metal or energy resources to the specified team.

[source]

Spring.UseTeamResource

---

function Spring.UseTeamResource(
  teamID: integer,
  type: ResourceName,
  amount: number
) -> hadEnough boolean

@param type - Resource type.

@param amount - Amount of resource to use.

@return hadEnough - True if enough of the resource type was available and was consumed, otherwise false.

Consumes metal or energy resources of the specified team.

[source]

Spring.UseTeamResource

---

function Spring.UseTeamResource(
  teamID: integer,
  amount: ResourceUsage
) -> hadEnough boolean

@return hadEnough - True if enough of the resource type(s) were available and was consumed, otherwise false.

Consumes metal and/or energy resources of the specified team.

[source]

Spring.SetTeamResource

---

function Spring.SetTeamResource(
  teamID: integer,
  resource: (ResourceName|StorageName),
  amount: number
) ->  nil

[source]

Spring.SetTeamShareLevel

---

function Spring.SetTeamShareLevel(
  teamID: integer,
  type: ResourceName,
  amount: number
) ->  nil

Changes the resource amount for a team beyond which resources aren’t stored but transferred to other allied teams if possible.

[source]

Spring.ShareTeamResource

---

function Spring.ShareTeamResource(
  teamID_src: integer,
  teamID_recv: integer,
  type: ResourceName,
  amount: number
) ->  nil

Transfers resources between two teams.

[source]

Spring.SetGameRulesParam

---

function Spring.SetGameRulesParam(
  paramName: string,
  paramValue: (number|string)?,
  losAccess: losAccess?
) ->  nil

@param paramValue - numeric paramValues in quotes will be converted to number.

[source]

Spring.SetTeamRulesParam

---

function Spring.SetTeamRulesParam(
  teamID: integer,
  paramName: string,
  paramValue: (number|string)?,
  losAccess: losAccess?
) ->  nil

@param paramValue - numeric paramValues in quotes will be converted to number.

[source]

Spring.SetPlayerRulesParam

---

function Spring.SetPlayerRulesParam(
  playerID: integer,
  paramName: string,
  paramValue: (number|string)?,
  losAccess: losAccess?
) ->  nil

@param paramValue - numeric paramValues in quotes will be converted to number.

[source]

Spring.SetUnitRulesParam

---

function Spring.SetUnitRulesParam(
  unitID: integer,
  paramName: string,
  paramValue: (number|string)?,
  losAccess: losAccess?
) ->  nil

@param paramValue - numeric paramValues in quotes will be converted to number.

[source]

Spring.SetFeatureRulesParam

---

function Spring.SetFeatureRulesParam(
  featureID: integer,
  paramName: string,
  paramValue: (number|string)?,
  losAccess: losAccess?
) ->  nil

@param paramValue - numeric paramValues in quotes will be converted to number.

[source]

Spring.CallCOBScript

---

function Spring.CallCOBScript(
  unitID: integer,
  funcName: (integer|string)?,
  retArgs: integer,
  ...: any
) ->  number ...

@param funcName - Function ID or name.

@param retArgs - Number of values to return.

@param ... - Arguments

[source]

Spring.GetCOBScriptID

---

function Spring.GetCOBScriptID(
  unitID: integer,
  funcName: string
) -> funcID integer?

[source]

Spring.CreateUnit

---

function Spring.CreateUnit(
  unitDef: (string|integer),
  posX: number,
  posY: number,
  posZ: number,
  facing: Facing,
  teamID: integer,
  build: boolean?,
  flattenGround: boolean?,
  unitID: integer?,
  builderID: integer?
) -> unitID integer?

@param unitDef - UnitDef name or ID.

@param build - (Default: false) The unit is created in “being built” state with zero buildProgress.

@param flattenGround - (Default: true) The unit flattens ground, if it normally does so.

@param unitID - Request a specific unitID.

@return unitID - The ID of the created unit, or nil if the unit could not be created.

[source]

@see Spring.DestroyUnit

Spring.DestroyUnit

---

function Spring.DestroyUnit(
  unitID: integer,
  selfd: boolean?,
  reclaimed: boolean?,
  attackerID: integer?,
  cleanupImmediately: boolean?
) ->  nil

@param selfd - (Default: false) makes the unit act like it self-destructed.

@param reclaimed - (Default: false) don’t show any DeathSequences, don’t leave a wreckage. This does not give back the resources to the team!

@param cleanupImmediately - (Default: false) stronger version of reclaimed, removes the unit unconditionally and makes its ID available for immediate reuse (otherwise it takes a few frames)

[source]

@see Spring.CreateUnit

Spring.TransferUnit

---

function Spring.TransferUnit(
  unitID: integer,
  newTeamID: integer,
  given: boolean?
) ->  nil

@param given - (Default: true) if false, the unit is captured.

[source]

Spring.SetUnitCosts

---

function Spring.SetUnitCosts(
  unitID: integer,
  where: table<number,number>
) ->  nil

@param where - keys and values are, respectively and in this order: buildTime=amount, metalCost=amount, energyCost=amount

[source]

Spring.SetUnitResourcing

---

function Spring.SetUnitResourcing(
  unitID: integer,
  res: string,
  amount: number
) ->  nil

[source]

Spring.SetUnitResourcing

---

function Spring.SetUnitResourcing(
  unitID: integer,
  res: table<string,number>
) ->  nil

@param res - keys are: “[u|c][u|m][m|e]” unconditional | conditional, use | make, metal | energy. Values are amounts

[source]

Spring.SetUnitStorage

---

function Spring.SetUnitStorage(
  unitID: integer,
  res: string,
  amount: number
)

[source]

Spring.SetUnitStorage

---

function Spring.SetUnitStorage(
  unitID: integer,
  res: ResourceUsage
)

@param res - keys are: “[m|e]” metal | energy. Values are amounts

[source]

Spring.SetUnitTooltip

---

function Spring.SetUnitTooltip(
  unitID: integer,
  tooltip: string
) ->  nil

[source]

Spring.SetUnitHealth

---

function Spring.SetUnitHealth(
  unitID: integer,
  health: (number|SetUnitHealthAmounts)
) ->  nil

@param health - If a number, sets the units health to that value. Pass a table to update health, capture progress, paralyze damage, and build progress.

[source]

Note, if your game’s custom shading framework doesn’t support reverting into nanoframes then reverting into nanoframes via the “build” tag will fail to render properly.

@see SetUnitHealthAmounts

Spring.SetUnitMaxHealth

---

function Spring.SetUnitMaxHealth(
  unitID: integer,
  maxHealth: number
) ->  nil

[source]

Spring.SetUnitStockpile

---

function Spring.SetUnitStockpile(
  unitID: integer,
  stockpile: number?,
  buildPercent: number?
) ->  nil

[source]

Spring.SetUnitUseWeapons

---

function Spring.SetUnitUseWeapons(
  unitID: integer,
  forceUseWeapons: number?,
  allowUseWeapons: number?
) ->  nil

[source]

Spring.SetUnitWeaponState

---

function Spring.SetUnitWeaponState(
  unitID: integer,
  weaponNum: number,
  states: WeaponState
) ->  nil

[source]

Spring.SetUnitWeaponState

---

function Spring.SetUnitWeaponState(
  unitID: integer,
  weaponNum: number,
  key: string,
  value: number
) ->  nil

[source]

Spring.SetUnitWeaponDamages

---

function Spring.SetUnitWeaponDamages(
  unitID: integer,
  weaponNum: (number|"selfDestruct"|"explode"),
  damages: WeaponDamages
) ->  nil

[source]

Spring.SetUnitWeaponDamages

---

function Spring.SetUnitWeaponDamages(
  unitID: integer,
  weaponNum: (number|"selfDestruct"|"explode"),
  key: string,
  value: number
) ->  nil

[source]

Spring.SetUnitMaxRange

---

function Spring.SetUnitMaxRange(
  unitID: integer,
  maxRange: number
) ->  nil

[source]

Spring.SetUnitExperience

---

function Spring.SetUnitExperience(
  unitID: integer,
  experience: number
) ->  nil

[source]

@see Spring.GetUnitExperience

Spring.AddUnitExperience

---

function Spring.AddUnitExperience(
  unitID: integer,
  deltaExperience: number
) ->  nil

@param deltaExperience - Can be negative to subtract, but the unit will never have negative total afterwards

[source]

@see Spring.GetUnitExperience

Spring.SetUnitArmored

---

function Spring.SetUnitArmored(
  unitID: integer,
  armored: boolean?,
  armorMultiple: number?
) ->  nil

[source]

Spring.SetUnitLosMask

---

function Spring.SetUnitLosMask(
  unitID: integer,
  allyTeam: number,
  losTypes: (number|table)
) ->  nil

[source]

The 3rd argument is either the bit-and combination of the following numbers:

LOS_INLOS = 1 LOS_INRADAR = 2 LOS_PREVLOS = 4 LOS_CONTRADAR = 8

or a table of the following form:

losTypes = { [los = boolean,] [radar = boolean,] [prevLos = boolean,] [contRadar = boolean] }

Spring.SetUnitLosState

---

function Spring.SetUnitLosState(
  unitID: integer,
  allyTeam: number,
  los: (number|table)
) ->  nil

[source]

Spring.SetUnitCloak

---

function Spring.SetUnitCloak(
  unitID: integer,
  cloak: (boolean|number),
  cloakArg: (boolean|number)
) ->  nil

[source]

If the 2nd argument is a number, the value works like this: 1:=normal cloak 2:=for free cloak (cost no E) 3:=for free + no decloaking (except the unit is stunned) 4:=ultimate cloak (no ecost, no decloaking, no stunned decloak)

The decloak distance is only changed:

• if the 3th argument is a number or a boolean.
• if the boolean is false it takes the default decloak distance for that unitdef,
• if the boolean is true it takes the absolute value of it.

Spring.SetUnitStealth

---

function Spring.SetUnitStealth(
  unitID: integer,
  stealth: boolean
) ->  nil

[source]

Spring.SetUnitSonarStealth

---

function Spring.SetUnitSonarStealth(
  unitID: integer,
  sonarStealth: boolean
) ->  nil

[source]

Spring.SetUnitSeismicSignature

---

function Spring.SetUnitSeismicSignature(
  unitID: integer,
  seismicSignature: number
) ->  nil

[source]

Spring.SetUnitAlwaysVisible

---

function Spring.SetUnitAlwaysVisible(
  unitID: integer,
  alwaysVisible: boolean
) ->  nil

[source]

Spring.SetUnitUseAirLos

---

function Spring.SetUnitUseAirLos(
  unitID: integer,
  useAirLos: boolean
) ->  nil

[source]

Spring.SetUnitMetalExtraction

---

function Spring.SetUnitMetalExtraction(
  unitID: integer,
  depth: number,
  range: number?
) ->  nil

@param depth - corresponds to metal extraction rate

@param range - similar to “extractsMetal” in unitDefs.

[source]

Spring.SetUnitHarvestStorage

---

function Spring.SetUnitHarvestStorage(
  unitID: integer,
  metal: number
) ->  nil

See also harvestStorage UnitDef tag.

[source]

Spring.SetUnitBuildParams

---

function Spring.SetUnitBuildParams(
  unitID: integer,
  paramName: string,
  value: (number|boolean)
) ->  nil

@param paramName - one of buildRange|buildDistance|buildRange3D

@param value - boolean when paramName is buildRange3D, otherwise number.

[source]

Spring.SetUnitBuildSpeed

---

function Spring.SetUnitBuildSpeed(
  builderID: integer,
  buildSpeed: number,
  repairSpeed: number?,
  reclaimSpeed: number?,
  captureSpeed: number?,
  terraformSpeed: number?
) ->  nil

[source]

Spring.SetUnitNanoPieces

---

function Spring.SetUnitNanoPieces(
  builderID: integer,
  pieces: table
) ->  nil

[source]

This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end Use it!

Spring.SetUnitBlocking

---

function Spring.SetUnitBlocking(
  unitID: integer,
  isBlocking: boolean?,
  isSolidObjectCollidable: boolean?,
  isProjectileCollidable: boolean?,
  isRaySegmentCollidable: boolean?,
  crushable: boolean?,
  blockEnemyPushing: boolean?,
  blockHeightChanges: boolean?
) -> isBlocking boolean

@param isBlocking - If true add this unit to the GroundBlockingMap, but only if it collides with solid objects (or is being set to collide with the isSolidObjectCollidable argument). If false, remove this unit from the GroundBlockingMap. No change if nil.

@param isSolidObjectCollidable - Enable or disable collision with solid objects, or no change if nil.

@param isProjectileCollidable - Enable or disable collision with projectiles, or no change if nil.

@param isRaySegmentCollidable - Enable or disable collision with ray segments, or no change if nil.

@param crushable - Enable or disable crushable, or no change if nil.

@param blockEnemyPushing - Enable or disable blocking enemy pushing, or no change if nil.

@param blockHeightChanges - Enable or disable blocking height changes, or no change if nil.

[source]

Spring.SetUnitCrashing

---

function Spring.SetUnitCrashing(
  unitID: integer,
  crashing: boolean
) -> success boolean

[source]

Spring.SetUnitShieldState

---

function Spring.SetUnitShieldState(
  unitID: integer,
  weaponID: integer?,
  enabled: boolean?,
  power: number?
) ->  nil

@param weaponID - (Default: -1)

[source]

Spring.SetUnitShieldRechargeDelay

---

function Spring.SetUnitShieldRechargeDelay(
  unitID: integer,
  weaponID: integer?,
  rechargeTime: number?
) ->  nil

@param weaponID - (optional if the unit only has one shield)

@param rechargeTime - (in seconds; emulates a regular hit if nil)

[source]

Spring.SetUnitFlanking

---

function Spring.SetUnitFlanking(
  unitID: integer,
  type: string,
  arg1: number,
  y: number?,
  z: number?
) ->  nil

@param type - “dir”|”minDamage”|”maxDamage”|”moveFactor”|”mode”

@param arg1 - x

minDamage

maxDamage

moveFactor

mode

@param y - only when type is “dir”

@param z - only when type is “dir”

[source]

Spring.SetUnitPhysicalStateBit

---

function Spring.SetUnitPhysicalStateBit(
  unitID: integer,
  Physical
) ->  nil

[source]

Spring.GetUnitPhysicalState

---

function Spring.GetUnitPhysicalState(unitID: integer) -> Unit number

@return Unit - ‘s PhysicalState bitmask

[source]

Spring.SetUnitNeutral

---

function Spring.SetUnitNeutral(
  unitID: integer,
  neutral: boolean
) -> setNeutral boolean?

[source]

Spring.SetUnitTarget

---

function Spring.SetUnitTarget(
  unitID: integer,
  enemyUnitID: integer?,
  dgun: boolean?,
  userTarget: boolean?,
  weaponNum: number?
) -> success boolean

@param enemyUnitID - when nil drops the units current target.

@param dgun - (Default: false)

@param userTarget - (Default: false)

@param weaponNum - (Default: -1)

Defines a unit’s target.

[source]

Spring.SetUnitTarget

---

function Spring.SetUnitTarget(
  unitID: integer,
  x: number?,
  y: number?,
  z: number?,
  dgun: boolean?,
  userTarget: boolean?,
  weaponNum: number?
) -> success boolean

@param x - when nil or not passed it will drop target and ignore other parameters

@param dgun - (Default: false)

@param userTarget - (Default: false)

@param weaponNum - (Default: -1)

[source]

Spring.SetUnitMidAndAimPos

---

function Spring.SetUnitMidAndAimPos(
  unitID: integer,
  mpX: number,
  mpY: number,
  mpZ: number,
  apX: number,
  apY: number,
  apZ: number,
  relative: boolean?
) -> success boolean

@param mpX - new middle positionX of unit

@param mpY - new middle positionY of unit

@param mpZ - new middle positionZ of unit

@param apX - new positionX that enemies aim at on this unit

@param apY - new positionY that enemies aim at on this unit

@param apZ - new positionZ that enemies aim at on this unit

@param relative - (Default: false) are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!

[source]

Spring.SetUnitRadiusAndHeight

---

function Spring.SetUnitRadiusAndHeight(
  unitID: integer,
  radius: number,
  height: number
) -> success boolean

[source]

Spring.SetUnitBuildeeRadius

---

function Spring.SetUnitBuildeeRadius(
  unitID: integer,
  build: number
) ->  nil

@param build - radius for when targeted by build, repair, reclaim-type commands.

[source]

Sets the unit’s radius for when targeted by build, repair, reclaim-type commands.

Spring.SetUnitPieceParent

---

function Spring.SetUnitPieceParent(
  unitID: integer,
  AlteredPiece: number,
  ParentPiece: number
) ->  nil

Changes the pieces hierarchy of a unit by attaching a piece to a new parent.

[source]

Spring.SetUnitPieceMatrix

---

function Spring.SetUnitPieceMatrix(
  unitID: integer,
  pieceNum: number,
  matrix: number[]
) ->  nil

@param matrix - an array of 16 floats

Sets the local (i.e. parent-relative) matrix of the given piece.

[source]

If any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed.

Spring.SetUnitCollisionVolumeData

---

function Spring.SetUnitCollisionVolumeData(
  unitID: integer,
  scaleX: number,
  scaleY: number,
  scaleZ: number,
  offsetX: number,
  offsetY: number,
  offsetZ: number,
  vType: number,
  tType: number,
  Axis: number
) -> enum nil

@return enum - COLVOL_TYPES { COLVOL_TYPE_DISABLED = -1, COLVOL_TYPE_ELLIPSOID = 0, COLVOL_TYPE_CYLINDER, COLVOL_TYPE_BOX, COLVOL_TYPE_SPHERE, COLVOL_NUM_TYPES // number of non-disabled collision volume types }; enum COLVOL_TESTS { COLVOL_TEST_DISC = 0, COLVOL_TEST_CONT = 1, COLVOL_NUM_TESTS = 2 // number of tests }; enum COLVOL_AXES { COLVOL_AXIS_X = 0, COLVOL_AXIS_Y = 1, COLVOL_AXIS_Z = 2, COLVOL_NUM_AXES = 3 // number of collision volume axes };

[source]

Spring.SetUnitPieceCollisionVolumeData

---

function Spring.SetUnitPieceCollisionVolumeData(
  unitID: integer,
  pieceIndex: number,
  enable: boolean,
  scaleX: number,
  scaleY: number,
  scaleZ: number,
  offsetX: number,
  offsetY: number,
  offsetZ: number,
  volumeType: number?,
  primaryAxis: number?
) ->  nil

[source]

Spring.SetUnitPieceVisible

---

function Spring.SetUnitPieceVisible(
  unitID: integer,
  pieceIndex: number,
  visible: boolean
) ->  nil

[source]

Spring.SetUnitSensorRadius

---

function Spring.SetUnitSensorRadius(
  unitID: integer,
  type: ("los"|"airLos"|"radar"|"sonar"|"seismic"|"radarJammer"...),
  radius: number
) -> New number?

@return New - radius, or nil if unit is invalid.

[source]

Spring.SetUnitPosErrorParams

---

function Spring.SetUnitPosErrorParams(
  unitID: integer,
  posErrorVectorX: number,
  posErrorVectorY: number,
  posErrorVectorZ: number,
  posErrorDeltaX: number,
  posErrorDeltaY: number,
  posErrorDeltaZ: number,
  nextPosErrorUpdate: number?
) ->  nil

Sets a unit’s radar wobble

Controls how much a unit’s radar dot will wobble. Note that setting this above the allyTeam’s default wobble may result in the edgemost dot positions failing to register in ray traces, i.e. things like native “is under cursor” checks and some Lua interfaces.

[source]

Spring.SetUnitMoveGoal

---

function Spring.SetUnitMoveGoal(
  unitID: integer,
  goalX: number,
  goalY: number,
  goalZ: number,
  goalRadius: number?,
  moveSpeed: number?,
  moveRaw: boolean?
) ->  nil

Used by default commands to get in build-, attackrange etc.

[source]

Spring.SetUnitLandGoal

---

function Spring.SetUnitLandGoal(
  unitID: integer,
  goalX: number,
  goalY: number,
  goalZ: number,
  goalRadius: number?
) ->  nil

Used in conjunction with Spring.UnitAttach et al. to re-implement old airbase & fuel system in Lua.

[source]

Spring.ClearUnitGoal

---

function Spring.ClearUnitGoal(unitID: integer) ->  nil

[source]

Spring.SetUnitPhysics

---

function Spring.SetUnitPhysics(
  unitID: integer,
  posX: number,
  posY: number,
  posZ: number,
  velX: number,
  velY: number,
  velZ: number,
  rotX: number,
  rotY: number,
  rotZ: number,
  dragX: number,
  dragY: number,
  dragZ: number
) ->  nil

[source]

Spring.SetUnitMass

---

function Spring.SetUnitMass(
  unitID: integer,
  mass: number
) ->  nil

[source]

Spring.SetUnitPosition

---

function Spring.SetUnitPosition(
  unitID: integer,
  x: number,
  z: number,
  floating: boolean?
) ->  nil

@param floating - (Default: false) If true, over water the position is on surface. If false, on seafloor.

Set unit position (2D)

[source]

Sets a unit’s position in 2D, at terrain height.

Spring.SetUnitPosition

---

function Spring.SetUnitPosition(
  unitID: integer,
  x: number,
  y: number,
  z: number
) ->  nil

Set unit position (3D)

[source]

Sets a unit’s position in 3D, at an arbitrary height.

Spring.SetUnitRotation

---

function Spring.SetUnitRotation(
  unitID: integer,
  pitch: number,
  yaw: number,
  roll: number
) ->  nil

@param pitch - Rotation in X axis

@param yaw - Rotation in Y axis

@param roll - Rotation in Z axis

[source]

Note: PYR order

Spring.SetUnitDirection

---

function Spring.SetUnitDirection(
  unitID: integer,
  frontx: number,
  fronty: number,
  frontz: number
) ->  nil

[source]

Set unit front direction vector. The vector is normalized in the engine.

@deprecated It’s strongly that you use the overload that accepts a right direction as frontDir alone doesn’t define object orientation.

Spring.SetUnitDirection

---

function Spring.SetUnitDirection(
  unitID: integer,
  frontx: number,
  fronty: number,
  frontz: number,
  rightx: number,
  righty: number,
  rightz: number
) ->  nil

[source]

Set unit front and right direction vectors.

Both vectors will be normalized in the engine.

Spring.SetUnitHeadingAndUpDir

---

function Spring.SetUnitHeadingAndUpDir(
  unitID: integer,
  heading: Heading,
  upx: number,
  upy: number,
  upz: number
) ->  nil

[source]

Use this call to set up unit direction in a robust way. If unit was completely upright, new {upx, upy, upz} direction will be used as new “up” vector, the rotation set by “heading” will remain preserved.

Spring.SetUnitVelocity

---

function Spring.SetUnitVelocity(
  unitID: integer,
  velX: number,
  velY: number,
  velZ: number
) ->  nil

[source]

Spring.SetFactoryBuggerOff

---

function Spring.SetFactoryBuggerOff(
  unitID: integer,
  buggerOff: boolean?,
  offset: number?,
  radius: number?,
  relHeading: Heading?,
  spherical: boolean?,
  forced: boolean?
) -> buggerOff number?

[source]

Spring.BuggerOff

---

function Spring.BuggerOff(
  x: number,
  y: number,
  z: number?,
  radius: number,
  teamID: integer,
  spherical: boolean?,
  forced: boolean?,
  excludeUnitID: integer?,
  excludeUnitDefIDs: number[]?
) ->  nil

@param z - uses ground height when unspecified

@param spherical - (Default: true)

@param forced - (Default: true)

[source]

Spring.AddUnitDamage

---

function Spring.AddUnitDamage(
  unitID: integer,
  damage: number,
  paralyze: number?,
  attackerID: integer?,
  weaponID: integer?,
  impulseX: number?,
  impulseY: number?,
  impulseZ: number?
) ->  nil

@param paralyze - (Default: 0) equals to the paralyzetime in the WeaponDef.

@param attackerID - (Default: -1)

@param weaponID - (Default: -1)

[source]

Spring.AddUnitImpulse

---

function Spring.AddUnitImpulse(
  unitID: integer,
  x: number,
  y: number,
  z: number,
  decayRate: number?
) ->  nil

[source]

Spring.AddUnitSeismicPing

---

function Spring.AddUnitSeismicPing(
  unitID: integer,
  pindSize: number
) ->  nil

[source]

Spring.AddUnitResource

---

function Spring.AddUnitResource(
  unitID: integer,
  resource: string,
  amount: number
) ->  nil

@param resource - “m” | “e”

[source]

Spring.UseUnitResource

---

function Spring.UseUnitResource(
  unitID: integer,
  resource: ResourceName,
  amount: number
) -> okay boolean?

[source]

Spring.UseUnitResource

---

function Spring.UseUnitResource(
  unitID: integer,
  resources: ResourceUsage
) -> okay boolean?

[source]

Spring.AddObjectDecal

---

function Spring.AddObjectDecal(unitID: integer) ->  nil

[source]

Spring.RemoveObjectDecal

---

function Spring.RemoveObjectDecal(unitID: integer) ->  nil

[source]

Spring.AddGrass

---

function Spring.AddGrass(
  x: number,
  z: number
) ->  nil

[source]

Spring.RemoveGrass

---

function Spring.RemoveGrass(
  x: number,
  z: number
) ->  nil

[source]

Spring.CreateFeature

---

function Spring.CreateFeature(
  featureDef: (string|integer),
  x: number,
  y: number,
  z: number,
  heading: Heading?,
  AllyTeamID: integer?,
  featureID: integer?
) -> featureID integer

@param featureDef - name or id

[source]

Spring.DestroyFeature

---

function Spring.DestroyFeature(featureDefID: integer) ->  nil

[source]

Spring.TransferFeature

---

function Spring.TransferFeature(
  featureDefID: integer,
  teamID: integer
) ->  nil

Feature Control

[source]

Spring.SetFeatureAlwaysVisible

---

function Spring.SetFeatureAlwaysVisible(
  featureID: integer,
  enable: boolean
) ->  nil

[source]

Spring.SetFeatureUseAirLos

---

function Spring.SetFeatureUseAirLos(
  featureID: integer,
  useAirLos: boolean
) ->  nil

[source]

Spring.SetFeatureHealth

---

function Spring.SetFeatureHealth(
  featureID: integer,
  health: number
) ->  nil

[source]

Spring.SetFeatureMaxHealth

---

function Spring.SetFeatureMaxHealth(
  featureID: integer,
  maxHealth: number
) ->  nil

@param maxHealth - minimum 0.1

[source]

Spring.SetFeatureReclaim

---

function Spring.SetFeatureReclaim(
  featureID: integer,
  reclaimLeft: number
) ->  nil

[source]

Spring.SetFeatureResources

---

function Spring.SetFeatureResources(
  featureID: integer,
  metal: number,
  energy: number,
  reclaimTime: number?,
  reclaimLeft: number?,
  featureDefMetal: number?,
  featureDefEnergy: number?
) ->  nil

[source]

Spring.SetFeatureResurrect

---

function Spring.SetFeatureResurrect(
  featureID: integer,
  unitDef: (string|integer),
  facing: Facing?,
  progress: number?
) ->  nil

@param unitDef - Can be a number id or a string name, this allows cancelling resurrection by passing -1.

@param facing - (Default: "south")

@param progress - Set the level of progress.

[source]

Spring.SetFeatureMoveCtrl

---

function Spring.SetFeatureMoveCtrl(
  featureID: integer,
  enabled: true,
  initialVelocityX: number?,
  initialVelocityY: number?,
  initialVelocityZ: number?,
  accelerationX: number?,
  accelerationY: number?,
  accelerationZ: number?
)

@param enabled - Enable feature movement.

@param initialVelocityX - Initial velocity on X axis, or nil for no change.

@param initialVelocityY - Initial velocity on Y axis, or nil for no change.

@param initialVelocityZ - Initial velocity on Z axis, or nil for no change.

@param accelerationX - Acceleration per frame on X axis, or nil for no change.

@param accelerationY - Acceleration per frame on Y axis, or nil for no change.

@param accelerationZ - Acceleration per frame on Z axis, or nil for no change.

Enable feature movement control.

[source]

Spring.SetFeatureMoveCtrl

---

function Spring.SetFeatureMoveCtrl(
  featureID: integer,
  enabled: false,
  velocityMaskX: number?,
  velocityMaskY: number?,
  velocityMaskZ: number?,
  impulseMaskX: number?,
  impulseMaskY: number?,
  impulseMaskZ: number?,
  movementMaskX: number?,
  movementMaskY: number?,
  movementMaskZ: number?
)

@param enabled - Disable feature movement.

@param velocityMaskX - Lock velocity change in X dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.

@param velocityMaskY - Lock velocity change in Y dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.

@param velocityMaskZ - Lock velocity change in Z dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.

@param impulseMaskX - Lock impulse in X dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.

@param impulseMaskY - Lock impulse in Y dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.

@param impulseMaskZ - Lock impulse in Z dimension when not using MoveCtrl. 0 to lock, non-zero to allow, or nil to for no change.

@param movementMaskX - Lock move in X dimension when not using MoveCtrl. 0 to lock the axis, non-zero to allow, or nil for no change.

@param movementMaskY - Lock move in Y dimension when not using MoveCtrl. 0 to lock the axis, non-zero to allow, or nil for no change.

@param movementMaskZ - Lock move in Z dimension when not using MoveCtrl. 0 to lock the axis, non-zero to allow, or nil for no change.

Disable feature movement control.

Optional parameter allow physics vectors to build when not using MoveCtrl.

It is necessary to unlock feature movement on x, z axis before changing feature physics.

For example:

-- Unlock all movement before setting velocity.
Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)

-- Set velocity.
Spring.SetFeatureVelocity(featureID,10,0,10)

[source]

Spring.SetFeaturePhysics

---

function Spring.SetFeaturePhysics(
  featureID: integer,
  posX: number,
  posY: number,
  posZ: number,
  velX: number,
  velY: number,
  velZ: number,
  rotX: number,
  rotY: number,
  rotZ: number,
  dragX: number,
  dragY: number,
  dragZ: number
) ->  nil

[source]

Spring.SetFeatureMass

---

function Spring.SetFeatureMass(
  featureID: integer,
  mass: number
) ->  nil

[source]

Spring.SetFeaturePosition

---

function Spring.SetFeaturePosition(
  featureID: integer,
  x: number,
  y: number,
  z: number,
  snapToGround: boolean?
) ->  nil

[source]

Spring.SetFeatureRotation

---

function Spring.SetFeatureRotation(
  featureID: integer,
  pitch: number,
  yaw: number,
  roll: number
) ->  nil

@param pitch - Rotation in X axis

@param yaw - Rotation in Y axis

@param roll - Rotation in Z axis

[source]

Note: PYR order

Spring.SetFeatureDirection

---

function Spring.SetFeatureDirection(
  featureID: integer,
  frontx: number,
  fronty: number,
  frontz: number
) ->  nil

[source]

Set feature front direction vector. The vector is normalized in the engine.

@deprecated It’s strongly that you use the overload that accepts a right direction as frontDir alone doesn’t define object orientation.

Spring.SetFeatureDirection

---

function Spring.SetFeatureDirection(
  featureID: integer,
  frontx: number,
  fronty: number,
  frontz: number,
  rightx: number,
  righty: number,
  rightz: number
) ->  nil

[source]

Set feature front and right direction vectors.

Both vectors will be normalized in the engine.

Spring.SetFeatureHeadingAndUpDir

---

function Spring.SetFeatureHeadingAndUpDir(
  featureID: integer,
  heading: Heading,
  upx: number,
  upy: number,
  upz: number
) ->  nil

[source]

Use this call to set up feature direction in a robust way. If feature was completely upright, new {upx, upy, upz} direction will be used as new “up” vector, the rotation set by “heading” will remain preserved.

Spring.SetFeatureVelocity

---

function Spring.SetFeatureVelocity(
  featureID: integer,
  velX: number,
  velY: number,
  velZ: number
) ->  nil

[source]

Spring.SetFeatureBlocking

---

function Spring.SetFeatureBlocking(
  featureID: integer,
  isBlocking: boolean?,
  isSolidObjectCollidable: boolean?,
  isProjectileCollidable: boolean?,
  isRaySegmentCollidable: boolean?,
  crushable: boolean?,
  blockEnemyPushing: boolean?,
  blockHeightChanges: boolean?
) -> isBlocking boolean

@param isBlocking - If true add this feature to the GroundBlockingMap, but only if it collides with solid objects (or is being set to collide with the isSolidObjectCollidable argument). If false, remove this feature from the GroundBlockingMap. No change if nil.

@param isSolidObjectCollidable - Enable or disable collision with solid objects, or no change if nil.

@param isProjectileCollidable - Enable or disable collision with projectiles, or no change if nil.

@param isRaySegmentCollidable - Enable or disable collision with ray segments, or no change if nil.

@param crushable - Enable or disable crushable, or no change if nil.

@param blockEnemyPushing - Enable or disable blocking enemy pushing, or no change if nil.

@param blockHeightChanges - Enable or disable blocking height changes, or no change if nil.

[source]

Spring.SetFeatureNoSelect

---

function Spring.SetFeatureNoSelect(
  featureID: integer,
  noSelect: boolean
) ->  nil

[source]

Spring.SetFeatureMidAndAimPos

---

function Spring.SetFeatureMidAndAimPos(
  featureID: integer,
  mpX: number,
  mpY: number,
  mpZ: number,
  apX: number,
  apY: number,
  apZ: number,
  relative: boolean?
) -> success boolean

[source]

Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.

Spring.SetFeatureRadiusAndHeight

---

function Spring.SetFeatureRadiusAndHeight(
  featureID: integer,
  radius: number,
  height: number
) -> success boolean

[source]

Spring.SetFeatureCollisionVolumeData

---

function Spring.SetFeatureCollisionVolumeData(
  featureID: integer,
  scaleX: number,
  scaleY: number,
  scaleZ: number,
  offsetX: number,
  offsetY: number,
  offsetZ: number,
  vType: number,
  tType: number,
  Axis: number
) ->  nil

[source]

Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.

Spring.SetFeaturePieceCollisionVolumeData

---

function Spring.SetFeaturePieceCollisionVolumeData(
  featureID: integer,
  pieceIndex: number,
  enable: boolean,
  scaleX: number,
  scaleY: number,
  scaleZ: number,
  offsetX: number,
  offsetY: number,
  offsetZ: number,
  Axis: number,
  volumeType: number,
  primaryAxis: number?
) ->  nil

[source]

Spring.SetFeaturePieceVisible

---

function Spring.SetFeaturePieceVisible(
  featureID: integer,
  pieceIndex: number,
  visible: boolean
) ->  nil

[source]

Spring.SetProjectileAlwaysVisible

---

function Spring.SetProjectileAlwaysVisible(
  projectileID: integer,
  alwaysVisible: boolean
) ->  nil

[source]

Spring.SetProjectileUseAirLos

---

function Spring.SetProjectileUseAirLos(
  projectileID: integer,
  useAirLos: boolean
) ->  nil

[source]

Spring.SetProjectileMoveControl

---

function Spring.SetProjectileMoveControl(
  projectileID: integer,
  enable: boolean
) ->  nil

Disables engine movecontrol, so lua can fully control the physics.

[source]

Spring.SetProjectilePosition

---

function Spring.SetProjectilePosition(
  projectileID: integer,
  posX: number?,
  posY: number?,
  posZ: number?
) ->  nil

@param posX - (Default: 0)

@param posY - (Default: 0)

@param posZ - (Default: 0)

[source]

Spring.SetProjectileVelocity

---

function Spring.SetProjectileVelocity(
  projectileID: integer,
  velX: number?,
  velY: number?,
  velZ: number?
) ->  nil

@param velX - (Default: 0)

@param velY - (Default: 0)

@param velZ - (Default: 0)

[source]

Spring.SetProjectileCollision

---

function Spring.SetProjectileCollision(projectileID: integer) ->  nil

[source]

Spring.SetProjectileTarget

---

function Spring.SetProjectileTarget(
  projectileID: integer,
  arg1: number?,
  arg2: number?,
  posZ: number?
) -> validTarget boolean?

@param arg1 - (Default: 0) targetID or posX

@param arg2 - (Default: 0) targetType or posY

@param posZ - (Default: 0)

[source]

targetTypeStr can be one of: ‘u’ - unit ‘f’ - feature ‘p’ - projectile while targetTypeInt is one of: string.byte(‘g’) := GROUND string.byte(‘u’) := UNIT string.byte(‘f’) := FEATURE string.byte(‘p’) := PROJECTILE

Spring.SetProjectileTimeToLive

---

function Spring.SetProjectileTimeToLive(
  projectileID: integer,
  ttl: number
) ->  nil

@param ttl - Remaining time to live in frames

[source]

Spring.SetProjectileIsIntercepted

---

function Spring.SetProjectileIsIntercepted(projectileID: integer) ->  nil

[source]

Spring.SetProjectileDamages

---

function Spring.SetProjectileDamages(
  unitID: integer,
  weaponNum: number,
  key: string,
  value: number
) ->  nil

[source]

Spring.SetProjectileIgnoreTrackingError

---

function Spring.SetProjectileIgnoreTrackingError(
  projectileID: integer,
  ignore: boolean
) ->  nil

[source]

Spring.SetProjectileGravity

---

function Spring.SetProjectileGravity(
  projectileID: integer,
  grav: number?
) ->  nil

@param grav - (Default: 0)

[source]

Spring.SetPieceProjectileParams

---

function Spring.SetPieceProjectileParams(
  projectileID: integer,
  explosionFlags: number?,
  spinAngle: number?,
  spinSpeed: number?,
  spinVectorX: number?,
  spinVectorY: number?,
  spinVectorZ: number?
) ->  nil

[source]

Spring.SetProjectileCEG

---

function Spring.SetProjectileCEG(
  projectileID: integer,
  ceg_name: string
) ->  nil

[source]

Spring.UnitFinishCommand

---

function Spring.UnitFinishCommand(unitID: integer)

[source]

Spring.GiveOrderToUnit

---

function Spring.GiveOrderToUnit(
  unitID: integer,
  cmdID: (CMD|integer),
  params: CreateCommandParams?,
  options: CreateCommandOptions?,
  timeout: integer?
) -> unitOrdered boolean

@param cmdID - The command ID.

@param params - Parameters for the given command.

@param timeout - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

[source]

Spring.GiveOrderToUnitMap

---

function Spring.GiveOrderToUnitMap(
  unitMap: table<integer,any>,
  cmdID: (CMD|integer),
  params: CreateCommandParams?,
  options: CreateCommandOptions?,
  timeout: integer?
) -> unitsOrdered integer

@param unitMap - A table with unit IDs as keys.

@param cmdID - The command ID.

@param params - Parameters for the given command.

@param timeout - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

@return unitsOrdered - The number of units ordered.

Give order to multiple units, specified by table keys.

[source]

Spring.GiveOrderToUnitArray

---

function Spring.GiveOrderToUnitArray(
  unitIDs: integer[],
  cmdID: (CMD|integer),
  params: CreateCommandParams?,
  options: CreateCommandOptions?,
  timeout: integer?
) -> unitsOrdered integer

@param unitIDs - An array of unit IDs.

@param cmdID - The command ID.

@param params - Parameters for the given command.

@param timeout - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

@return unitsOrdered - The number of units ordered.

[source]

Spring.GiveOrderArrayToUnit

---

function Spring.GiveOrderArrayToUnit(
  unitID: integer,
  commands: CreateCommand[]
) -> ordersGiven boolean

[source]

Spring.GiveOrderArrayToUnitMap

---

function Spring.GiveOrderArrayToUnitMap(
  unitMap: table<integer,any>,
  commands: CreateCommand[]
) -> unitsOrdered integer

@param unitMap - A table with unit IDs as keys.

@return unitsOrdered - The number of units ordered.

[source]

Spring.GiveOrderArrayToUnitArray

---

function Spring.GiveOrderArrayToUnitArray(
  unitIDs: integer[],
  commands: CreateCommand[],
  pairwise: boolean?
) -> unitsOrdered integer

@param unitIDs - Array of unit IDs.

@param pairwise - (Default: false) When false, assign all commands to each unit.

When true, assign commands according to index between units and cmds arrays.

If len(unitArray) < len(cmdArray) only the first len(unitArray) commands will be assigned, and vice-versa.

@return unitsOrdered - The number of units ordered.

[source]

Spring.LevelHeightMap

---

function Spring.LevelHeightMap(
  x: number,
  z: number,
  height: number
)

Set the height of a point in the world.

[source]

Spring.LevelHeightMap

---

function Spring.LevelHeightMap(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number?
) ->  nil

Set the height of a rectangle area in the world.

[source]

Spring.AdjustHeightMap

---

function Spring.AdjustHeightMap(
  x: number,
  z: number,
  height: number
)

Add height to a point in the world.

[source]

Spring.AdjustHeightMap

---

function Spring.AdjustHeightMap(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number?
) ->  nil

Add height to a rectangle in the world.

[source]

Spring.RevertHeightMap

---

function Spring.RevertHeightMap(
  x: number,
  z: number,
  height: number
)

Restore map height at a point in the world.

[source]

Spring.RevertHeightMap

---

function Spring.RevertHeightMap(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number?
) ->  nil

Restore map height of a rectangle area in the world.

[source]

Spring.AddHeightMap

---

function Spring.AddHeightMap(
  x: number,
  z: number,
  height: number
) -> newHeight integer?

Can only be called in Spring.SetHeightMapFunc

[source]

Spring.SetHeightMap

---

function Spring.SetHeightMap(
  x: number,
  z: number,
  height: number,
  terraform: number?
) -> absHeightDiff integer?

@param terraform - (Default: 1) Scaling factor.

@return absHeightDiff - If 0, nothing will be changed (the terraform starts), if 1 the terraform will be finished.

[source]

Can only be called in Spring.SetHeightMapFunc.

Spring.SetHeightMapFunc

---

function Spring.SetHeightMapFunc(
  luaFunction: function,
  arg: number,
  ...: number
) -> absTotalHeightMapAmountChanged integer?

[source]

Example code:

function Spring.SetHeightMapFunc(function()
  for z=0,Game.mapSizeZ, Game.squareSize do
    for x=0,Game.mapSizeX, Game.squareSize do
      Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
    end
  end
end)

Spring.LevelOriginalHeightMap

---

function Spring.LevelOriginalHeightMap(
  x: number,
  z: number,
  height: number
)

Set the height of a point in the original map height cache.

[source]

Spring.LevelOriginalHeightMap

---

function Spring.LevelOriginalHeightMap(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number
)

Set the height of a rectangle area in the original map height cache.

[source]

Spring.AdjustOriginalHeightMap

---

function Spring.AdjustOriginalHeightMap(
  x: number,
  z: number,
  height: number
)

Add height to a point in the original map height cache.

[source]

Spring.AdjustOriginalHeightMap

---

function Spring.AdjustOriginalHeightMap(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number
)

Add height to a rectangle area in the original map height cache.

[source]

Spring.RevertOriginalHeightMap

---

function Spring.RevertOriginalHeightMap(
  x: number,
  z: number,
  height: number
)

Restore original map height at a point in the world.

[source]

Spring.RevertOriginalHeightMap

---

function Spring.RevertOriginalHeightMap(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number?
) ->  nil

Restore original map height over a rectangle in the world.

[source]

Spring.AddOriginalHeightMap

---

function Spring.AddOriginalHeightMap(
  x: number,
  y: number,
  height: number
) ->  nil

[source]

Can only be called in Spring.SetOriginalHeightMapFunc

Spring.SetOriginalHeightMap

---

function Spring.SetOriginalHeightMap(
  x: number,
  y: number,
  height: number,
  factor: number?
) ->  nil

[source]

Can only be called in Spring.SetOriginalHeightMapFunc

Spring.SetOriginalHeightMapFunc

---

function Spring.SetOriginalHeightMapFunc(heightMapFunc: function) ->  nil

[source]

Cannot recurse on itself

Spring.RebuildSmoothMesh

---

function Spring.RebuildSmoothMesh() ->  nil

[source]

Heightmap changes normally take up to 25s to propagate to the smooth mesh. Use to force a mapwide update immediately.

Spring.LevelSmoothMesh

---

function Spring.LevelSmoothMesh(
  x: number,
  z: number,
  height: number
)

[source]

Spring.LevelSmoothMesh

---

function Spring.LevelSmoothMesh(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number
)

[source]

Spring.AdjustSmoothMesh

---

function Spring.AdjustSmoothMesh(
  x: number,
  z: number,
  height: number
)

[source]

Spring.AdjustSmoothMesh

---

function Spring.AdjustSmoothMesh(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  height: number
)

[source]

Spring.RevertSmoothMesh

---

function Spring.RevertSmoothMesh(
  x: number,
  z: number,
  origFactor: number
)

[source]

Spring.RevertSmoothMesh

---

function Spring.RevertSmoothMesh(
  x1: number,
  z1: number,
  x2: number,
  z2: number,
  origFactor: number
)

[source]

Spring.AddSmoothMesh

---

function Spring.AddSmoothMesh(
  x: number,
  z: number,
  height: number
) -> height number?

@return height - The new height, or nil if coordinates are invalid.

Can only be called in Spring.SetSmoothMeshFunc.

[source]

Spring.SetSmoothMesh

---

function Spring.SetSmoothMesh(
  x: number,
  z: number,
  height: number,
  terraform: number?
) -> The number?

@param terraform - (Default: 1)

@return The - absolute height difference, or nil if coordinates are invalid.

Can only be called in Spring.SetSmoothMeshFunc.

[source]

Spring.SetSmoothMeshFunc

---

function Spring.SetSmoothMeshFunc(
  luaFunction: function,
  arg: any,
  ...: any
) -> absTotalHeightMapAmountChanged number?

[source]

Spring.SetMapSquareTerrainType

---

function Spring.SetMapSquareTerrainType(
  x: number,
  z: number,
  newType: number
) -> oldType integer?

[source]

Spring.SetTerrainTypeData

---

function Spring.SetTerrainTypeData(
  typeIndex: number,
  speedTanks: number?,
  speedKBOts: number?,
  speedHovers: number?,
  speedShips: number?
) ->  boolean?

@param speedTanks - (Default: nil)

@param speedKBOts - (Default: nil)

@param speedHovers - (Default: nil)

@param speedShips - (Default: nil)

@return - true

[source]

Spring.SetSquareBuildingMask

---

function Spring.SetSquareBuildingMask(
  x: number,
  z: number,
  mask: number
) -> See nil

@return See - also buildingMask unitdef tag.

[source]

Spring.UnitWeaponFire

---

function Spring.UnitWeaponFire(
  unitID: integer,
  weaponID: integer
) ->  nil

[source]

Spring.UnitWeaponHoldFire

---

function Spring.UnitWeaponHoldFire(
  unitID: integer,
  weaponID: integer
) ->  nil

[source]

Spring.ForceUnitCollisionUpdate

---

function Spring.ForceUnitCollisionUpdate(unitID: integer) ->  nil

Prevent collision checks from working on outdated data

There’s a rare edge case that requires units to be in specific positions and being shot by specific weapons but which can result in shots ghosting through the unit. This is because the unit’s collision volume is stale. The movement.unitQuadPositionUpdateRate modrule controls this behaviour and can guarantee 100% correctness if set to 1, but the default value is 3 and large-scale games generally don’t want to set it so low. This function lets you guarantee success for important weapons regardless of how high the normal update rate is set.

[source]

Spring.UnitAttach

---

function Spring.UnitAttach(
  transporterID: integer,
  passengerID: integer,
  pieceNum: number
) ->  nil

[source]

Spring.UnitDetach

---

function Spring.UnitDetach(passengerID: integer) ->  nil

[source]

Spring.UnitDetachFromAir

---

function Spring.UnitDetachFromAir(passengerID: integer) ->  nil

[source]

Spring.SetUnitLoadingTransport

---

function Spring.SetUnitLoadingTransport(
  passengerID: integer,
  transportID: integer
) ->  nil

Disables collisions between the two units to allow colvol intersection during the approach.

[source]

Spring.SpawnProjectile

---

function Spring.SpawnProjectile(
  weaponDefID: integer,
  projectileParams: ProjectileParams
) -> projectileID integer?

[source]

Spring.DeleteProjectile

---

function Spring.DeleteProjectile(projectileID: integer) ->  nil

Silently removes projectiles (no explosion).

[source]

Spring.SpawnExplosion

---

function Spring.SpawnExplosion(
  posX: number?,
  posY: number?,
  posZ: number?,
  dirX: number?,
  dirY: number?,
  dirZ: number?,
  explosionParams: ExplosionParams
) ->  nil

@param posX - (Default: 0)

@param posY - (Default: 0)

@param posZ - (Default: 0)

@param dirX - (Default: 0)

@param dirY - (Default: 0)

@param dirZ - (Default: 0)

[source]

Spring.SpawnCEG

---

function Spring.SpawnCEG(
  cegname: string,
  posX: number?,
  posY: number?,
  posZ: number?,
  dirX: number?,
  dirY: number?,
  dirZ: number?,
  radius: number?,
  damage: number?
)
 -> success boolean?
 -> cegID integer

@param posX - (Default: 0)

@param posY - (Default: 0)

@param posZ - (Default: 0)

@param dirX - (Default: 0)

@param dirY - (Default: 0)

@param dirZ - (Default: 0)

@param radius - (Default: 0)

@param damage - (Default: 0)

[source]

Spring.SpawnSFX

---

function Spring.SpawnSFX(
  unitID: integer?,
  sfxID: integer?,
  posX: number?,
  posY: number?,
  posZ: number?,
  dirX: number?,
  dirY: number?,
  dirZ: number?,
  radius: number?,
  damage: number?,
  absolute: boolean?
) -> success boolean?

@param unitID - (Default: 0)

@param sfxID - (Default: 0)

@param posX - (Default: 0)

@param posY - (Default: 0)

@param posZ - (Default: 0)

@param dirX - (Default: 0)

@param dirY - (Default: 0)

@param dirZ - (Default: 0)

@param radius - (Default: 0)

@param damage - (Default: 0)

Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

[source]

Spring.SetNoPause

---

function Spring.SetNoPause(noPause: boolean) ->  nil

[source]

Spring.SetExperienceGrade

---

function Spring.SetExperienceGrade(
  expGrade: number,
  ExpPowerScale: number?,
  ExpHealthScale: number?,
  ExpReloadScale: number?
) ->  nil

Defines how often Callins.UnitExperience will be called.

[source]

Spring.SetRadarErrorParams

---

function Spring.SetRadarErrorParams(
  allyTeamID: integer,
  allyteamErrorSize: number,
  baseErrorSize: number?,
  baseErrorMult: number?
) ->  nil

[source]

Spring.EditUnitCmdDesc

---

function Spring.EditUnitCmdDesc(
  unitID: integer,
  cmdDescID: integer,
  cmdArray: CommandDescription
)

[source]

Spring.InsertUnitCmdDesc

---

function Spring.InsertUnitCmdDesc(
  unitID: integer,
  index: integer,
  cmdDesc: CommandDescription
)

Insert a command description at a specific index.

[source]

Spring.InsertUnitCmdDesc

---

function Spring.InsertUnitCmdDesc(
  unitID: integer,
  cmdDesc: CommandDescription
)

Insert a command description at the last position.

[source]

Spring.RemoveUnitCmdDesc

---

function Spring.RemoveUnitCmdDesc(
  unitID: integer,
  cmdDescID: integer?
)

[source]

Spring.Ping

---

function Spring.Ping(pingTag: number) ->  nil

Send a ping request to the server

[source]

Spring.SendCommands

---

function Spring.SendCommands(commands: string[])

[source]

Spring.SendCommands

---

function Spring.SendCommands(
  command: string,
  ...: string
) ->  nil

@param ... - additional commands

[source]

Spring.SendPublicChat

---

function Spring.SendPublicChat(message: string) ->  nil

Sends a chat message to everyone (players and spectators).

[source]

Spring.SendAllyChat

---

function Spring.SendAllyChat(message: string) ->  nil

Sends a chat message to the sender’s ally team (if a spectator, to other spectators).

[source]

Spring.SendSpectatorChat

---

function Spring.SendSpectatorChat(message: string) ->  nil

Sends a chat message to spectators. Works even if you’re a player.

[source]

Spring.SendPrivateChat

---

function Spring.SendPrivateChat(
  message: string,
  playerID: integer
) ->  nil

Sends a private chat message to a specific player ID.

[source]

Spring.SendMessage

---

function Spring.SendMessage(message: string) ->  nil

[source]

Spring.SendMessageToSpectators

---

function Spring.SendMessageToSpectators(message: string) ->  nil

@param message - "`<PLAYER#>`" where # is a player ID.

This will be replaced with the player’s name. e.g.

Spring.SendMessage("`<PLAYER1>` did something") -- "ProRusher did something"

[source]

Spring.SendMessageToPlayer

---

function Spring.SendMessageToPlayer(
  playerID: integer,
  message: string
) ->  nil

[source]

Spring.SendMessageToTeam

---

function Spring.SendMessageToTeam(
  teamID: integer,
  message: string
) ->  nil

[source]

Spring.SendMessageToAllyTeam

---

function Spring.SendMessageToAllyTeam(
  allyID: integer,
  message: string
) ->  nil

[source]

Spring.LoadSoundDef

---

function Spring.LoadSoundDef(soundfile: string) -> success boolean

Loads a SoundDefs file, the format is the same as in gamedata/sounds.lua.

[source]

Spring.PlaySoundFile

---

function Spring.PlaySoundFile(
  soundfile: string,
  volume: number?,
  posx: number?,
  posy: number?,
  posz: number?,
  speedx: number?,
  speedy: number?,
  speedz: number?,
  channel: SoundChannel?
) -> playSound boolean

@param volume - (Default: 1.0)

@param channel - (Default: 0|"general")

[source]

Spring.PlaySoundStream

---

function Spring.PlaySoundStream(
  oggfile: string,
  volume: number?,
  enqueue: boolean?
) -> success boolean

@param volume - (Default: 1.0)

Allows to play an Ogg Vorbis (.OGG) and mp3 compressed sound file.

[source]

Multiple sound streams may be played at once.

Spring.StopSoundStream

---

function Spring.StopSoundStream() ->  nil

Terminates any SoundStream currently running.

[source]

Spring.PauseSoundStream

---

function Spring.PauseSoundStream() ->  nil

Pause any SoundStream currently running.

[source]

Spring.SetSoundStreamVolume

---

function Spring.SetSoundStreamVolume(volume: number) ->  nil

Set volume for SoundStream

[source]

Spring.SetSoundEffectParams

---

function Spring.SetSoundEffectParams()

[source]

Spring.AddWorldIcon

---

function Spring.AddWorldIcon(
  cmdID: integer,
  posX: number,
  posY: number,
  posZ: number
) ->  nil

[source]

Spring.AddWorldText

---

function Spring.AddWorldText(
  text: string,
  posX: number,
  posY: number,
  posZ: number
) ->  nil

[source]

Spring.AddWorldUnit

---

function Spring.AddWorldUnit(
  unitDefID: integer,
  posX: number,
  posY: number,
  posZ: number,
  teamID: integer,
  facing: FacingInteger
) ->  nil

[source]

Spring.DrawUnitCommands

---

function Spring.DrawUnitCommands(unitID: integer)

[source]

Spring.DrawUnitCommands

---

function Spring.DrawUnitCommands(
  unitIDs: integer[],
  tableOrArray: false?
)

@param unitIDs - Unit ids.

@param tableOrArray - Set to true if the unit IDs should be read from the keys of unitIDs.

[source]

Spring.DrawUnitCommands

---

function Spring.DrawUnitCommands(
  unitIDs: table<integer,any>,
  tableOrArray: true
) ->  nil

@param unitIDs - Table with unit IDs as keys.

@param tableOrArray - Set to false if the unit IDs should be read from the values of unitIDs.

[source]

Spring.SetCameraTarget

---

function Spring.SetCameraTarget(
  x: number,
  y: number,
  z: number,
  transTime: number?
) ->  nil

For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

[source]

Spring.SetCameraOffset

---

function Spring.SetCameraOffset(
  posX: number?,
  posY: number?,
  posZ: number?,
  tiltX: number?,
  tiltY: number?,
  tiltZ: number?
) ->  nil

@param posX - (Default: 0)

@param posY - (Default: 0)

@param posZ - (Default: 0)

@param tiltX - (Default: 0)

@param tiltY - (Default: 0)

@param tiltZ - (Default: 0)

[source]

Spring.SetCameraState

---

function Spring.SetCameraState(
  cameraState: CameraState,
  transitionTime: number?,
  transitionTimeFactor: number?,
  transitionTimeExponent: number?
) -> set boolean

@param cameraState - The fields must be consistent with the name/mode and current/new camera mode.

@param transitionTime - (Default: 0) in nanoseconds

@param transitionTimeFactor - Multiplicative factor applied to this and all subsequent transition times for this camera mode.

Defaults to “CamTimeFactor” springsetting unless set previously.

@param transitionTimeExponent - Tween factor applied to this and all subsequent transitions for this camera mode.

Defaults to “CamTimeExponent” springsetting unless set previously.

@return set - true when applied without errors, otherwise false.

Set camera state.

[source]

Spring.RunDollyCamera

---

function Spring.RunDollyCamera(runtime: number) ->  nil

@param runtime - Runtime in milliseconds.

Runs Dolly Camera

[source]

Spring.PauseDollyCamera

---

function Spring.PauseDollyCamera(fraction: number) ->  nil

@param fraction - Fraction of the total runtime to pause at, 0 to 1 inclusive. A null value pauses at current percent

Pause Dolly Camera

[source]

Spring.ResumeDollyCamera

---

function Spring.ResumeDollyCamera() ->  nil

Resume Dolly Camera

[source]

Spring.SetDollyCameraPosition

---

function Spring.SetDollyCameraPosition(
  x: number,
  y: number,
  z: number
) ->  nil

Sets Dolly Camera Position

[source]

Spring.SetDollyCameraCurve

---

function Spring.SetDollyCameraCurve(
  degree: number,
  cpoints: ControlPoint[],
  knots: table
) ->  nil

@param cpoints - NURBS control point positions.

Sets Dolly Camera movement Curve

[source]

Spring.SetDollyCameraMode

---

function Spring.SetDollyCameraMode(mode: (1|2)) ->  nil

@param mode - 1 static position, 2 nurbs curve

Sets Dolly Camera movement mode

[source]

Spring.SetDollyCameraRelativeMode

---

function Spring.SetDollyCameraRelativeMode(relativeMode: number) ->  nil

@param relativeMode - 1 world, 2 look target

Sets Dolly Camera movement curve to world relative or look target relative

[source]

Spring.SetDollyCameraLookCurve

---

function Spring.SetDollyCameraLookCurve(
  degree: number,
  cpoints: ControlPoint[],
  knots: table
) ->  nil

@param cpoints - NURBS control point positions.

Sets Dolly Camera Look Curve

[source]

Spring.SetDollyCameraLookPosition

---

function Spring.SetDollyCameraLookPosition(
  x: number,
  y: number,
  z: number
) ->  nil

Sets Dolly Camera Look Position

[source]

Spring.SetDollyCameraLookUnit

---

function Spring.SetDollyCameraLookUnit(unitID: integer) ->  nil

@param unitID - The unit to look at.

Sets target unit for Dolly Camera to look towards

[source]

Spring.SelectUnit

---

function Spring.SelectUnit(
  unitID: integer?,
  append: boolean?
) ->  nil

@param append - (Default: false) Append to current selection.

Selects a single unit

[source]

Spring.DeselectUnit

---

function Spring.DeselectUnit(unitID: integer) ->  nil

[source]

Spring.DeselectUnitArray

---

function Spring.DeselectUnitArray(unitIDs: integer[]) ->  nil

@param unitIDs - Table with unit IDs as values.

Deselects multiple units.

[source]

Spring.DeselectUnitMap

---

function Spring.DeselectUnitMap(unitMap: table<integer,any>) ->  nil

@param unitMap - Table with unit IDs as keys.

Deselects multiple units.

[source]

Spring.SelectUnitArray

---

function Spring.SelectUnitArray(
  unitIDs: integer[],
  append: boolean?
) ->  nil

@param unitIDs - Table with unit IDs as values.

@param append - (Default: false) append to current selection

Selects multiple units, or appends to selection. Accepts a table with unitIDs as values

[source]

Spring.SelectUnitMap

---

function Spring.SelectUnitMap(
  unitMap: table<integer,any>,
  append: boolean?
) ->  nil

@param unitMap - Table with unit IDs as keys.

@param append - (Default: false) append to current selection

Selects multiple units, or appends to selection. Accepts a table with unitIDs as keys

[source]

Spring.AddMapLight

---

function Spring.AddMapLight(lightParams: LightParams) -> lightHandle integer

[source]

requires MaxDynamicMapLights > 0

Spring.AddModelLight

---

function Spring.AddModelLight(lightParams: LightParams) -> lightHandle number

[source]

requires MaxDynamicMapLights > 0

Spring.UpdateMapLight

---

function Spring.UpdateMapLight(
  lightHandle: number,
  lightParams: LightParams
) -> success boolean

[source]

Spring.UpdateModelLight

---

function Spring.UpdateModelLight(
  lightHandle: number,
  lightParams: LightParams
) -> success boolean

[source]

Spring.AddLightTrackingTarget

---

function Spring.AddLightTrackingTarget()

[source]

Spring.SetMapLightTrackingState

---

function Spring.SetMapLightTrackingState(
  lightHandle: number,
  unitOrProjectileID: integer,
  enableTracking: boolean,
  unitOrProjectile: boolean
) -> success boolean

Set a map-illuminating light to start/stop tracking the position of a moving object (unit or projectile)

[source]

Spring.SetModelLightTrackingState

---

function Spring.SetModelLightTrackingState(
  lightHandle: number,
  unitOrProjectileID: integer,
  enableTracking: boolean,
  unitOrProjectile: boolean
) -> success boolean

Set a model-illuminating light to start/stop tracking the position of a moving object (unit or projectile)

[source]

Spring.SetMapShader

---

function Spring.SetMapShader(
  standardShaderID: integer,
  deferredShaderID: integer
) ->  nil

[source]

The ID’s must refer to valid programs returned by gl.CreateShader. Passing in a value of 0 will cause the respective shader to revert back to its engine default. Custom map shaders that declare a uniform ivec2 named “texSquare” can sample from the default diffuse texture(s), which are always bound to TU 0.

Spring.SetMapSquareTexture

---

function Spring.SetMapSquareTexture(
  texSqrX: number,
  texSqrY: number,
  luaTexName: string
) -> success boolean

[source]

Spring.SetMapShadingTexture

---

function Spring.SetMapShadingTexture(
  texType: string,
  texName: string
) -> success boolean

[source]

@usage Spring.SetMapShadingTexture(“$ssmf_specular”, “name_of_my_shiny_texture”)

Spring.SetSkyBoxTexture

---

function Spring.SetSkyBoxTexture(texName: string) ->  nil

[source]

Spring.SetUnitNoDraw

---

function Spring.SetUnitNoDraw(
  unitID: integer,
  noDraw: boolean
) ->  nil

[source]

Spring.SetUnitEngineDrawMask

---

function Spring.SetUnitEngineDrawMask(
  unitID: integer,
  drawMask: number
) ->  nil

[source]

Spring.SetUnitAlwaysUpdateMatrix

---

function Spring.SetUnitAlwaysUpdateMatrix(
  unitID: integer,
  alwaysUpdateMatrix: boolean
) ->  nil

[source]

Spring.SetUnitNoMinimap

---

function Spring.SetUnitNoMinimap(
  unitID: integer,
  unitNoMinimap: boolean
) ->  nil

[source]

Spring.SetMiniMapRotation

---

function Spring.SetMiniMapRotation(rotation: number) ->  nil

@param rotation - amount in radians

[source]

Spring.SetUnitNoGroup

---

function Spring.SetUnitNoGroup(
  unitID: integer,
  unitNoGroup: boolean
)

@param unitNoGroup - Whether unit can be added to selection groups

[source]

Spring.SetUnitNoSelect

---

function Spring.SetUnitNoSelect(
  unitID: integer,
  unitNoSelect: boolean
) ->  nil

@param unitNoSelect - whether unit can be selected or not

[source]

Spring.SetUnitLeaveTracks

---

function Spring.SetUnitLeaveTracks(
  unitID: integer,
  unitLeaveTracks: boolean
) ->  nil

@param unitLeaveTracks - whether unit leaves tracks on movement

[source]

Spring.SetUnitSelectionVolumeData

---

function Spring.SetUnitSelectionVolumeData(
  unitID: integer,
  featureID: integer,
  scaleX: number,
  scaleY: number,
  scaleZ: number,
  offsetX: number,
  offsetY: number,
  offsetZ: number,
  vType: number,
  tType: number,
  Axis: number
) ->  nil

[source]

Spring.SetFeatureNoDraw

---

function Spring.SetFeatureNoDraw(
  featureID: integer,
  noDraw: boolean
) ->  nil

[source]

Spring.SetFeatureEngineDrawMask

---

function Spring.SetFeatureEngineDrawMask(
  featureID: integer,
  engineDrawMask: number
) ->  nil

[source]

Spring.SetFeatureAlwaysUpdateMatrix

---

function Spring.SetFeatureAlwaysUpdateMatrix(
  featureID: integer,
  alwaysUpdateMat: number
) ->  nil

[source]

Spring.SetFeatureFade

---

function Spring.SetFeatureFade(
  featureID: integer,
  allow: boolean
) ->  nil

Control whether a feature will fade or not when zoomed out.

[source]

Spring.SetFeatureSelectionVolumeData

---

function Spring.SetFeatureSelectionVolumeData(
  featureID: integer,
  scaleX: number,
  scaleY: number,
  scaleZ: number,
  offsetX: number,
  offsetY: number,
  offsetZ: number,
  vType: number,
  tType: number,
  Axis: number
) ->  nil

[source]

Spring.AddUnitIcon

---

function Spring.AddUnitIcon(
  iconName: string,
  texFile: string,
  size: number?,
  dist: number?,
  radAdjust: number?
) -> added boolean

[source]

Spring.FreeUnitIcon

---

function Spring.FreeUnitIcon(iconName: string) -> freed boolean?

[source]

Spring.UnitIconSetDraw

---

function Spring.UnitIconSetDraw(
  unitID: integer,
  drawIcon: boolean
) ->  nil

[source]

Use Spring.SetUnitIconDraw instead.

Spring.SetUnitIconDraw

---

function Spring.SetUnitIconDraw(
  unitID: integer,
  drawIcon: boolean
) ->  nil

[source]

Spring.SetUnitDefIcon

---

function Spring.SetUnitDefIcon(
  unitDefID: integer,
  iconName: string
) ->  nil

[source]

Spring.SetUnitDefImage

---

function Spring.SetUnitDefImage(
  unitDefID: integer,
  image: string
) ->  nil

@param image - luaTexture|texFile

[source]

Spring.ExtractModArchiveFile

---

function Spring.ExtractModArchiveFile(modfile: string) -> extracted boolean

[source]

Spring.CreateDir

---

function Spring.CreateDir(path: string) -> dirCreated boolean?

[source]

Spring.SetActiveCommand

---

function Spring.SetActiveCommand(
  action: string,
  actionExtra: string?
) -> commandSet boolean?

[source]

Spring.SetActiveCommand

---

function Spring.SetActiveCommand(
  cmdIndex: number,
  button: number?,
  leftClick: boolean?,
  rightClick: boolean?,
  alt: boolean?,
  ctrl: boolean?,
  meta: boolean?,
  shift: boolean?
) -> commandSet boolean?

@param button - (Default: 1)

[source]

Spring.LoadCmdColorsConfig

---

function Spring.LoadCmdColorsConfig(config: string) ->  nil

[source]

Spring.LoadCtrlPanelConfig

---

function Spring.LoadCtrlPanelConfig(config: string) ->  nil

[source]

Spring.ForceLayoutUpdate

---

function Spring.ForceLayoutUpdate() ->  nil

[source]

Spring.SetDrawSelectionInfo

---

function Spring.SetDrawSelectionInfo(enable: boolean) ->  nil

Disables the “Selected Units x” box in the GUI.

[source]

Spring.SetBoxSelectionByEngine

---

function Spring.SetBoxSelectionByEngine(state: boolean) ->  nil

[source]

Spring.SetTeamColor

---

function Spring.SetTeamColor(
  teamID: integer,
  r: number,
  g: number,
  b: number
) ->  nil

[source]

Spring.AssignMouseCursor

---

function Spring.AssignMouseCursor(
  cmdName: string,
  iconFileName: string,
  overwrite: boolean?,
  hotSpotTopLeft: boolean?
) -> assigned boolean?

@param iconFileName - not the full filename, instead it is like this: Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack

@param overwrite - (Default: true)

@param hotSpotTopLeft - (Default: false)

Changes/creates the cursor of a single CursorCmd.

[source]

Spring.ReplaceMouseCursor

---

function Spring.ReplaceMouseCursor(
  oldFileName: string,
  newFileName: string,
  hotSpotTopLeft: boolean?
) -> assigned boolean?

@param hotSpotTopLeft - (Default: false)

Mass replace all occurrences of the cursor in all CursorCmds.

[source]

Spring.SetCustomCommandDrawData

---

function Spring.SetCustomCommandDrawData(
  cmdID: integer,
  cmdReference: (string|integer)?,
  color: rgba?,
  showArea: boolean?
) ->  nil

@param cmdReference - The name or ID of an icon for command. Pass nil to clear draw data for command.

@param color - (Default: white)

@param showArea - (Default: false)

Register your custom cmd so it gets visible in the unit’s cmd queue

[source]

Spring.WarpMouse

---

function Spring.WarpMouse(
  x: number,
  y: number
) ->  nil

[source]

Spring.SetMouseCursor

---

function Spring.SetMouseCursor(
  cursorName: string,
  cursorScale: number?
) ->  nil

@param cursorScale - (Default: 1.0)

[source]

Spring.SetLosViewColors

---

function Spring.SetLosViewColors(
  always: rgb,
  LOS: rgb,
  radar: rgb,
  jam: rgb,
  radar2: rgb
) ->  nil

[source]

Spring.SetNanoProjectileParams

---

function Spring.SetNanoProjectileParams(
  rotVal: number?,
  rotVel: number?,
  rotAcc: number?,
  rotValRng: number?,
  rotVelRng: number?,
  rotAccRng: number?
) ->  nil

@param rotVal - (Default: 0) in degrees

@param rotVel - (Default: 0) in degrees

@param rotAcc - (Default: 0) in degrees

@param rotValRng - (Default: 0) in degrees

@param rotVelRng - (Default: 0) in degrees

@param rotAccRng - (Default: 0) in degrees

[source]

Spring.SetConfigInt

---

function Spring.SetConfigInt(
  name: string,
  value: integer,
  useOverlay: boolean?
) ->  nil

@param useOverlay - (Default: false) If true, the value will only be set in memory, and not be restored for the next game.

[source]

Spring.SetConfigFloat

---

function Spring.SetConfigFloat(
  name: string,
  value: number,
  useOverla: boolean?
) ->  nil

@param useOverla - (Default: false) If true, the value will only be set in memory, and not be restored for the next game.y

[source]

Spring.SetConfigString

---

function Spring.SetConfigString(
  name: string,
  value: string,
  useOverlay: boolean?
) ->  nil

@param useOverlay - (Default: false) If true, the value will only be set in memory, and not be restored for the next game.

[source]

Spring.Quit

---

function Spring.Quit() ->  nil

Closes the application

[source]

Spring.SetUnitGroup

---

function Spring.SetUnitGroup(
  unitID: integer,
  groupID: integer
) ->  nil

@param groupID - the group number to be assigned, or -1 for deassignment

[source]

Spring.GiveOrder

---

function Spring.GiveOrder(
  cmdID: (CMD|integer),
  params: CreateCommandParams,
  options: CreateCommandOptions?,
  timeout: integer?
) ->  boolean

@param cmdID - The command ID.

@param params - Parameters for the given command.

@param timeout - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Give order to selected units.

[source]

Spring.GiveOrderToUnit

---

function Spring.GiveOrderToUnit(
  unitID: integer,
  cmdID: (CMD|integer),
  params: CreateCommandParams?,
  options: CreateCommandOptions?,
  timeout: integer?
) ->  boolean

@param cmdID - The command ID.

@param params - Parameters for the given command.

@param timeout - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Give order to specific unit.

[source]

Spring.GiveOrderToUnitMap

---

function Spring.GiveOrderToUnitMap(
  unitMap: table<integer,any>,
  cmdID: (CMD|integer),
  params: CreateCommandParams?,
  options: CreateCommandOptions?,
  timeout: integer?
) -> orderGiven boolean

@param unitMap - A table with unit IDs as keys.

@param cmdID - The command ID.

@param params - Parameters for the given command.

@param timeout - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

Give order to multiple units, specified by table keys.

[source]

Spring.GiveOrderToUnitArray

---

function Spring.GiveOrderToUnitArray(
  unitIDs: integer[],
  cmdID: (CMD|integer),
  params: CreateCommandParams?,
  options: CreateCommandOptions?,
  timeout: integer?
) -> ordersGiven boolean

@param unitIDs - Array of unit IDs.

@param cmdID - The command ID.

@param params - Parameters for the given command.

@param timeout - Absolute frame number. The command will be discarded after this frame. Only respected by mobile units.

@return ordersGiven - true if any orders were sent, otherwise false.

Give order to an array of units.

[source]

Spring.GiveOrderArrayToUnit

---

function Spring.GiveOrderArrayToUnit(
  unitID: integer,
  commands: CreateCommand[]
) -> ordersGiven boolean

@param unitID - Unit ID.

@return ordersGiven - true if any orders were sent, otherwise false.

[source]

Spring.GiveOrderArrayToUnitMap

---

function Spring.GiveOrderArrayToUnitMap(
  unitMap: table<integer,any>,
  commands: CreateCommand[]
) -> ordersGiven boolean

@param unitMap - A table with unit IDs as keys.

@return ordersGiven - true if any orders were sent, otherwise false.

[source]

Spring.GiveOrderArrayToUnitArray

---

function Spring.GiveOrderArrayToUnitArray(
  unitIDs: integer[],
  commands: CreateCommand[],
  pairwise: boolean?
) -> ordersGiven boolean

@param unitIDs - Array of unit IDs.

@param pairwise - (Default: false) When false, assign all commands to each unit.

When true, assign commands according to index between units and cmds arrays.

If len(unitArray) < len(cmdArray) only the first len(unitArray) commands will be assigned, and vice-versa.

@return ordersGiven - true if any orders were sent, otherwise false.

[source]

Spring.SetBuildSpacing

---

function Spring.SetBuildSpacing(spacing: number) ->  nil

[source]

Spring.SetBuildFacing

---

function Spring.SetBuildFacing(facing: FacingInteger) ->  nil

[source]

Spring.SendLuaUIMsg

---

function Spring.SendLuaUIMsg(
  message: string,
  mode: string
) ->  nil

@param mode - “s”/”specs” | “a”/”allies”

[source]

Spring.SendLuaGaiaMsg

---

function Spring.SendLuaGaiaMsg(message: string) ->  nil

[source]

Spring.SendLuaRulesMsg

---

function Spring.SendLuaRulesMsg(message: string) ->  nil

[source]

Spring.SendLuaMenuMsg

---

function Spring.SendLuaMenuMsg(msg: string)

[source]

Spring.SetShareLevel

---

function Spring.SetShareLevel(
  resource: string,
  shareLevel: number
) ->  nil

@param resource - metal | energy

[source]

Spring.ShareResources

---

function Spring.ShareResources(
  teamID: integer,
  units: string
) ->  nil

[source]

Spring.ShareResources

---

function Spring.ShareResources(
  teamID: integer,
  resource: string,
  amount: number
) ->  nil

@param resource - metal | energy

[source]

Spring.SetLastMessagePosition

---

function Spring.SetLastMessagePosition(
  x: number,
  y: number,
  z: number
) ->  nil

[source]

Spring.MarkerAddPoint

---

function Spring.MarkerAddPoint(
  x: number,
  y: number,
  z: number,
  text: string?,
  localOnly: boolean?
) ->  nil

@param text - (Default: "")

[source]

Spring.MarkerAddLine

---

function Spring.MarkerAddLine(
  x1: number,
  y1: number,
  z1: number,
  x2: number,
  y2: number,
  z2: number,
  localOnly: boolean?,
  playerId: number?
) ->  nil

@param localOnly - (Default: false)

[source]

Spring.MarkerErasePosition

---

function Spring.MarkerErasePosition(
  x: number,
  y: number,
  z: number,
  unused: nil,
  localOnly: boolean?,
  playerId: number?,
  alwaysErase: boolean?
) ->  nil

@param unused - This argument is ignored.

@param localOnly - (Default: false) do not issue a network message, erase only for the current player

@param playerId - when not specified it uses the issuer playerId

@param alwaysErase - (Default: false) erase any marker when localOnly and current player is spectating. Allows spectators to erase players markers locally

[source]

Issue an erase command for markers on the map.

Spring.SetAtmosphere

---

function Spring.SetAtmosphere(params: AtmosphereParams)

It can be used to modify the following atmosphere parameters

Usage:

Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})

[source]

Spring.SetSunDirection

---

function Spring.SetSunDirection(
  dirX: number,
  dirY: number,
  dirZ: number,
  intensity: number?
) ->  nil

@param intensity - (Default: 1.0)

[source]

Spring.SetSunLighting

---

function Spring.SetSunLighting(params: { groundAmbientColor: rgb, groundDiffuseColor: rgb })

Modify sun lighting parameters.

Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })

[source]

Spring.SetMapRenderingParams

---

function Spring.SetMapRenderingParams(params: MapRenderingParams) ->  nil

Allows to change map rendering params at runtime.

[source]

Spring.ForceTesselationUpdate

---

function Spring.ForceTesselationUpdate(
  normal: boolean?,
  shadow: boolean?
) -> updated boolean

@param normal - (Default: true)

@param shadow - (Default: false)

[source]

Spring.SendSkirmishAIMessage

---

function Spring.SendSkirmishAIMessage(
  aiTeam: number,
  message: string
) -> ai_processed boolean?

[source]

Spring.SetLogSectionFilterLevel

---

function Spring.SetLogSectionFilterLevel(
  sectionName: string,
  logLevel: (string|number)?
) ->  nil

[source]

Spring.GarbageCollectCtrl

---

function Spring.GarbageCollectCtrl(
  itersPerBatch: integer?,
  numStepsPerIter: integer?,
  minStepsPerIter: integer?,
  maxStepsPerIter: integer?,
  minLoopRunTime: number?,
  maxLoopRunTime: number?,
  baseRunTimeMult: number?,
  baseMemLoadMult: number?
) ->  nil

[source]

Spring.SetAutoShowMetal

---

function Spring.SetAutoShowMetal(autoShow: boolean) ->  nil

[source]

Spring.SetDrawSky

---

function Spring.SetDrawSky(drawSky: boolean) ->  nil

[source]

Spring.SetDrawWater

---

function Spring.SetDrawWater(drawWater: boolean) ->  nil

[source]

Spring.SetDrawGround

---

function Spring.SetDrawGround(drawGround: boolean) ->  nil

[source]

Spring.SetDrawGroundDeferred

---

function Spring.SetDrawGroundDeferred(
  drawGroundDeferred: boolean,
  drawGroundForward: boolean?
) ->  nil

@param drawGroundForward - allows disabling of the forward pass

[source]

Spring.SetDrawModelsDeferred

---

function Spring.SetDrawModelsDeferred(
  drawUnitsDeferred: boolean,
  drawFeaturesDeferred: boolean,
  drawUnitsForward: boolean?,
  drawFeaturesForward: boolean?
) ->  nil

@param drawUnitsForward - allows disabling of the respective forward passes

@param drawFeaturesForward - allows disabling of the respective forward passes

[source]

Spring.SetVideoCapturingMode

---

function Spring.SetVideoCapturingMode(allowCaptureMode: boolean) ->  nil

This doesn’t actually record the game in any way, it just regulates the framerate and interpolations.

[source]

Spring.SetVideoCapturingTimeOffset

---

function Spring.SetVideoCapturingTimeOffset(timeOffset: boolean) ->  nil

[source]

Spring.SetWaterParams

---

function Spring.SetWaterParams(waterParams: WaterParams) ->  nil

Does not need cheating enabled.

Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your springrc to 1, then you don’t even need to restart BumpWater via /water 4.

[source]

Spring.PreloadUnitDefModel

---

function Spring.PreloadUnitDefModel(unitDefID: integer) ->  nil

[source]

Allow the engine to load the unit’s model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.

Spring.PreloadFeatureDefModel

---

function Spring.PreloadFeatureDefModel(featureDefID: integer) ->  nil

[source]

Spring.PreloadSoundItem

---

function Spring.PreloadSoundItem(name: string) ->  nil

[source]

Spring.LoadModelTextures

---

function Spring.LoadModelTextures(modelName: string) -> success boolean?

[source]

Spring.CreateGroundDecal

---

function Spring.CreateGroundDecal() -> decalID number?

[source]

Spring.DestroyGroundDecal

---

function Spring.DestroyGroundDecal(decalID: integer) -> delSuccess boolean

[source]

Spring.SetGroundDecalPosAndDims

---

function Spring.SetGroundDecalPosAndDims(
  decalID: integer,
  midPosX: number?,
  midPosZ: number?,
  sizeX: number?,
  sizeZ: number?,
  projCubeHeight: number?
) -> decalSet boolean

@param midPosX - (Default: currMidPosX)

@param midPosZ - (Default: currMidPosZ)

@param sizeX - (Default: currSizeX)

@param sizeZ - (Default: currSizeZ)

@param projCubeHeight - (Default: calculateProjCubeHeight)

[source]

Spring.SetGroundDecalQuadPosAndHeight

---

function Spring.SetGroundDecalQuadPosAndHeight(
  decalID: integer,
  posTL: xz?,
  posTR: xz?,
  posBR: xz?,
  posBL: xz?,
  projCubeHeight: number?
) -> decalSet boolean

@param posTL - (Default: currPosTL)

@param posTR - (Default: currPosTR)

@param posBR - (Default: currPosBR)

@param posBL - (Default: currPosBL)

@param projCubeHeight - (Default: calculateProjCubeHeight)

[source]

Use for non-rectangular decals

Spring.SetGroundDecalRotation

---

function Spring.SetGroundDecalRotation(
  decalID: integer,
  rot: number?
) -> decalSet boolean

@param rot - (Default: random) in radians

[source]

Spring.SetGroundDecalTexture

---

function Spring.SetGroundDecalTexture(
  decalID: integer,
  textureName: string,
  isMainTex: boolean?
) -> decalSet boolean?

@param textureName - The texture has to be on the atlas which seems to mean it’s defined as an explosion, unit tracks, or building plate decal on some unit already (no arbitrary textures)

@param isMainTex - (Default: true) If false, it sets the normals/glow map

[source]

Spring.SetGroundDecalTextureParams

---

function Spring.SetGroundDecalTextureParams(
  decalID: integer,
  texWrapDistance: number?,
  texTraveledDistance: number?
) -> decalSet boolean?

@param texWrapDistance - (Default: currTexWrapDistance) if non-zero sets the mode to repeat the texture along the left-right direction of the decal every texWrapFactor elmos

@param texTraveledDistance - (Default: currTexTraveledDistance) 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.

[source]

Spring.SetGroundDecalAlpha

---

function Spring.SetGroundDecalAlpha(
  decalID: integer,
  alpha: number?,
  alphaFalloff: number?
) -> decalSet boolean

@param alpha - (Default: currAlpha) Between 0 and 1

@param alphaFalloff - (Default: currAlphaFalloff) Between 0 and 1, per second

[source]

Spring.SetGroundDecalNormal

---

function Spring.SetGroundDecalNormal(
  decalID: integer,
  normalX: number?,
  normalY: number?,
  normalZ: number?
) -> decalSet boolean

@param normalX - (Default: 0)

@param normalY - (Default: 0)

@param normalZ - (Default: 0)

[source]

Sets projection cube normal to orient in 3D space. In case the normal (0,0,0) then normal is picked from the terrain

Spring.SetGroundDecalTint

---

function Spring.SetGroundDecalTint(
  decalID: integer,
  tintColR: number?,
  tintColG: number?,
  tintColB: number?,
  tintColA: number?
) -> decalSet boolean

@param tintColR - (Default: curTintColR)

@param tintColG - (Default: curTintColG)

@param tintColB - (Default: curTintColB)

@param tintColA - (Default: curTintColA)

[source]

Sets the tint of the ground decal. Color = 2 * textureColor * tintColor Respectively a color of (0.5, 0.5, 0.5, 0.5) is effectively no tint

Spring.SetGroundDecalMisc

---

function Spring.SetGroundDecalMisc(
  decalID: integer,
  dotElimExp: number?,
  refHeight: number?,
  minHeight: number?,
  maxHeight: number?,
  forceHeightMode: number?
) -> decalSet boolean

@param dotElimExp - (Default: curValue) pow(max(dot(decalProjVector, SurfaceNormal), 0.0), dotElimExp), used to reduce decal artifacts on surfaces non-collinear with the projection vector

@param refHeight - (Default: curValue)

@param minHeight - (Default: curValue)

@param maxHeight - (Default: curValue)

@param forceHeightMode - (Default: curValue) in case forceHeightMode==1.0 ==> force relative height: midPoint.y = refHeight + clamp(midPoint.y - refHeight, minHeight); forceHeightMode==2.0 ==> force absolute height: midPoint.y = midPoint.y, clamp(midPoint.y, minHeight, maxHeight); other forceHeightMode values do not enforce the height of the center position

[source]

Sets varios secondary parameters of a decal

Spring.SetGroundDecalCreationFrame

---

function Spring.SetGroundDecalCreationFrame(
  decalID: integer,
  creationFrameMin: number?,
  creationFrameMax: number?
) -> decalSet boolean

@param creationFrameMin - (Default: currCreationFrameMin)

@param creationFrameMax - (Default: currCreationFrameMax)

[source]

Use separate min and max for “gradient” style decals such as tank tracks

Spring.SDLSetTextInputRect

---

function Spring.SDLSetTextInputRect(
  x: number,
  y: number,
  width: number,
  height: number
) ->  nil

[source]

Spring.SDLStartTextInput

---

function Spring.SDLStartTextInput() ->  nil

[source]

Spring.SDLStopTextInput

---

function Spring.SDLStopTextInput() ->  nil

[source]

Spring.SetWindowGeometry

---

function Spring.SetWindowGeometry(
  displayIndex: number,
  winRelPosX: number,
  winRelPosY: number,
  winSizeX: number,
  winSizeY: number,
  fullScreen: boolean,
  borderless: boolean
) ->  nil

[source]

Spring.SetWindowMinimized

---

function Spring.SetWindowMinimized() -> minimized boolean

[source]

Spring.SetWindowMaximized

---

function Spring.SetWindowMaximized() -> maximized boolean

[source]

Spring.Reload

---

function Spring.Reload(startScript: string) ->  nil

@param startScript - the CONTENT of the script.txt spring should use to start.

[source]

Spring.Restart

---

function Spring.Restart(
  commandline_args: string,
  startScript: string
) ->  nil

@param commandline_args - commandline arguments passed to spring executable.

[source]

If this call returns, something went wrong

Spring.Start

---

function Spring.Start(
  commandline_args: string,
  startScript: string
) ->  nil

@param commandline_args - commandline arguments passed to spring executable.

@param startScript - the CONTENT of the script.txt spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to commandline_args.

Launches a new Spring instance without terminating the existing one.

[source]

If this call returns, something went wrong

Spring.SetWMIcon

---

function Spring.SetWMIcon(iconFileName: string) ->  nil

Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo).

[source]

Note: has to be 24bit or 32bit. Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) Note: *.bmp images have to be in BGR format (default for m$ ones). Note: *.ico images are not supported.

Spring.ClearWatchDogTimer

---

function Spring.ClearWatchDogTimer(threadName: string?) ->  nil

@param threadName - (Default: main)

[source]

Spring.SetClipboard

---

function Spring.SetClipboard(text: string) ->  nil

[source]

Spring.Yield

---

function Spring.Yield() -> when boolean

@return when - true caller should continue calling Spring.Yield during the widgets/gadgets load, when false it shouldn’t call it any longer.

Relinquish control of the game loading thread and OpenGL context back to the UI (LuaIntro).

[source]

Should be called after each widget/unsynced gadget is loaded in widget/gadget handler. Use it to draw screen updates and process windows events.

@usage local wantYield = Spring.Yield and Spring.Yield() – nil check: not present in synced for wupget in pairs(wupgetsToLoad) do loadWupget(wupget) wantYield = wantYield and Spring.Yield() end

Spring.Echo

---

function Spring.Echo(
  arg: any,
  ...: any
) ->  nil

Prints values in the spring chat console. Useful for debugging.

Hint: the default print() writes to STDOUT.

[source]

Spring.Log

---

function Spring.Log(
  section: string,
  logLevel: (LogLevel|LOG)?,
  ...: string
)

@param section - Sets an arbitrary section. Level filtering can be applied per-section

@param logLevel - (Default: "notice")

@param ... - messages

Logs a message to the logfile/console.

[source]

Spring.GetMetalMapSize

---

function Spring.GetMetalMapSize()
 -> x integer
 -> z integer

@return x - X coordinate in worldspace / Game.metalMapSquareSize.

@return z - Z coordinate in worldspace / Game.metalMapSquareSize.

[source]

Spring.GetMetalAmount

---

function Spring.GetMetalAmount(
  x: integer,
  z: integer
) -> amount number

@param x - X coordinate in worldspace / Game.metalMapSquareSize.

@param z - Z coordinate in worldspace / Game.metalMapSquareSize.

Returns the amount of metal on a single square.

[source]

Spring.SetMetalAmount

---

function Spring.SetMetalAmount(
  x: integer,
  z: integer,
  metalAmount: number
) ->  nil

@param x - X coordinate in worldspace / Game.metalMapSquareSize.

@param z - Z coordinate in worldspace / Game.metalMapSquareSize.

@param metalAmount - must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).

Sets the amount of metal on a single square.

[source]

Spring.GetMetalExtraction

---

function Spring.GetMetalExtraction(
  x: integer,
  z: integer
) -> extraction number

@param x - X coordinate in worldspace / Game.metalMapSquareSize.

@param z - Z coordinate in worldspace / Game.metalMapSquareSize.

[source]

fields

---

Spring.MoveCtrl

---

Spring.MoveCtrl : MoveCtrl {
    IsEnabled: function,
    Enable: function,
    Disable: function,
    SetTag: function,
    GetTag: function,
    SetProgressState: function,
    SetExtrapolate: function,
    SetPhysics: function,
    SetPosition: function,
    SetVelocity: function,
    SetRelativeVelocity: function,
    SetRotation: function,
    ...(+26)
}

[source]