Module `LuaHandle`

Callins, functions called by the Engine

This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the changelog.

Related Sourcecode: LuaHandle.cpp

For now, to use these addons 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; those are in the Synced - Unsynced Shared section. Essentially the reason is that 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. This document will be continuously updated to properly alert about those situations.

Teams

TeamDied: Called when a team dies (see Spring.KillTeam).
TeamChanged
PlayerChanged: Called whenever a player's status changes e.g.
PlayerAdded: Called whenever a new player joins the game.
PlayerRemoved: Called whenever a player is removed from the game.

Projectiles

ProjectileCreated: Called when the projectile is created.
ProjectileDestroyed: Called when the projectile is destroyed.
Explosion: Called when an explosion occurs.
StockpileChanged: Called when a units stockpile of weapons increases or decreases.
RecvLuaMsg: Receives messages from unsynced sent via Spring.SendLuaRulesMsg or Spring.SendLuaUIMsg.
Save: Called when a chat command '/save' or '/savegame' is received.
UnsyncedHeightMapUpdate: Called when the unsynced copy of the height-map is altered.
Update: Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up.
ViewResize: Called whenever the window is resized.
SunChanged
DefaultCommand: Used to set the default command when a unit is selected.

Features

FeatureCreated: Called when a feature is created.
FeatureDestroyed: Called when a feature is destroyed.
FeatureDamaged: Called when a feature is damaged.

Common

Initialize: Called when the addon is (re)loaded.
LoadCode: Called when the game is (re)loaded.
Shutdown: Called when the addon or the game is shutdown.
GotChatMsg: Called when a player issues a UI command e.g.
Load: Called after GamePreload and before GameStart.

Game

GamePreload: Called before the 0 gameframe.
GameStart: Called upon the start of the game.
GameOver: Called when the game ends
GamePaused: Called when the game is paused.
GameFrame: Called for every game simulation frame (30 per second).
GameFramePost: Called at the end of every game simulation frame
GameID: Called once to deliver the gameID

Units

UnitCreated: Called at the moment the unit is created.
UnitFinished: Called at the moment the unit is completed.
UnitFromFactory: Called when a factory finishes construction of a unit.
UnitReverseBuilt: Called when a living unit becomes a nanoframe again.
UnitConstructionDecayed: Called when a unit being built starts decaying.
UnitDestroyed: Called when a unit is destroyed.
UnitTaken: Called when a unit is transferred between teams.
UnitGiven: Called when a unit is transferred between teams.
UnitIdle: Called when a unit is idle (empty command queue).
UnitCommand: Called after when a unit accepts a command, after AllowCommand returns true.
UnitCmdDone: Called when a unit completes a command.
UnitDamaged: Called when a unit is damaged (after UnitPreDamaged).
UnitStunned: Called when a unit changes its stun status.
UnitExperience: Called when a unit gains experience greater or equal to the minimum limit set by calling Spring.SetExperienceGrade.
UnitHarvestStorageFull: Called when a unit's harvestStorage is full (according to its unitDef's entry).
UnitSeismicPing: Called when a unit emits a seismic ping.
UnitEnteredRadar: Called when a unit enters radar of an allyteam.
UnitEnteredLos: Called when a unit enters LOS of an allyteam.
UnitLeftRadar: Called when a unit leaves radar of an allyteam.
UnitLeftLos: Called when a unit leaves LOS of an allyteam.

Transport

UnitLoaded: Called when a unit is loaded by a transport.
UnitUnloaded: Called when a unit is unloaded by a transport.

Unit Interactions

UnitEnteredUnderwater
UnitEnteredWater
UnitLeftAir
UnitLeftUnderwater
UnitLeftWater
UnitEnteredAir
UnitCloaked: Called when a unit cloaks.
UnitDecloaked: Called when a unit decloaks.
UnitUnitCollision: Called when two units collide.
UnitFeatureCollision: Called when a unit collides with a feature.
UnitMoveFailed
UnitArrivedAtGoal
RenderUnitDestroyed: Called just before a unit is invalid, after it finishes its death animation.

