Lua Callins

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

For now, to use these addons in a widget, replace addon with widget and, for a gadget, replace addon with 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.

Common

Template:Prefix Template:Name Template:CodeStyle()

Called when the addon is (re)loaded.

Template:Prefix Template:Name Template:CodeStyle()

Called when the addon or the game is shutdown.

Unsynced Only

Template:Prefix Template:Name Template:CodeStyle(type, id)
return: Template:CodeStyleTemplate:Type cmdID

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 Template:CodeStyleunitID or Template:CodeStylefeatureID respectively.

Template:Prefix Template:Name Template:CodeStyle(cmdID, cmdParams, cmdOptions)
return: Template:CodeStyleTemplate:Type removeCmd

Called when a command is issued. Returning Template:Value deletes the command and does not send it through the network.

Template:Prefix Template:Name Template:CodeStyle(None)
return: Template:CodeStyle?

Called when the command descriptions changed, e.g. when selecting or deselecting a unit.

Template:Prefix Template:Name Template:CodeStyle(ttType, data1, data2, data3)
return: Template:CodeStyleTemplate:Type newTooltip

The parameters can be Template:Value, Template:CodeStyleunitID; Template:Value, Template:CodeStylefeatureID; Template:Value, Template:CodeStyleposX, Template:CodeStyleposY, Template:CodeStyleposZ or Template:Value.

Template:Prefix Template:Name Template:CodeStyle(???)

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

Template:Prefix Template:Name Template:CodeStyle(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.

Template:Prefix Template:Name Template:CodeStyle(state, ready, playerStates)
return: Template:CodeStyleTemplate:Type success, Template:Type newReady

???

Template:Prefix Template:Name Template:CodeStyle(???)

???

Template:Prefix Template:Name Template:CodeStyle(msg, priority)

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

Template:Prefix Template:Name Template:CodeStyle(aiTeam, dataStr)
return: Template:CodeStyle???

???

Template:Prefix Template:Name Template:CodeStyle(...)

Receives data sent via SendToUnsynced callout.

Template:Prefix Template:Name Template:CodeStyle(zip)

Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See Lua_SaveLoad.

Template:Prefix Template:Name Template:CodeStyle(message, replaceLastLine)

Only available to LuaIntro.

Template:Prefix Template:Name Template:CodeStyle(groupID)

Called when a unit is added to or removed from a control group. Currently implemented for widgets only.

Template:Prefix Template:Name Template:CodeStyle(???)
return: Template:CodeStyle???

???

Input

Template:Prefix Template:Name Template:CodeStyle(x, y)
return: Template:CodeStyleTemplate:Type isAbove

Called every Update. Must return Template:Value for Template:Name events and Template:Name to be called.

Template:Prefix Template:Name Template:CodeStyle(x, y)
return: Template:CodeStyleTemplate:Type tooltip

Called when Template:Name returns Template:Value.

Template:Prefix Template:Name Template:CodeStyle(key, mods, isRepeat)
return: Template:CodeStyleTemplate:Type becomeOwner

Called repeatedly when a key is pressed down. If you want an action to occur only once check for Template:CodeStyleisRepeat == Template:Value. The Template:CodeStylemods parameter is a Template:Type, with keys Template:Value, Template:Value, Template:Value and Template:Value each having a boolean value. Return Template:Value 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.

Template:Prefix Template:Name Template:CodeStyle(key)
return: Template:CodeStyleTemplate:Type

Called when the key is released.

Template:Prefix Template:Name Template:CodeStyle(utf8char)

Called whenever a key press results in text input. Introduced in 97.0.

Template:Prefix Template:Name Template:CodeStyle(???)

???

Template:Prefix Template:Name Template:CodeStyle(x, y, button)
return: Template:CodeStyleTemplate:Type becomeMouseOwner

Called when a mouse button is pressed. The Template:CodeStylebutton parameter supports up to 7 buttons. Must return Template:Value for Template:Name and other functions to be called.

Template:Prefix Template:Name Template:CodeStyle(x, y, button)
return: Template:CodeStylebool becomeMouseOwner

Called when a mouse button is released. Please note that in order to have Spring call Template:Name, you need to have a Template:Name call-in in the same addon that returns Template:Value.

Template:Prefix Template:Name Template:CodeStyle(up, value)

Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.

Template:Prefix Template:Name Template:CodeStyle(x, y, dx, dy, button)

Called when the mouse is moved. The Template:CodeStyledx and Template:CodeStyledy parameters indicate the distance travelled, whereas the first two indicate the final position.

Players

Template:Prefix Template:Name Template:CodeStyle(playerID)

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

Template:Prefix Template:Name Template:CodeStyle(playerID)

Called whenever a new player joins the game.

Template:Prefix Template:Name Template:CodeStyle(playerID, reason)

Called whenever a player is removed from the game.

Downloads

Template:Prefix Template:Name Template:CodeStyle(id)

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

Template:Prefix Template:Name Template:CodeStyle(id)

Called when a Pr-downloader download finishes successfully.

Template:Prefix Template:Name Template:CodeStyle(id, errorID)

Called when a Pr-downloader download fails to complete.

Template:Prefix Template:Name Template:CodeStyle(id, downloaded, total)

Called incrementally during a Pr-downloader download.

Drawing

Template:Prefix Template:Name Template:CodeStyle(viewSizeX, viewSizeY)

Called whenever the window is resized.

Template:Prefix Template:Name Template:CodeStyle(dt)

Called for every draw frame (including when the game is paused) and at least once per sim frame except when catching up. The parameter is the time since the last update.

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.

Template:Prefix Template:Name Template:CodeStyle()

Doesn't render to screen! Use this callin to update textures, shaders, etc. Also available to LuaMenu.

Template:Prefix Template:Name Template:CodeStyle()

??? Template:New

Template:Prefix Template:Name Template:CodeStyle()

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

Template:Prefix Template:Name Template:CodeStyle()

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

Template:Prefix Template:Name Template:CodeStyle()

???

Template:Prefix Template:Name Template:CodeStyle()

???

Template:Prefix Template:Name Template:CodeStyle()

???

Template:Prefix Template:Name Template:CodeStyle()

Runs at the start of the forward pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|Template:Name]] (convenient for setting uniforms).

