class Callins

Functions called by the Engine.

To use these callins in a widget, prepend widget: and, for a gadget, prepend gadget:. For example:

function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
  -- ...
end

Some functions may differ between (synced) gadget and widgets. This is because all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget. e.g. information about an enemy unit only detected via radar and not yet in LOS.

In such cases the full (synced) param list is documented.

Attention: Some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace.

methods

Callins.ActiveCommandChanged

function Callins.ActiveCommandChanged(
  cmdId: integer?,
  cmdType: integer?
)

Called when a command is issued.

Callins.AddConsoleLine

function Callins.AddConsoleLine(
  msg: string,
  priority: integer
)

Called when text is entered into the console (e.g. Spring.Echo).

Callins.CommandNotify

function Callins.CommandNotify(
  cmdID: integer,
  cmdParams: table,
  options: CommandOptions
) -> Returning boolean

@return Returning - true deletes the command and does not send it through the network.

Called when a command is issued.

Callins.DefaultCommand

function Callins.DefaultCommand(
  type: string,
  id: integer
)

@param type - “unit” | “feature”

@param id - unitID featureID

Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either “unit or “feature”) and the second is its unitID or featureID respectively.

Callins.DownloadFailed

function Callins.DownloadFailed(
  id: number,
  errorID: number
)

Called when a Pr-downloader download fails to complete.

Callins.DownloadFinished

function Callins.DownloadFinished(id: number)

Called when a Pr-downloader download finishes successfully.

Callins.DownloadProgress

function Callins.DownloadProgress(
  id: number,
  downloaded: number,
  total: number
)

Called incrementally during a Pr-downloader download.

Callins.DownloadQueued

function Callins.DownloadQueued(
  id: number,
  name: string,
  type: string
)

Called when a Pr-downloader download is queued

Callins.DownloadStarted

function Callins.DownloadStarted(id: number)

Called when a Pr-downloader download is started via VFS.DownloadArchive.

Callins.DrawFeaturesPostDeferred

function Callins.DrawFeaturesPostDeferred()

Runs at the end of the feature deferred pass to inform Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

Callins.DrawGenesis

function Callins.DrawGenesis()

Use this callin to update textures, shaders, etc.

Doesn’t render to screen! Also available to LuaMenu.

Callins.DrawGroundDeferred

function Callins.DrawGroundDeferred()

Callins.DrawGroundPostDeferred

function Callins.DrawGroundPostDeferred()

This runs at the end of its respective deferred pass.

Allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and DrawWorldPreUnit) via gl.CopyToTexture.

Callins.DrawGroundPostForward

function Callins.DrawGroundPostForward()

Callins.DrawGroundPreDeferred

function Callins.DrawGroundPreDeferred()

Runs at the start of the deferred pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

Callins.DrawGroundPreForward

function Callins.DrawGroundPreForward()

Runs at the start of the forward pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).

Callins.DrawInMiniMap

function Callins.DrawInMiniMap(
  sx: number,
  sy: number
)

@param sx - relative to the minimap’s position and scale.

@param sy - relative to the minimap’s position and scale.

Callins.DrawInMiniMapBackground

function Callins.DrawInMiniMapBackground(
  sx: number,
  sy: number
)

@param sx - relative to the minimap’s position and scale.

@param sy - relative to the minimap’s position and scale.

Callins.DrawPreDecals

function Callins.DrawPreDecals()

Called before decals are drawn

Callins.DrawScreen

function Callins.DrawScreen(
  viewSizeX: number,
  viewSizeY: number
)

Also available to LuaMenu.

Callins.DrawScreenEffects

function Callins.DrawScreenEffects(
  viewSizeX: number,
  viewSizeY: number
)

Callins.DrawScreenPost

function Callins.DrawScreenPost(
  viewSizeX: number,
  viewSizeY: number
)

Similar to DrawScreenEffects, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).

Callins.DrawShadowFeaturesLua

function Callins.DrawShadowFeaturesLua()

Callins.DrawShadowPassTransparent

function Callins.DrawShadowPassTransparent()

Invoked after semi-transparent shadows pass is about to conclude