Draw* Functions

DrawGenesis: Use this callin to update textures, shaders, etc.
DrawWorld: Spring draws command queues, 'map stuff', and map marks.
DrawWorldPreUnit: Spring draws units, features, some water types, cloaked units, and the sun.
DrawPreDecals: Called before decals are drawn
DrawWaterPost
DrawShadowPassTransparent: Invoked after semi-transparent shadows pass is about to conclude
DrawWorldShadow
DrawWorldReflection
DrawWorldRefraction
DrawGroundPreForward: Runs at the start of the forward pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).
DrawGroundPostForward
DrawGroundPreDeferred: Runs at the start of the deferred pass when a custom map shader has been assigned via Spring.SetMapShader (convenient for setting uniforms).
DrawGroundDeferred
DrawGroundPostDeferred: This runs at the end of its respective deferred pass.
DrawUnitsPostDeferred: Runs at the end of the unit deferred pass.
DrawFeaturesPostDeferred: Runs at the end of the feature deferred pass to inform Lua code it should make use of the $modelgbuffer* textures before another pass overwrites them (and to allow proper blending with e.g.
DrawShadowUnitsLua
DrawShadowFeaturesLua
DrawWorldPreParticles: DrawWorldPreParticles is called multiples times per draw frame.
DrawScreen: Also available to LuaMenu.
DrawScreenEffects
DrawScreenPost: Similar to DrawScreenEffects, this can be used to alter the contents of a frame after it has been completely rendered (i.e.
DrawInMinimap
DrawInMinimapBackground
GameProgress: Called every 60 frames, calculating delta between GameFrame and GameProgress.
KeyMapChanged: Called when the keymap changes

Input

mods: Key Modifier Params
KeyPress: Called repeatedly when a key is pressed down.
KeyRelease: Called when the key is released.
TextInput: Called whenever a key press results in text input.
TextEditing
MousePress: Called when a mouse button is pressed.
MouseRelease: Called when a mouse button is released.
MouseMove: Called when the mouse is moved.
MouseWheel: Called when the mouse wheel is moved.
IsAbove: Called every Update.
GetTooltip: Called when Spring.IsAbove returns true.
cmdOpts: Parameters for command options
CommandNotify: Called when a command is issued.
AddConsoleLine: Called when text is entered into the console (e.g.
GroupChanged: Called when a unit is added to or removed from a control group.
WorldTooltip
MapDrawCmd
GameSetup
RecvSkirmishAIMessage

Downloads

DownloadQueued: Called when a Pr-downloader download is queued
DownloadStarted: Called when a Pr-downloader download is started via VFS.DownloadArchive.
DownloadFinished: Called when a Pr-downloader download finishes successfully.
DownloadFailed: Called when a Pr-downloader download fails to complete.
DownloadProgress: Called incrementally during a Pr-downloader download.

Teams

TeamDied(teamID)

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

Parameters:

teamID number

TeamChanged(teamID)

Parameters:

teamID number

PlayerChanged(playerID)

Called whenever a player's status changes e.g.

becoming a spectator.

Parameters:

playerID number

PlayerAdded(playerID)

Called whenever a new player joins the game.

Parameters:

playerID number

PlayerRemoved(playerID, reason)

Called whenever a player is removed from the game.

Parameters:

playerID number
reason string

Projectiles

ProjectileCreated(proID, proOwnerID, weaponDefID)

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.

Parameters:

proID number
proOwnerID number
weaponDefID number

ProjectileDestroyed(proID, ownerID, proWeaponDefID)

Called when the projectile is destroyed.

Parameters:

proID number
ownerID number
proWeaponDefID number

Explosion(weaponDefID, px, py, pz, attackerID, projectileID)

Called when an explosion occurs.

Parameters:

weaponDefID number
px number
py number
pz number
attackerID number
projectileID number

Returns:

bool noGfx if then no graphical effects are drawn by the engine for this explosion.

StockpileChanged(unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount)

Called when a units stockpile of weapons increases or decreases.

Parameters:

unitID number
unitDefID number
unitTeam number
weaponNum number
oldCount number
newCount number

RecvLuaMsg(msg, playerID)

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

Parameters:

msg string
playerID number

Save(zip)

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

Parameters:

zip table a userdatum representing the savegame zip file. See Lua_SaveLoad.

UnsyncedHeightMapUpdate()

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

Returns:

Update(dt)

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

Parameters:

dt number the time since the last update.

ViewResize(viewSizeX, viewSizeY)

Called whenever the window is resized.

Parameters:

viewSizeX number
viewSizeY number

SunChanged()

DefaultCommand(type, id)

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.

Parameters:

type string "unit" | "feature"
id int unitID | featureID

Features

FeatureCreated(featureID, allyTeamID)

Called when a feature is created.

Parameters:

featureID number
allyTeamID number

FeatureDestroyed(featureID, allyTeamID)

Called when a feature is destroyed.

Parameters:

featureID number
allyTeamID number

FeatureDamaged(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Called when a feature is damaged.

Parameters:

featureID number
featureDefID number
featureTeam number
damage number
weaponDefID number
projectileID number
attackerID number
attackerDefID number
attackerTeam number

Common

Initialize()

Called when the addon is (re)loaded.

LoadCode()

Called when the game is (re)loaded.

Shutdown()

Called when the addon or the game is shutdown.

Returns:

nil

GotChatMsg(msg, playerID)

Called when a player issues a UI command e.g.

types /foo or /luarules foo.

Parameters:

msg string
playerID number

Load(zipReader)

Called after `GamePreload` and before `GameStart`.

See Lua_SaveLoad.

Parameters:

zipReader table

Game

GamePreload()

Called before the 0 gameframe.

Is not called when a saved game is loaded.

GameStart()

Called upon the start of the game.

Is not called when a saved game is loaded.

GameOver(winningAllyTeams)

Called when the game ends

Parameters:

winningAllyTeams {number,...} list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).

GamePaused(playerID, paused)

Called when the game is paused.

Parameters:

playerID number
paused bool

GameFrame(frame)

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

Parameters:

frame number Starts at frame 1

GameFramePost(frame)

Called at the end of every game simulation frame

Parameters:

frame number Starts at frame 1

GameID(gameID)

Called once to deliver the gameID

Parameters:

gameID string encoded in hex.

Units

UnitCreated(unitID, unitDefID, unitTeam[, builderID])

Called at the moment the unit is created.

Parameters:

unitID number
unitDefID number
unitTeam number
builderID number (optional)

UnitFinished(unitID, unitDefID, unitTeam)

Called at the moment the unit is completed.

Parameters:

unitID number
unitDefID number
unitTeam number

UnitFromFactory(unitID, unitDefID, unitTeam, factID, factDefID, userOrders)

Called when a factory finishes construction of a unit.

Parameters:

unitID number
unitDefID number
unitTeam number
factID number
factDefID number
userOrders bool

UnitReverseBuilt(unitID, unitDefID, unitTeam)

Called when a living unit becomes a nanoframe again.

Parameters:

unitID number
unitDefID number
unitTeam number

UnitConstructionDecayed(unitID, unitDefID, unitTeam, timeSinceLastBuild, iterationPeriod, part)

Called when a unit being built starts decaying.

Parameters:

unitID number
unitDefID number
unitTeam number
timeSinceLastBuild number
iterationPeriod number
part number

UnitDestroyed(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam, weaponDefID)

Called when a unit is destroyed.

Parameters:

unitID number
unitDefID number
unitTeam number
attackerID number
attackerDefID number
attackerTeam number
weaponDefID number

UnitTaken(unitID, unitDefID, oldTeam, newTeam)

Called when a unit is transferred between teams.

This is called before `UnitGiven` and in that moment unit is still assigned to the oldTeam.

Parameters:

unitID number
unitDefID number
oldTeam number
newTeam number

UnitGiven(unitID, unitDefID, newTeam, oldTeam)

Called when a unit is transferred between teams.

This is called after `UnitTaken` and in that moment unit is assigned to the newTeam.

Parameters:

unitID number
unitDefID number
newTeam number
oldTeam number

UnitIdle(unitID, unitDefID, unitTeam)

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

Parameters:

unitID number
unitDefID number
unitTeam number

UnitCommand(unitID, unitDefID, unitTeam, cmdID, cmdParams, options, cmdTag)

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

Parameters:

unitID number
unitDefID number
unitTeam number
cmdID number
cmdParams table
options cmdOpts
cmdTag number

UnitCmdDone(unitID, unitDefID, unitTeam, cmdID, cmdParams, options, cmdTag)

Called when a unit completes a command.

Parameters:

unitID number
unitDefID number
unitTeam number
cmdID number
cmdParams table
options cmdOpts
cmdTag number

UnitDamaged(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Called when a unit is damaged (after UnitPreDamaged).

Parameters:

unitID number
unitDefID number
unitTeam number
damage number
paralyzer number
weaponDefID number
projectileID number
attackerID number
attackerDefID number
attackerTeam number

UnitStunned(unitID, unitDefID, unitTeam, stunned)

Called when a unit changes its stun status.

Parameters:

unitID number
unitDefID number
unitTeam number
stunned bool

UnitExperience(unitID, unitDefID, unitTeam, experience, oldExperience)

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.

Parameters:

unitID number
unitDefID number
unitTeam number
experience number
oldExperience number

UnitHarvestStorageFull(unitID, unitDefID, unitTeam)

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

Parameters:

unitID number
unitDefID number
unitTeam number

UnitSeismicPing(x, y, z, strength, allyTeam, unitID, unitDefID)

Called when a unit emits a seismic ping.

See `seismicSignature`.

Parameters:

x number
y number
z number
strength number
allyTeam number
unitID number
unitDefID number

UnitEnteredRadar(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters radar of an allyteam.

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

Parameters:

unitID number
unitTeam number
allyTeam number
unitDefID number

UnitEnteredLos(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters LOS of an allyteam.

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

Parameters:

unitID number
unitTeam number
allyTeam number who's LOS the unit entered.
unitDefID number

UnitLeftRadar(unitID, unitTeam, allyTeam, unitDefID)

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.

Parameters:

unitID number
unitTeam number
allyTeam number
unitDefID number

UnitLeftLos(unitID, unitTeam, allyTeam, unitDefID)

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.

Parameters:

unitID number
unitTeam number
allyTeam number
unitDefID number

Transport

UnitLoaded(unitID, unitDefID, unitTeam, transportID, transportTeam)

Called when a unit is loaded by a transport.

Parameters:

unitID number
unitDefID number
unitTeam number
transportID number
transportTeam number

UnitUnloaded(unitID, unitDefID, unitTeam, transportID, transportTeam)

Called when a unit is unloaded by a transport.

Parameters:

unitID number
unitDefID number
unitTeam number
transportID number
transportTeam number

Unit Interactions

UnitEnteredUnderwater(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

UnitEnteredWater(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

UnitLeftAir(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

UnitLeftUnderwater(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

UnitLeftWater(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

UnitEnteredAir(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

UnitCloaked(unitID, unitDefID, unitTeam)

Called when a unit cloaks.

Parameters:

unitID number
unitDefID number
unitTeam number

UnitDecloaked(unitID, unitDefID, unitTeam)

Called when a unit decloaks.

Parameters:

unitID number
unitDefID number
unitTeam number

UnitUnitCollision(colliderID, collideeID)

Called when two units collide.

Both units must be registered with `Script.SetWatchUnit`.

Parameters:

colliderID number
collideeID number

UnitFeatureCollision(colliderID, collideeID)

Called when a unit collides with a feature.

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

Parameters:

colliderID number
collideeID number

UnitMoveFailed(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

UnitArrivedAtGoal(unitID, unitDefID, unitTeam)

Parameters:

unitID number
unitDefID number
unitTeam number

RenderUnitDestroyed(unitID, unitDefID, unitTeam)

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

Parameters:

unitID number
unitDefID number
unitTeam number

Draw* Functions

Inside the Draw* functions, you can use the Lua OpenGL Api to draw graphics.

Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

DrawGenesis()

Use this callin to update textures, shaders, etc.

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

DrawWorld()

Spring draws command queues, 'map stuff', and map marks.

DrawWorldPreUnit()

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

DrawPreDecals()

Called before decals are drawn

DrawWaterPost()

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.

DrawWorldShadow()

DrawWorldReflection()

DrawWorldRefraction()

DrawGroundPreForward()

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

DrawGroundPostForward()

DrawGroundPreDeferred()

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

DrawGroundDeferred()

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

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.

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.

DrawShadowUnitsLua()

DrawShadowFeaturesLua()

DrawWorldPreParticles(drawAboveWater, drawBelowWater, drawReflection, drawRefraction)

DrawWorldPreParticles is called multiples times per draw frame.

Each call has a different permutation of values for drawAboveWater, drawBelowWater, drawReflection, and drawRefraction.

Parameters:

drawAboveWater bool
drawBelowWater bool
drawReflection bool
drawRefraction bool

DrawScreen(viewSizeX, viewSizeY)

Also available to LuaMenu.

Parameters:

viewSizeX number
viewSizeY number

DrawScreenEffects(viewSizeX, viewSizeY)

Parameters:

viewSizeX number
viewSizeY number

DrawScreenPost(viewSizeX, viewSizeY)

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

Parameters:

viewSizeX number
viewSizeY number

DrawInMinimap(sx, sy)

Parameters:

sx number relative to the minimap's position and scale.
sy number relative to the minimap's position and scale.

DrawInMinimapBackground(sx, sy)

Parameters:

sx number relative to the minimap's position and scale.
sy number relative to the minimap's position and scale.

GameProgress(serverFrameNum)

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

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

Parameters:

serverFrameNum int

KeyMapChanged()

Called when the keymap changes

Can be caused due to a change in language or keyboard

Input

mods

Key Modifier Params

Fields:

right bool Right mouse key pressed
alt bool Alt key pressed
ctrl bool Ctrl key pressed
shift bool Shift key pressed

KeyPress(keyCode, mods, isRepeat, label, utf32char, scanCode, actionList)

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.

Parameters:

keyCode number
mods mods
isRepeat bool If you want an action to occur only once check for isRepeat == false.
label bool the name of the key
utf32char number (deprecated) always 0
scanCode number
actionList table the list of actions for this keypress

Returns:

boolean halt whether to halt the chain for consumers of the keypress

KeyRelease(keyCode, mods, label, utf32char, scanCode, actionList)

Called when the key is released.

Parameters:

keyCode number
mods mods
label bool the name of the key
utf32char number (deprecated) always 0
scanCode number
actionList table the list of actions for this keyrelease

Returns:

bool

TextInput(utf8char)

Called whenever a key press results in text input.

Parameters:

utf8char string

TextEditing(utf8, start, length)

Parameters:

utf8 string
start number
length number

MousePress(x, y, button)

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.

Parameters:

x number
y number
button number

Returns:

boolean becomeMouseOwner

MouseRelease(x, y, button)

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.

Parameters:

x number
y number
button number

Returns:

boolean becomeMouseOwner

MouseMove(x, y, dx, dy, button)

Called when the mouse is moved.

Parameters:

x number final x position
y number final y position
dx number distance travelled in x
dy number distance travelled in y
button number

MouseWheel(up, value)

Called when the mouse wheel is moved.

Parameters:

up bool the direction
value number the amount travelled

IsAbove(x, y)

Called every `Update`.

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

Parameters:

x number
y number

Returns:

boolean isAbove

GetTooltip(x, y)

Called when `Spring.IsAbove` returns true.

Parameters:

x number
y number

Returns:

string tooltip

cmdOpts

Parameters for command options

Fields:

coded int
alt bool
ctrl bool
shift bool
right bool
meta bool
internal bool

CommandNotify(cmdID, cmdParams, options)

Called when a command is issued.

Parameters:

cmdID int
cmdParams table
options cmdOpts

Returns:

boolean Returning true deletes the command and does not send it through the network.

AddConsoleLine(msg, priority)

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

`Spring.Echo`).

Parameters:

msg string
priority int

GroupChanged(groupID)

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

Parameters:

groupID number

WorldTooltip(ttType, data1[, data2[, data3]])

Parameters:

ttType string "unit" | "feature" | "ground" | "selection"
data1 number unitID | featureID | posX
data2 number posY (optional)
data3 number posZ (optional)

Returns:

string newTooltip

MapDrawCmd(playerID, type, posX, posY, posZ, data4[, pos2Y[, pos2Z]])

Parameters:

playerID number
type string "point" | "line" | "erase"
posX number
posY number
posZ number
data4 string or number point: label, erase: radius, line: pos2X
pos2Y number when type is line (optional)
pos2Z number when type is line (optional)

GameSetup(state, ready, playerStates)

Parameters:

state string
ready bool
playerStates table

Returns:

bool success
bool newReady

RecvSkirmishAIMessage(aiTeam, dataStr)

Parameters:

aiTeam int
dataStr string

Downloads

DownloadQueued(id, name, type)

Called when a Pr-downloader download is queued

Parameters:

id number
name string
type string

DownloadStarted(id)

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

Parameters:

id number

DownloadFinished(id)

Called when a Pr-downloader download finishes successfully.

Parameters:

id number

DownloadFailed(id, errorID)

Called when a Pr-downloader download fails to complete.

Parameters:

id number
errorID number

DownloadProgress(id, downloaded, total)

Called incrementally during a Pr-downloader download.

Parameters:

id number
downloaded number
total number

Module LuaHandle

See also:

Teams

TeamDied(teamID)

Parameters:

TeamChanged(teamID)

Parameters:

PlayerChanged(playerID)

Parameters:

PlayerAdded(playerID)

Parameters:

PlayerRemoved(playerID, reason)

Parameters:

Projectiles

ProjectileCreated(proID, proOwnerID, weaponDefID)

Parameters:

ProjectileDestroyed(proID, ownerID, proWeaponDefID)

Parameters:

Explosion(weaponDefID, px, py, pz, attackerID, projectileID)

Parameters:

Returns:

StockpileChanged(unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount)

Parameters:

RecvLuaMsg(msg, playerID)

Parameters:

Save(zip)

Parameters:

UnsyncedHeightMapUpdate()

Returns:

Update(dt)

Parameters:

ViewResize(viewSizeX, viewSizeY)

Parameters:

SunChanged()

DefaultCommand(type, id)

Parameters:

Features

FeatureCreated(featureID, allyTeamID)

Parameters:

FeatureDestroyed(featureID, allyTeamID)

Parameters:

FeatureDamaged(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Parameters:

Common

Initialize()

LoadCode()

Shutdown()

Returns:

GotChatMsg(msg, playerID)

Parameters:

Load(zipReader)

Parameters:

Game

GamePreload()

GameStart()

GameOver(winningAllyTeams)

Parameters:

GamePaused(playerID, paused)

Parameters:

GameFrame(frame)

Parameters:

GameFramePost(frame)

Parameters:

GameID(gameID)

Parameters:

Units

UnitCreated(unitID, unitDefID, unitTeam[, builderID])

Parameters:

UnitFinished(unitID, unitDefID, unitTeam)

Parameters:

UnitFromFactory(unitID, unitDefID, unitTeam, factID, factDefID, userOrders)

Parameters:

UnitReverseBuilt(unitID, unitDefID, unitTeam)

Parameters:

UnitConstructionDecayed(unitID, unitDefID, unitTeam, timeSinceLastBuild, iterationPeriod, part)

Parameters:

UnitDestroyed(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam, weaponDefID)

Parameters:

UnitTaken(unitID, unitDefID, oldTeam, newTeam)

Parameters:

Module `LuaHandle`