Template:Prefix Template:Name Template:CodeStyle()

Runs at the start of the deferred pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|Template:Name]] (convenient for setting uniforms).

Template:Prefix Template:Name Template:CodeStyle()

This runs at the end of its respective deferred pass and allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and [[#API:DrawWorldPreUnit|Template:Name]]) via [[Lua_OpenGL_Api#Textures|Template:Name]].

Template:Prefix Template:Name Template:CodeStyle()

Runs at the end of the unit deferred pass to inform Lua code it should make use of the Template:Value textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|Template:Name]] via [[Lua_OpenGL_Api#Textures|Template:Name]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

Template:Prefix Template:Name Template:CodeStyle()

Runs at the end of the feature deferred pass to inform Lua code it should make use of the Template:Value textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|Template:Name]] via [[Lua_OpenGL_Api#Textures|Template:Name]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.

Template:Prefix Template:Name Template:CodeStyle(vsx, vsy)

??? Also available to LuaMenu.

Template:Prefix Template:Name Template:CodeStyle(vsx, vsy)

Where Template:CodeStylevsx, Template:CodeStylevsy are screen coordinates.

Template:Prefix Template:Name Template:CodeStyle(vsx, vsy)

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

Template:Prefix Template:Name Template:CodeStyle()

Template:New Only available to LuaIntro, draws custom load screens.

Template:Prefix Template:Name Template:CodeStyle(sx, sy)

Where Template:CodeStylesx, Template:CodeStylesy are values relative to the minimap's position and scale.

Template:Prefix Template:Name Template:CodeStyle(sx, sy)

Where Template:CodeStylesx, Template:CodeStylesy are values relative to the minimap's position and scale.

Custom Object Rendering

For the following calls Template:CodeStyledrawMode can be one of the following, Template:CodeStylenotDrawing = Template:Value, Template:CodeStylenormalDraw = Template:Value, Template:CodeStyleshadowDraw = Template:Value, Template:CodeStylereflectionDraw = Template:Value, Template:CodeStylerefractionDraw = Template:Value, and finally Template:CodeStylegameDeferredDraw = Template:Value which was added in 102.0.

Template:Prefix Template:Name Template:CodeStyle(unitID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of units, enabled here.

Template:Prefix Template:Name Template:CodeStyle(unitID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of features, enabled here.

Template:Prefix Template:Name Template:CodeStyle(unitID, weaponID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of shields.

Template:Prefix Template:Name Template:CodeStyle(projectileID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of weapon (& other) projectiles.

Unsynced Menu Only

Template:Prefix Template:Name Template:CodeStyle()
return: Template:CodeStyleTemplate:Type allowDraw

Enables Draw{Genesis,Screen,ScreenPost} callins if Template:Value is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.

Template:Prefix Template:Name Template:CodeStyle()

Called whenever LuaMenu is on with no game loaded.

Template:Prefix Template:Name Template:CodeStyle()

Called whenever LuaMenu is on with a game loaded.

Synced - Unsynced Shared

Template:Prefix Template:Name Template:CodeStyle(msg, player)

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

Game

Template:Prefix Template:Name Template:CodeStyle(gameID)

Called once to deliver the Template:CodeStylegameID. As of 101.0+ the string is encoded in hex.

Template:Prefix Template:Name Template:CodeStyle()

Called when the game is paused.

Template:Prefix Template:Name Template:CodeStyle(winningAllyTeams)

The parameter is a Template:Type list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).

Template:Prefix Template:Name Template:CodeStyle(frame)

Called for every game simulation frame (30 per second). Starts at frame Template:Value in 101.0+ and Template:Value in previous versions.

Template:Prefix Template:Name Template:CodeStyle()

Called before the 0 gameframe. From 104.0 onwards, will not be called when a saved game is loaded.

Template:Prefix Template:Name Template:CodeStyle()

Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.

Teams

Template:Prefix Template:Name Template:CodeStyle(teamID)

???

Template:Prefix Template:Name Template:CodeStyle(teamID)

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

Units

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, builderID)

Called at the moment the unit is created.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam)

Called at the moment the unit is completed.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, factID, factDefID, userOrders)

Called when a factory finishes construction of a unit.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam)

Called when a living unit becomes a nanoframe again.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, newTeam, oldTeam)

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

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, oldTeam, newTeam)

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

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Called when a unit is damaged (after Template:Name).

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam)