This callin has depth and color buffer of shadowmap bound via FBO as well as the FFP state to do “semi-transparent” shadows pass (traditionally only used to draw shadows of shadow casting semi-transparent particles). Can be used to draw nice colored shadows.

Callins.DrawShadowUnitsLua

function Callins.DrawShadowUnitsLua()

Callins.DrawUnitsPostDeferred

function Callins.DrawUnitsPostDeferred()

Runs at the end of the unit deferred pass.

Informs Lua code it should make use of the $model_gbuffer_* textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and DrawWorld via gl.CopyToTexture). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

Callins.DrawWaterPost

function Callins.DrawWaterPost()

Callins.DrawWorld

function Callins.DrawWorld()

Spring draws command queues, ‘map stuff’, and map marks.

Callins.DrawWorldPreParticles

function Callins.DrawWorldPreParticles(
  drawAboveWater: boolean,
  drawBelowWater: boolean,
  drawReflection: boolean,
  drawRefraction: boolean
)

DrawWorldPreParticles is called multiples times per draw frame. Each call has a different permutation of values for drawAboveWater, drawBelowWater, drawReflection, and drawRefraction.

Callins.DrawWorldPreUnit

function Callins.DrawWorldPreUnit()

Spring draws units, features, some water types, cloaked units, and the sun.

Callins.DrawWorldReflection

function Callins.DrawWorldReflection()

Callins.DrawWorldRefraction

function Callins.DrawWorldRefraction()

Callins.DrawWorldShadow

function Callins.DrawWorldShadow()

Callins.Explosion

function Callins.Explosion(
  weaponDefID: number,
  px: number,
  py: number,
  pz: number,
  attackerID: number,
  projectileID: number
) -> noGfx boolean

@return noGfx - if then no graphical effects are drawn by the engine for this explosion.

Called when an explosion occurs.

Callins.FeatureCreated

function Callins.FeatureCreated(
  featureID: number,
  allyTeamID: number
)

Called when a feature is created.

Callins.FeatureDamaged

function Callins.FeatureDamaged(
  featureID: number,
  featureDefID: number,
  featureTeam: number,
  damage: number,
  weaponDefID: number,
  projectileID: number,
  attackerID: number,
  attackerDefID: number,
  attackerTeam: number
)

Called when a feature is damaged.

Callins.FeatureDestroyed

function Callins.FeatureDestroyed(
  featureID: number,
  allyTeamID: number
)

Called when a feature is destroyed.

Callins.FontsChanged

function Callins.FontsChanged()

Called whenever fonts are updated. Signals the game display lists and other caches should be discarded.

Gets called before other Update and Draw callins.

Callins.GameFrame

function Callins.GameFrame(frame: number)

@param frame - Starts at frame 1

Called for every game simulation frame (30 per second).

Callins.GameFramePost

function Callins.GameFramePost(frame: number)

@param frame - Starts at frame 1

Called at the end of every game simulation frame

Callins.GameID

function Callins.GameID(gameID: string)

@param gameID - encoded in hex.

Called once to deliver the gameID

Callins.GameOver

function Callins.GameOver(winningAllyTeams: number[])

@param winningAllyTeams - list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).

Called when the game ends

Callins.GamePaused

function Callins.GamePaused(
  playerID: number,
  paused: boolean
)

Called when the game is paused.

Callins.GamePreload

function Callins.GamePreload()

Called before the 0 gameframe.

Is not called when a saved game is loaded.

Callins.GameProgress

function Callins.GameProgress(serverFrameNum: integer)

Called every 60 frames, calculating delta between GameFrame and GameProgress.

Can give an ETA about catching up with simulation for mid-game join players.

Callins.GameSetup

function Callins.GameSetup(
  state: string,
  ready: boolean,
  playerStates: table
)
 -> success boolean
 -> newReady boolean

Callins.GameStart

function Callins.GameStart()

Called upon the start of the game.

Is not called when a saved game is loaded.

Callins.GetTooltip

function Callins.GetTooltip(
  x: number,
  y: number
) -> tooltip string

Called when Spring.IsAbove returns true.

Callins.GotChatMsg

function Callins.GotChatMsg(
  msg: string,
  playerID: number
)

