View source for Lua Callins

= Lua Callins =
This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the [https://github.com/spring/spring/blob/ebb704e008f6ea645947d07be1cfcc272af0428f/doc/changelog.txt#L71 changelog].

Related Sourcecode :
[https://github.com/spring/spring/blob/d9b3927a528a876b9ab4042771e82b050267572a/rts/Lua/LuaHandle.cpp https://github.com/spring/spring/rts/Lua/LuaHandle.cpp]

For now, to use these addons in a widget, replace addon with widget and, for a gadget, replace addon with gadget. For example,
<code><pre>
    function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
        ...  
    end
</pre></code>

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.

<span style="color: maroon;">'''Attention:'''</span> 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 ==
{{LuaCallin
|name = Initialize
|info = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|info = Called when the addon or the game is shutdown.
}}


== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|args = type, id
|return = {{type|number}} cmdID
|info = 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 {{var|unitID}} or {{var|featureID}} respectively. 
}}

{{LuaCallin
|name = CommandNotify
|args = cmdID, cmdParams, cmdOptions
|return = {{type|bool}} removeCmd
|info = Called when a command is issued. Returning {{value|true}} deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = CommandsChanged
|args = None
|return = ?
|info = Called when the command descriptions changed, e.g. when selecting or deselecting a unit.
}}

{{LuaCallin
|name = WorldTooltip
|args = ttType, data1, data2, data3
|return = {{type|string}} newTooltip
|info = The parameters can be {{value|"unit"}}, {{var|unitID}}; {{value|"feature"}}, {{var|featureID}}; {{value|"ground"}}, {{var|posX}}, {{var|posY}}, {{var|posZ}} or {{value|"selection"}}.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|args = ???
|info = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|args = serverFrameNum
|info = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
}}

{{LuaCallin
|name = GameSetup
|args =  state, ready, playerStates
|return = {{type|bool}} success, {{type|bool}} newReady
|info = ???
}}

{{LuaCallin
|name = SunChanged
|args = ???
|info = ???
}}

{{LuaCallin
|name = AddConsoleLine
|args = msg, priority
|info = Called when text is entered into the console (e.g. Spring.Echo).
}}

{{LuaCallin
|name = RecvSkirmishAIMessage
|args = aiTeam, dataStr
|return = ???
|info = ???
}}