Called when a unit is destroyed.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam)

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

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, stunned)

Called when a unit changes its stun status. Template:New

Template:Prefix Template:Name Template:CodeStyle(colliderID, collideeID)

Called when two units collide. Both units must be registered with Script.SetWatchUnit.

Template:Prefix Template:Name Template:CodeStyle(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.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag)

Called after when a unit accepts a command, after Template:Name returns Template:Value.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag)

Called when a unit completes a command.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, transportID, transportTeam)

Called when a unit is loaded by a transport.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, transportID, transportTeam)

Called when a unit is unloaded by a transport.

Template:Prefix Template:Name Template:CodeStyle(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 in 104.0+.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam)

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

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam)

Called when a unit cloaks.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam)

Called when a unit decloaks.

Template:Prefix Template:Name Template:CodeStyle(???)

??? Not implemented in base handler

Template:Prefix Template:Name Template:CodeStyle(???)

??? Not implemented in base handler

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount)

Called when a units stockpile of weapons increases or decreases. See Template:Xtaglink.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters LOS of an allyteam.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit leaves LOS of an allyteam.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters radar of an allyteam.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit leaves radar of an allyteam.

Template:Prefix Template:Name Template:CodeStyle(???)

??? Not implemented by base handler

Template:Prefix Template:Name Template:CodeStyle(???)

??? Not implemented by base handler

Template:Prefix Template:Name Template:CodeStyle(???)