Called when a player issues a UI command e.g. types /foo or /luarules foo.

Callins.GroupChanged

function Callins.GroupChanged(groupID: number)

Called when a unit is added to or removed from a control group.

Callins.Initialize

function Callins.Initialize()

Called when the addon is (re)loaded.

Callins.IsAbove

function Callins.IsAbove(
  x: number,
  y: number
) -> isAbove boolean

Called every Update.

Must return true for Mouse* events and Spring.GetToolTip to be called.

Callins.KeyMapChanged

function Callins.KeyMapChanged()

Called when the keymap changes

Can be caused due to a change in language or keyboard

Callins.KeyPress

function Callins.KeyPress(
  keyCode: number,
  mods: KeyModifiers,
  isRepeat: boolean,
  label: boolean,
  utf32char: number,
  scanCode: number,
  actionList: table
) -> halt boolean

@param isRepeat - If you want an action to occur only once check for isRepeat == false.

@param label - the name of the key

@param utf32char - (deprecated) always 0

@param actionList - the list of actions for this keypress

@return halt - whether to halt the chain for consumers of the keypress

Called repeatedly when a key is pressed down.

Return true if you don’t want other callins or the engine to also receive this keypress. A list of key codes can be seen at the SDL wiki.

Callins.KeyRelease

function Callins.KeyRelease(
  keyCode: number,
  mods: KeyModifiers,
  label: boolean,
  utf32char: number,
  scanCode: number,
  actionList: table
) ->  boolean

@param label - the name of the key

@param utf32char - (deprecated) always 0

@param actionList - the list of actions for this keyrelease

Called when the key is released.

Callins.Load

function Callins.Load(zipReader: table)

Called after GamePreload and before GameStart. See Lua_SaveLoad.

Callins.LoadCode

function Callins.LoadCode()

Called when the game is (re)loaded.

Callins.MapDrawCmd

function Callins.MapDrawCmd(
  playerID: number,
  type: string,
  posX: number,
  posY: number,
  posZ: number,
  data4: (string|number),
  pos2Y: number?,
  pos2Z: number?
)

@param type - “point” | “line” | “erase”

@param data4 - point: label, erase: radius, line: pos2X

@param pos2Y - when type is line

@param pos2Z - when type is line

Callins.MouseMove

function Callins.MouseMove(
  x: number,
  y: number,
  dx: number,
  dy: number,
  button: number
)

@param x - final x position

@param y - final y position

@param dx - distance travelled in x

@param dy - distance travelled in y

Called when the mouse is moved.

Callins.MousePress

function Callins.MousePress(
  x: number,
  y: number,
  button: number
) -> becomeMouseOwner boolean

Called when a mouse button is pressed.

The button parameter supports up to 7 buttons. Must return true for MouseRelease and other functions to be called.

Callins.MouseRelease

function Callins.MouseRelease(
  x: number,
  y: number,
  button: number
) -> becomeMouseOwner boolean

Called when a mouse button is released.

Please note that in order to have Spring call Spring.MouseRelease, you need to have a Spring.MousePress call-in in the same addon that returns true.

Callins.MouseWheel

function Callins.MouseWheel(
  up: boolean,
  value: number
)

@param up - the direction

@param value - the amount travelled

Called when the mouse wheel is moved.

Callins.PlayerAdded

function Callins.PlayerAdded(playerID: number)

Called whenever a new player joins the game.

Callins.PlayerChanged

function Callins.PlayerChanged(playerID: number)

Called whenever a player’s status changes e.g. becoming a spectator.

Callins.PlayerRemoved

function Callins.PlayerRemoved(
  playerID: number,
  reason: string
)

Called whenever a player is removed from the game.

Callins.ProjectileCreated

function Callins.ProjectileCreated(
  proID: number,
  proOwnerID: number,
  weaponDefID: number
)

Called when the projectile is created.

Note that weaponDefID is missing if the projectile is spawned as part of a burst, but Spring.GetProjectileDefID and Spring.GetProjectileName still work in callin scope using proID.

Callins.ProjectileDestroyed

function Callins.ProjectileDestroyed(
  proID: number,
  ownerID: number,
  proWeaponDefID: number
)