{{LuaCallin
|name = RecvFromSynced
|args = ...
|info = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|args = zip
|info = Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See [[Lua_SaveLoad#Save_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

{{LuaCallin
|name = LoadProgress
|args = message, replaceLastLine
|info = Only available to LuaIntro.
}}

{{LuaCallin
|name = GroupChanged
|args = groupID
|info = Called when a unit is added to or removed from a control group. Currently implemented for widgets only.
}}

{{LuaCallin
|name = ConfigureLayout
|args = ???
|return = ???
|info = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|args = x, y
|return = {{type|bool}} isAbove
|info = Called every Update. Must return {{value|true}} for {{name|Mouse*}} events and {{name|GetToolTip}} to be called.
}}

{{LuaCallin
|name = GetTooltip
|args = x, y
|return = {{type|string}} tooltip
|info = Called when {{name|IsAbove}} returns {{value|true}}.
}}

{{LuaCallin
|name = KeyPress
|args = key, mods, isRepeat
|return = {{type|bool}} becomeOwner
|info = Called repeatedly when a key is pressed down. If you want an action to occur only once check for {{var|1=isRepeat == {{value|false}}}}. The {{var|mods}} parameter is a {{type|table}}, with keys {{value|"alt"}}, {{value|"ctrl"}}, {{value|"meta"}} and {{value|"shift"}} each having a boolean value. Return {{value|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 [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{LuaCallin
|name = KeyRelease
|args = key
|return = {{type|bool}}
|info = Called when the key is released.
}}


{{LuaCallin
|name = TextInput
|args = utf8char
|info = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|args = ???
|info = ???
}}

{{LuaCallin
|name = MousePress
|args = x, y, button
|return = {{type|bool}} becomeMouseOwner
|info = Called when a mouse button is pressed. The {{var|button}} parameter supports up to 7 buttons. Must return {{value|true}} for {{name|MouseRelease}} and other functions to be called.
}}

{{LuaCallin
|name = MouseRelease
|args = x, y, button
|return = bool becomeMouseOwner
|info = Called when a mouse button is released. Please note that in order to have Spring call {{name|MouseRelease}}, you need to have a {{name|MousePress}} call-in in the same addon that returns {{value|true}}.
}}

{{LuaCallin
|name = MouseWheel
|args = up, value
|info = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}

{{LuaCallin
|name = MouseMove
|args = x, y, dx, dy, button
|info = Called when the mouse is moved. The {{var|dx}} and {{var|dy}} parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|args = playerID
|info = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|args = playerID
|info = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|args = playerID, reason
|info = Called whenever a player is removed from the game.
}}

=== Downloads ===

{{LuaCallin
|name = DownloadStarted
|args = id
|info = Called when a [[Pr-downloader]] download is started via [[Lua_VFS#Archives|VFS.DownloadArchive]].
}}

{{LuaCallin
|name = DownloadFinished
|args = id
|info = Called when a [[Pr-downloader]] download finishes successfully.
}}

{{LuaCallin
|name = DownloadFailed
|args = id, errorID
|info = Called when a [[Pr-downloader]] download fails to complete.
}}

{{LuaCallin
|name = DownloadProgress
|args = id, downloaded, total
|info = Called incrementally during a [[Pr-downloader]] download.
}}

=== Drawing ===
{{LuaCallin
|name = ViewResize
|args = viewSizeX, viewSizeY
|info = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|args = dt
|info = 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 | Lua OpenGL Api]] to draw graphics.
<br />
Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

{{LuaCallin
|name = DrawGenesis
|info = Doesn't render to screen! Use this callin to update textures, shaders, etc. Also available to LuaMenu.
}}

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

{{LuaCallin
|name = DrawWorldPreUnit
|info = Spring draws units, features, some water types, cloaked units, and the sun.
}}

{{LuaCallin
|name = DrawWorld
|info = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|info = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|info = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|info = ???
}}

{{LuaCallin
|name = DrawGroundPreForward
|info = Runs at the start of the forward pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPreDeferred
|info = Runs at the start of the deferred pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}


{{LuaCallin
|name = DrawGroundPostDeferred
|info = 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|{{name|DrawWorldPreUnit}}]]) via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]].
}}

{{LuaCallin
|name = DrawUnitsPostDeferred
|info = Runs at the end of the unit deferred pass to inform Lua code it should make use of the {{value|$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 [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawFeaturesPostDeferred
|info = Runs at the end of the feature deferred pass to inform Lua code it should make use of the {{value|$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 [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawScreen
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

{{LuaCallin
|name = DrawScreenEffects
|args = vsx, vsy
|info = Where {{var|vsx}}, {{var|vsy}} are screen coordinates.
}}

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{LuaCallin
|name = DrawLoadScreen
|info = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls {{var|drawMode}} can be one of the following, {{var|1=notDrawing = {{value|0}}}}, {{var|1=normalDraw = {{value|1}}}}, {{var|1=shadowDraw = {{value|2}}}}, {{var|1=reflectionDraw = {{value|3}}}}, {{var|1=refractionDraw = {{value|4}}}}, and finally {{var|1=gameDeferredDraw = {{value|5}}}} which was added in 102.0.

{{LuaCallin
|name = DrawUnit
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of units, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].	
}}

{{LuaCallin
|name = DrawFeature
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of features, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].	
}}

{{LuaCallin
|name = DrawShield
|args = unitID, weaponID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of [[Gamedev:WeaponDefs#Shield_(WeaponType)|shields]].
}}

{{LuaCallin
|name = DrawProjectile
|args = projectileID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of weapon (& other) projectiles.
}}

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|args = msg, player
|info = Called when a player issues a UI command e.g. types {{var|/foo}} or {{var|/luarules foo}}.
}}

=== Game ===

{{LuaCallin
|name = GameID
|args = gameID
|info = Called once to deliver the {{var|gameID}}. As of 101.0+ the string is encoded in hex.
}}

{{LuaCallin
|name = GamePaused
|info = Called when the game is paused.
}}

{{LuaCallin
|name = GameOver
|args = winningAllyTeams
|info = The parameter is a {{type|table}} list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}

{{LuaCallin
|name = GameFrame
|args = frame
|info = Called for every game simulation frame (30 per second). Starts at frame {{value|0}} in 101.0+ and {{value|1}} in previous versions.
}}

{{LuaCallin
|name = GamePreload
|info = Called before the 0 gameframe. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|args = teamID
|info = ???
}}

{{LuaCallin
|name = TeamDied
|args = teamID
|info = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}

=== Units ===
{{LuaCallin
|name = UnitCreated
|args = unitID, unitDefID, unitTeam, builderID
|info = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|args = unitID, unitDefID, unitTeam
|info = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|args = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|info = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitReverseBuilt
|args = unitID, unitDefID, unitTeam
|info = Called when a living unit becomes a nanoframe again.
}}

{{LuaCallin
|name = UnitGiven
|args = unitID, unitDefID, newTeam, oldTeam
|info = Called when a unit is transferred between teams. This is called after {{name|UnitTaken}} and in that moment unit is assigned to the '''newTeam'''.
}}

{{LuaCallin
|name = UnitTaken
|args = unitID, unitDefID, oldTeam, newTeam
|info = Called when a unit is transferred between teams. This is called before {{name|UnitGiven}} and in that moment unit is still assigned to the '''oldTeam'''.
}}

{{LuaCallin
|name = UnitDamaged
|args =  unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is damaged (after {{name|UnitPreDamaged}}).
}}

{{LuaCallin
|name = UnitDestroyed
|args = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is destroyed.
}}

{{LuaCallin
|name = RenderUnitDestroyed
|args = unitID, unitDefID, unitTeam
|info = Called just before a unit is invalid, after it finishes its death animation. {{new|101.0}}
}}

{{LuaCallin
|name = UnitStunned
|args =  unitID, unitDefID, unitTeam, stunned
|info = Called when a unit changes its stun status. {{new|99.0}}
}}

{{LuaCallin
|name = UnitUnitCollision
|args = colliderID, collideeID
|info = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}

{{LuaCallin
|name = UnitFeatureCollision
|args = colliderID, collideeID
|info = Called when a unit collides with a feature. The unit must be registered with [[Lua_System#Synced|Script.SetWatchUnit]] and the feature registered with [[Lua_System#Synced|Script.SetWatchFeature]].
}}

{{LuaCallin
|name = UnitCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
}}

{{LuaCallin
|name = UnitCmdDone
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|args = unitID, unitDefID, unitTeam, experience, oldExperience
|info = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{LuaCallin
|name = UnitIdle
|args = unitID, unitDefID, unitTeam
|info = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = StockpileChanged
|args = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|info = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}

{{LuaCallin
|name = UnitEnteredLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitSeismicPing
|args = x, y, z, strength, allyTeam, unitID, unitDefID
|info = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}

=== Features ===
{{LuaCallin
|name = FeatureCreated
|args = featureID, allyTeamID
|info = Called when a feature is created.
}}

{{LuaCallin
|name = FeatureDamaged
|args =  featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a feature is damaged.
}}

{{LuaCallin
|name = FeatureDestroyed
|args = featureID, allyTeamID
|info = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|args = ???
|info = ???
}}

=== Projectiles ===
The following Callins are only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].

{{LuaCallin
|name = ProjectileCreated
|args = proID, proOwnerID, weaponDefID
|info = Called when the projectile is created. Note that {{var|weaponDefID}} is missing if the projectile is spawned as part of a burst, but [[Lua_SyncedRead#Projectiles|Spring.GetProjectileDefID]] and [[Lua_SyncedRead#Projectiles|Spring.GetProjectileName]] still work in callin scope using {{var|proID}}.
}}

{{LuaCallin
|name = ProjectileDestroyed
|args = proID
|info = Called when the projectile is destroyed.
}}

== Synced Only ==
{{LuaCallin
|name = CommandFallback
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = {{type|bool}} used, {{type|bool}} finished
|info = Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns {{var|used}} as {{value|true}} the command is dropped, if an addon returns {{value|true}}, {{value|true}} the command is removed because it's done, with {{value|true}}, {{value|false}} it's kept in the queue and {{name|CommandFallback}} gets called again on the next slowupdate.
}}

{{LuaCallin
|name = AllowCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = {{type|bool}} allow
|info = 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.
}}

{{LuaCallin
|name = AllowUnitCreation
|args = unitDefID, builderID, builderTeam, x, y, z, facing
|return = {{type|bool}} allow
|info = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|args = unitID, unitDefID, oldTeam, newTeam, capture
|return = {{type|bool}} allow
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowUnitBuildStep
|args = builderID, builderTeam, unitID, unitDefID, part
|return = {{type|bool}} allow
|info = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

{{LuaCallin
|name = AllowFeatureCreation
|args = featureDefID, teamID, x, y, z
|return = {{type|bool}} allow
|info = Called just before feature is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowFeatureBuildStep
|args = builderID, builderTeam, featureID, featureDefID, part
|return = {{type|bool}} allow
|info = Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.
}}

{{LuaCallin
|name = AllowResourceLevel
|args = teamID, res, level
|return = {{type|bool}} allow
|info = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
}}

{{LuaCallin
|name = AllowResourceTransfer
|args = oldTeamID, newTeamID, res, amount
|return = {{type|bool}} allow
|info = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|args = playerID, teamID, readyState, clampedX, clampedY, clampedZ, rawX, rawY, rawZ
|return = {{type|bool}} allow
|info = {{var|clamped{X,Y,Z}}} are the coordinates clamped into start-boxes, {{var|raw}} is where player tried to place their marker. The {{var|readyState}} can be any one of 
* {{value|0}} - player picked a position, 
* {{value|1}} - player clicked ready, 
* {{value|2}} - player pressed ready OR  the game was force-started (player did not click ready, but is now forcibly readied) or 
* {{value|3}} - the player failed to load. 
* {{new|95.0}} 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 {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

{{LuaCallin
|name = AllowDirectUnitControl
|args = unitID, unitDefID, unitTeam, playerID
|return = {{type|bool}} allow
|info = Determines if this unit can be controlled directly in FPS view.
}}

{{LuaCallin
|name = AllowWeaponTargetCheck
|args = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = {{type|bool}} allowCheck, {{type|bool}} ignoreCheck
|info = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag. The {{var|ignoreCheck}} return value was added in 99.0 to allow ignoring the callin i.e. running normal engine check for this weapon.
}}

{{LuaCallin
|name = AllowWeaponTarget
|args = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = {{type|bool}} allowed, {{type|number}} newPriority
|info = 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 {{var|defPriority}}). Lower priority targets are targeted first.
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|args = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = {{type|bool}} allowed
|info = Controls blocking of a specific intercept target from being considered during an {{xtaglink|Gamedev:WeaponDefs|interceptor}} weapon's periodic auto-targeting sweep. Only called for {{var|weaponDefIDs}} registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

{{LuaCallin
|name = AllowBuilderHoldFire
|args = unitID, unitDefID, action
|return = {{type|bool}} actionAllowed
|info = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}}   Called when a construction unit wants to "use his nano beams".<br>{{var|action}} is one of following:
* {{value|-1}} Build
* {{value|CMD.REPAIR}} Repair
* {{value|CMD.RECLAIM}} Reclaim
* {{value|CMD.RESTORE}} Restore
* {{value|CMD.RESURRECT}} Resurrect
* {{value|CMD.CAPTURE}} Capture
}}

{{LuaCallin
|name = Explosion
|args = weaponDefID, px, py, pz, AttackerID, ProjectileID
|return = {{type|bool}} noGfx
|info = Called when an explosion occurs. If it returns {{value|true}} then no graphical effects are drawn by the engine for this explosion.
}}

{{LuaCallin
|name = TerraformComplete
|args = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = {{type|bool}} stop
|info = Called when pre-building terrain levelling terraforms are completed (c.f. {{xtaglink|Gamedev:UnitDefs|levelGround}}). If the return value is {{value|true}} the current build order is terminated.
}}

{{LuaCallin
|name = MoveCtrlNotify
|args = unitID, unitDefID, unitTeam, data
|return = {{type|bool}} moveCtrlComplete
|info = Enable both [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetCollideStop]] and [[Lua_MoveCtrl#Options|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 {{value|1}} ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled ({{value|false}}) or return to engine controlled movement ({{value|true}}).
}}

{{LuaCallin
|name = RecvLuaMsg
|args = msg, playerID
|info = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}

{{LuaCallin
|name = Load
|args = zip
|info = Called after {{name|GamePreload}} and before {{name|GameStart}}. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

=== Damage Controllers ===
For the following callins, in addition to being a regular weapon, {{var|weaponDefID}} may be one of the following:
* <code>-1</code> - debris collision, also default of [[Lua_SyncedCtrl#Unit_Control|Spring.AddUnitDamage]]
* <code>-2</code> - ground collision
* <code>-3</code> - object collision
* <code>-4</code> - fire damage
* <code>-5</code> - water damage
* <code>-6</code> - kill damage
* <code>-7</code> - crush damage

{{LuaCallin
|name = UnitPreDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the unit, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

{{LuaCallin
|name = ShieldPreDamaged
|I recommend looking up the CallIns in Sourcecode, because the Lua-Documentation, generated from the lua handle of them is seriously flawed and not regenerated.
|Lua-Handler documented from version
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynced.h#L106
|Actual CallIn: 
|args = proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|return = {{type|bool}} handleCollision
|info = Called before any engine shield-vs-projectile logic executes. If the return value is {{value|true}} the gadget handles the collision event and the engine does not remove the projectile. If the weapon is a hitscan type ([[Gamedev:WeaponDefs#Tag:weaponType|BeamLaser]] or [[Gamedev:WeaponDefs#Tag:weaponType|LightningCanon]]) then {{var|proID}} is {{value|nil}} and {{var|beamEmitterWeaponNum}} and {{var|beamEmitterUnitID}} are populated instead. The start and hit position arguments are provided from 104.0 onwards.
}}

{{LuaCallin
|name = FeaturePreDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the feature, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

[[Category: Lua]]