Development < Lua Scripting < LuaCallinReturn

Engine Source

If you can understand Lua code well and wish to get the most up to date info, you can refer to: cont/base/springcontent/LuaGadgets/actions.lua , cont/LuaUI/widgets.lua and
cont/base/springcontent/LuaGadgets/gadgets.lua
to see how widget/gadget call-ins are distributed, find call-in and widgetHandler function definitions, see how they are processed and what values should be returned from some call ins (are these the only files?)

What is a callin anyway?

Call-ins are calls from the engine, into the gadget or widget script. In other words, these functions are called when a particular “event” happens. Some call-in functions can return values to the engine.

Blocking events with return values

The call-in functions named AllowXXX can block their event by returning false.
For example AllowUnitTransfer()
return true = allow transfer
return false = deny transfer

Commands, general-purpose:

Initialize() --> none.</br> called when widget/gadget gets (re-)loaded.

Shutdown() --> none.

PlayerChanged --> (playerID). gadget/widget: Use this to check whether a player has become spectator for instance.

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

CommandNotify() --> "id, params, options", where id = the CommandID

KeyPress() --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

KeyRelease() --> "key"

MouseMove() --> "x, y, dx, dy, button"

MousePress() --> "x, y, button"
button parameter values: left - 1, middle - 2, right - 3

MouseRelease() --> "x, y, button"
Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same widget that returns true.

MouseWheel() --> "up, value"

IsAbove() --> "x, y" where x,y = screen coordinates.

GetTooltip() --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

AddConsoleLine() --> "msg, priority"

MapDrawCmd() --> "playerID, cmdType, px, py, pz, labeltext"

AllowCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

CommandFallback() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

CommandsChanged() --> unknown (none?)

AllowUnitCreation() --> "unitDefID, builderID, builderTeam, x, y, z, facing"

AllowUnitTransfer() --> "unitID, unitDefID, oldTeam, newTeam, capture"

AllowUnitBuildStep() --> "builderID, builderTeam, unitID, unitDefID, part"

AllowFeatureCreation() --> "featureDefID, teamID, x, y, z"

AllowFeatureBuildStep() --> unknown, please document.

AllowResourceLevel() --> "teamID, res, level"

AllowResourceTransfer() --> "teamID, res, level"</font>

Update() --> "dt"
gets called very often, even if the game is paused. dt is the time since the function was last called (???)

DefaultCommand() --> nothing (???)
can return an CMD to change cursor and command. example usage

AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID) -> allowFpsControl
return true allows fps mode, return false blocks it.

Unit-Specific:

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, attackerID, attackerDefID, attackerTeam" (prior to 94.0)

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" (as of 94.0)

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, attackerID, attackerDefID, attackerTeam"
Can overwrite the taken damage by returning a new number value.

As of 88.0 for both UnitDamaged and UnitPreDamaged:

    weaponDefID -1 --> debris collision
    weaponDefID -2 --> ground collision
    weaponDefID -3 --> object collision
    weaponDefID -4 --> fire damage
    weaponDefID -5 --> water damage
    weaponDefID -6 --> kill damage

UnitExperience() --> "unitID, unitDefID, unitTeam, experience, oldExperience"

Spring.SetExperienceGrade must be called first to determine how often it is called

UnitCreated() --> "unitID, unitDefID, teamID, builderID"

UnitFinished() --> "unitID, unitDefID, teamID"

UnitFromFactory() --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

UnitDestroyed() --> "unitID, unitDefID, teamID, attackerID, attackerDefID, attackerTeamID"

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam"

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam"

UnitIdle() --> "unitID, unitDefID, teamID"

UnitCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams"

UnitSeismicPing() --> "x, y, z, strength"

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

UnitLeftLos() --> "unitID, unitDefID, teamID"

UnitLoaded() --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

UnitUnloaded() --> "unitID, unitDefID, teamID, transportID"

UnitCloaked() --> "unitID, unitDefID, teamID"

UnitDecloaked)--> "unitID, unitDefID, teamID"

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"

Only called for unitDefIDs registered via Script.SetWatchUnit since 85.0

StockpileChanged() --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

UnitEnteredWater() --> "unitID, unitDefID, teamID"

UnitEnteredAir() --> "unitID, unitDefID, teamID"

UnitLeftWater() --> "unitID, unitDefID, teamID"

UnitLeftAir() --> "unitID, unitDefID, teamID"

ShieldPreDamaged() --> "proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile"

UnitUnitCollision(colliderID, collideeID) -- needs SetWatchUnit enabled for both parties

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID) New in version 83.0

Only called for weaponDefIDs registered via Script.SetWatchWeapon since 92.0

AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defaultPriority)

--> return "targetAllowed, targetPriority"

New in version 83.0, defaultPriority new in 89.0

Only called for weaponDefIDs registered via Script.SetWatchWeapon since 92.0

DrawShield(number unitID, number weaponID) --> boolean

true (<-?) skips Spring's own drawing of shield <weaponID> owned by unit <unitID>

maybe new in 86.0+

Feature-Specific:

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag"

UnitFeatureCollision(colliderID, collideeID, crushKilled) -- needs SetWatchUnit for first and SetWatchFeature for second party

Drawing:

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

• DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

• DrawWorldPreUnit() --> none.

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

• DrawWorld() --> none.

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

Each unit might also have a DrawUnit call, enabled here.

DrawUnit(unitID,DrawMode)
With enum DrawMode {
notDrawing = 0,
normalDraw = 1,
shadowDraw = 2,
reflectionDraw = 3,
refractionDraw = 4
};

DrawFeature(featureID, DrawMode)

DrawShield(unitID, weaponID, DrawMode)

DrawProjectile(projectileID, DrawMode)

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

Game Events:

GameID() --> "gameID" New in version 89.0

Explosion() --> "weaponID, px, py, pz, ownerID"

ShockFront() --> "power, dx, dy, dz"

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail.

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) New in 0.83.x

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() --> x,y,z, playerID

return true/false to allow/deny placing startposition marker

GameSetup() --> string "state", boolean "ready", table "playerStates"

return success, newReady

GamePaused() --> "playerID, paused" New in version 83.0

PlayerAdded() --> "playerID" New in version 83.0

PlayerRemoved() --> "playerID, reason" New in version 83.0

Projectiles:

ProjectileCreated() --> "proID, proOwnerID, weaponDefID" Only called for weapons with SetWatchWeapon enabled

ProjectileDestroyed() --> "proID" Only called for weapons with SetWatchWeapon enabled