Called when the projectile is destroyed.

Callins.RecvLuaMsg

function Callins.RecvLuaMsg(
  msg: string,
  playerID: number
)

Receives messages from unsynced sent via Spring.SendLuaRulesMsg or Spring.SendLuaUIMsg.

Callins.RecvSkirmishAIMessage

function Callins.RecvSkirmishAIMessage(
  aiTeam: integer,
  dataStr: string
)

Callins.RenderUnitDestroyed

function Callins.RenderUnitDestroyed(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Called just before a unit is invalid, after it finishes its death animation.

Callins.Save

function Callins.Save(zip: table)

@param zip - a userdatum representing the savegame zip file. See Lua_SaveLoad.

Called when a chat command ‘/save’ or ‘/savegame’ is received.

Callins.Shutdown

function Callins.Shutdown() ->  nil

Called when the addon or the game is shutdown.

Callins.StockpileChanged

function Callins.StockpileChanged(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  weaponNum: integer,
  oldCount: integer,
  newCount: integer
)

Called when a units stockpile of weapons increases or decreases.

Callins.SunChanged

function Callins.SunChanged()

Callins.TeamChanged

function Callins.TeamChanged(teamID: number)

Callins.TeamDied

function Callins.TeamDied(teamID: number)

Called when a team dies (see Spring.KillTeam).

Callins.TextEditing

function Callins.TextEditing(
  utf8: string,
  start: number,
  length: number
)

Callins.TextInput

function Callins.TextInput(utf8char: string)

Called whenever a key press results in text input.

Callins.UnitArrivedAtGoal

function Callins.UnitArrivedAtGoal(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitCloaked

function Callins.UnitCloaked(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Called when a unit cloaks.

Callins.UnitCmdDone

function Callins.UnitCmdDone(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  cmdID: number,
  cmdParams: table,
  options: CommandOptions,
  cmdTag: number
)

Called when a unit completes a command.

Callins.UnitCommand

function Callins.UnitCommand(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  cmdID: number,
  cmdParams: table,
  options: CommandOptions,
  cmdTag: number
)

Called after when a unit accepts a command, after AllowCommand returns true.

Callins.UnitConstructionDecayed

function Callins.UnitConstructionDecayed(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  timeSinceLastBuild: number,
  iterationPeriod: number,
  part: number
)

Called when a unit being built starts decaying.

Callins.UnitCreated

function Callins.UnitCreated(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  builderID: number?
)

Called at the moment the unit is created.

Callins.UnitDamaged

function Callins.UnitDamaged(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  damage: number,
  paralyzer: number,
  weaponDefID: number,
  projectileID: number,
  attackerID: number,
  attackerDefID: number,
  attackerTeam: number
)

Called when a unit is damaged (after UnitPreDamaged).

Callins.UnitDecloaked

function Callins.UnitDecloaked(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Called when a unit decloaks.

Callins.UnitDestroyed

function Callins.UnitDestroyed(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  attackerID: number,
  attackerDefID: number,
  attackerTeam: number,
  weaponDefID: number
)

Called when a unit is destroyed.

Callins.UnitEnteredAir

function Callins.UnitEnteredAir(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitEnteredLos

function Callins.UnitEnteredLos(
  unitID: integer,
  unitTeam: integer,
  allyTeam: integer,
  unitDefID: integer
)

@param allyTeam - who’s LOS the unit entered.

Called when a unit enters LOS of an allyteam.

Its called after the unit is in LOS, so you can query that unit.

Callins.UnitEnteredRadar

function Callins.UnitEnteredRadar(
  unitID: integer,
  unitTeam: integer,
  allyTeam: integer,
  unitDefID: integer
)

Called when a unit enters radar of an allyteam.

Also called when a unit enters LOS without any radar coverage.

Callins.UnitEnteredUnderwater

function Callins.UnitEnteredUnderwater(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitEnteredWater

function Callins.UnitEnteredWater(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitExperience

function Callins.UnitExperience(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  experience: number,
  oldExperience: number
)

Called when a unit gains experience greater or equal to the minimum limit set by calling Spring.SetExperienceGrade.

Should be called more reliably with small values of experience grade.

Callins.UnitFeatureCollision

function Callins.UnitFeatureCollision(
  colliderID: number,
  collideeID: number
)

Called when a unit collides with a feature.

The unit must be registered with Script.SetWatchUnit and the feature registered with Script.SetWatchFeature.

Callins.UnitFinished

function Callins.UnitFinished(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Called at the moment the unit is completed.

Callins.UnitFromFactory

function Callins.UnitFromFactory(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  factID: number,
  factDefID: number,
  userOrders: boolean
)

Called when a factory finishes construction of a unit.

Callins.UnitGiven

function Callins.UnitGiven(
  unitID: integer,
  unitDefID: integer,
  newTeam: number,
  oldTeam: number
)

Called when a unit is transferred between teams. This is called after UnitTaken and in that moment unit is assigned to the newTeam.

Callins.UnitHarvestStorageFull

function Callins.UnitHarvestStorageFull(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Called when a unit’s harvestStorage is full (according to its unitDef’s entry).

Callins.UnitIdle

function Callins.UnitIdle(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Called when a unit is idle (empty command queue).

Callins.UnitLeftAir

function Callins.UnitLeftAir(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitLeftLos

function Callins.UnitLeftLos(
  unitID: integer,
  unitTeam: integer,
  allyTeam: integer,
  unitDefID: integer
)

Called when a unit leaves LOS of an allyteam.

For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.

Callins.UnitLeftRadar

function Callins.UnitLeftRadar(
  unitID: integer,
  unitTeam: integer,
  allyTeam: integer,
  unitDefID: integer
)

Called when a unit leaves radar of an allyteam.

Also called when a unit leaves LOS without any radar coverage. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.

Callins.UnitLeftUnderwater

function Callins.UnitLeftUnderwater(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitLeftWater

function Callins.UnitLeftWater(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitLoaded

function Callins.UnitLoaded(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  transportID: integer,
  transportTeam: integer
)

Called when a unit is loaded by a transport.

Callins.UnitMoveFailed

function Callins.UnitMoveFailed(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Callins.UnitReverseBuilt

function Callins.UnitReverseBuilt(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer
)

Called when a living unit becomes a nanoframe again.

Callins.UnitSeismicPing

function Callins.UnitSeismicPing(
  x: number,
  y: number,
  z: number,
  strength: number,
  allyTeam: integer,
  unitID: integer,
  unitDefID: integer
)

Called when a unit emits a seismic ping.

See seismicSignature.

Callins.UnitStunned

function Callins.UnitStunned(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  stunned: boolean
)

Called when a unit changes its stun status.

Callins.UnitTaken

function Callins.UnitTaken(
  unitID: integer,
  unitDefID: integer,
  oldTeam: number,
  newTeam: number
)

Called when a unit is transferred between teams. This is called before UnitGiven and in that moment unit is still assigned to the oldTeam.

Callins.UnitUnitCollision

function Callins.UnitUnitCollision(
  colliderID: number,
  collideeID: number
)

Called when two units collide.

Both units must be registered with Script.SetWatchUnit.

Callins.UnitUnloaded

function Callins.UnitUnloaded(
  unitID: integer,
  unitDefID: integer,
  unitTeam: integer,
  transportID: integer,
  transportTeam: integer
)

Called when a unit is unloaded by a transport.

Callins.UnsyncedHeightMapUpdate

function Callins.UnsyncedHeightMapUpdate()
 -> x1 number
 -> z1 number
 -> x2 number
 -> z2 number

Called when the unsynced copy of the height-map is altered.

Callins.Update

function Callins.Update(dt: number)

@param dt - the time since the last update.

Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up.

Callins.ViewResize

function Callins.ViewResize(
  viewSizeX: number,
  viewSizeY: number
)

Called whenever the window is resized.

Callins.WorldTooltip

function Callins.WorldTooltip(
  ttType: string,
  data1: number,
  data2: number?,
  data3: number?
) -> newTooltip string

@param ttType - “unit” | “feature” | “ground” | “selection”

@param data1 - unitID featureID posX

@param data2 - posY

@param data3 - posZ