??? Not implemented by base handler

Template:Prefix Template:Name Template:CodeStyle(???)

??? Not implemented by base handler

Template:Prefix Template:Name Template:CodeStyle(x, y, z, strength, allyTeam, unitID, unitDefID)

Called when a unit emits a seismic ping. See Template:Xtaglink.

Features

Template:Prefix Template:Name Template:CodeStyle(featureID, allyTeamID)

Called when a feature is created.

Template:Prefix Template:Name Template:CodeStyle(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Called when a feature is damaged.

Template:Prefix Template:Name Template:CodeStyle(featureID, allyTeamID)

Called when a feature is destroyed.

Template:Prefix Template:Name Template:CodeStyle(???)

???

Projectiles

The following Callins are only called for weaponDefIDs registered via Script.SetWatchWeapon.

Template:Prefix Template:Name Template:CodeStyle(proID, proOwnerID, weaponDefID)

Called when the projectile is created. Note that Template:CodeStyleweaponDefID is missing if the projectile is spawned as part of a burst, but Spring.GetProjectileDefID and Spring.GetProjectileName still work in callin scope using Template:CodeStyleproID.

Template:Prefix Template:Name Template:CodeStyle(proID)

Called when the projectile is destroyed.

Synced Only

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag)
return: Template:CodeStyleTemplate:Type used, Template:Type finished

Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns Template:CodeStyleused as Template:Value the command is dropped, if an addon returns Template:Value, Template:Value the command is removed because it's done, with Template:Value, Template:Value it's kept in the queue and Template:Name gets called again on the next slowupdate.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced)
return: Template:CodeStyleTemplate:Type allow

Called when the command is given, before the unit's queue is altered. The return value is whether it should be let into the queue. The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.

Template:Prefix Template:Name Template:CodeStyle(unitDefID, builderID, builderTeam, x, y, z, facing)
return: Template:CodeStyleTemplate:Type allow

Called just before unit is created, the boolean return value determines whether or not the creation is permitted.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, oldTeam, newTeam, capture)
return: Template:CodeStyleTemplate:Type allow

Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.

Template:Prefix Template:Name Template:CodeStyle(builderID, builderTeam, unitID, unitDefID, part)
return: Template:CodeStyleTemplate:Type allow

Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.

Template:Prefix Template:Name Template:CodeStyle(featureDefID, teamID, x, y, z)
return: Template:CodeStyleTemplate:Type allow

Called just before feature is created, the boolean return value determines whether or not the creation is permitted.

Template:Prefix Template:Name Template:CodeStyle(builderID, builderTeam, featureID, featureDefID, part)
return: Template:CodeStyleTemplate:Type allow

Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.

Template:Prefix Template:Name Template:CodeStyle(teamID, res, level)
return: Template:CodeStyleTemplate:Type allow

Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.

Template:Prefix Template:Name Template:CodeStyle(oldTeamID, newTeamID, res, amount)
return: Template:CodeStyleTemplate:Type allow

Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.

Template:Prefix Template:Name Template:CodeStyle(playerID, teamID, readyState, clampedX, clampedY, clampedZ, rawX, rawY, rawZ)
return: Template:CodeStyleTemplate:Type allow

Template:CodeStyleclamped{X,Y,Z} are the coordinates clamped into start-boxes, Template:CodeStyleraw is where player tried to place their marker. The Template:CodeStylereadyState can be any one of

Template:Value - player picked a position,
Template:Value - player clicked ready,
Template:Value - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
Template:Value - the player failed to load.
Template:New the default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.

NB: The order of the parameters changed with the addition of Template:CodeStyleteamID in 104.0. Previouly it was: Template:CodeStyleclampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, playerID)
return: Template:CodeStyleTemplate:Type allow

Determines if this unit can be controlled directly in FPS view.

Template:Prefix Template:Name Template:CodeStyle(attackerID, attackerWeaponNum, attackerWeaponDefID)
return: Template:CodeStyleTemplate:Type allowCheck, Template:Type ignoreCheck

Determines if this weapon can automatically generate targets itself. See also Template:Xtaglink weaponDef tag. The Template:CodeStyleignoreCheck return value was added in 99.0 to allow ignoring the callin i.e. running normal engine check for this weapon.

Template:Prefix Template:Name Template:CodeStyle(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)
return: Template:CodeStyleTemplate:Type allowed, Template:Type newPriority

Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value is the new priority for this target (if you don't want to change it, return Template:CodeStyledefPriority). Lower priority targets are targeted first.

Template:Prefix Template:Name Template:CodeStyle(interceptorUnitID, interceptorWeaponID, targetProjectileID)
return: Template:CodeStyleTemplate:Type allowed

Controls blocking of a specific intercept target from being considered during an Template:Xtaglink weapon's periodic auto-targeting sweep. Only called for Template:CodeStyleweaponDefIDs registered via Script.SetWatchWeapon.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, action)
return: Template:CodeStyleTemplate:Type actionAllowed

Template:New Template:Sourcelinkhash Called when a construction unit wants to "use his nano beams".
Template:CodeStyleaction is one of following:

Template:Value Build
Template:Value Repair
Template:Value Reclaim
Template:Value Restore
Template:Value Resurrect
Template:Value Capture

Template:Prefix Template:Name Template:CodeStyle(weaponDefID, px, py, pz, AttackerID, ProjectileID)
return: Template:CodeStyleTemplate:Type noGfx

Called when an explosion occurs. If it returns Template:Value then no graphical effects are drawn by the engine for this explosion.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam)
return: Template:CodeStyleTemplate:Type stop

Called when pre-building terrain levelling terraforms are completed (c.f. Template:Xtaglink). If the return value is Template:Value the current build order is terminated.

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, data)
return: Template:CodeStyleTemplate:Type moveCtrlComplete

Enable both Spring.MoveCtrl.SetCollideStop and Spring.MoveCtrl.SetTrackGround to enable this call-in, data was supposed to indicate the type of notification but currently never has a value other than Template:Value ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled (Template:Value) or return to engine controlled movement (Template:Value).

Template:Prefix Template:Name Template:CodeStyle(msg, playerID)

Receives messages from unsynced sent via Spring.SendLuaRulesMsg.

Template:Prefix Template:Name Template:CodeStyle(zip)

Called after Template:Name and before Template:Name. See Lua_SaveLoad.

Damage Controllers

For the following callins, in addition to being a regular weapon, Template:CodeStyleweaponDefID may be one of the following:

-1 - debris collision, also default of Spring.AddUnitDamage
-2 - ground collision
-3 - object collision
-4 - fire damage
-5 - water damage
-6 - kill damage
-7 - crush damage

Template:Prefix Template:Name Template:CodeStyle(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)
return: Template:CodeStyleTemplate:Type newDamage, Template:Type impulseMult

Called before damage is applied to the unit, allows fine control over how much damage and impulse is applied.

Template:Prefix Template:Name Template:CodeStyle(proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ)
return: Template:CodeStyleTemplate:Type handleCollision

Called before any engine shield-vs-projectile logic executes. If the return value is Template:Value the gadget handles the collision event and the engine does not remove the projectile. If the weapon is a hitscan type (BeamLaser or LightningCanon) then Template:CodeStyleproID is Template:Value and Template:CodeStylebeamEmitterWeaponNum and Template:CodeStylebeamEmitterUnitID are populated instead. The start and hit position arguments are provided from 104.0 onwards.

Template:Prefix Template:Name Template:CodeStyle(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)
return: Template:CodeStyleTemplate:Type newDamage, Template:Type impulseMult

Called before damage is applied to the feature, allows fine control over how much damage and impulse is applied.

Lua Callins

Contents

Lua Callins

Common

Unsynced Only

Input

Players

Downloads

Drawing

Draw* Functions

Custom Object Rendering

Unsynced Menu Only

Synced - Unsynced Shared

Game

Teams

Units

Features

Projectiles

Synced Only

Damage Controllers

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools