Lua:Callins: Difference between revisions

From Spring
Jump to navigationJump to search
← Older editNewer edit →
Flozi (talk | contribs)
0 edits
→Synced Only: templates
Flozi (talk | contribs)
0 edits
tweak to new API named params
Line 14: Line 14:
{{LuaCallin
{{LuaCallin
|name = Initialize
|name = Initialize
|description = Called when the addon is (re)loaded.
|info = Called when the addon is (re)loaded.
}}
}}


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


Line 27: Line 27:
{{LuaCallin
{{LuaCallin
|name = DefaultCommand
|name = DefaultCommand
|params = type, id
|args = type, id
|return = {{type|number}} cmdID
|return = {{type|number}} cmdID
|description = 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.  
|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
{{LuaCallin
|name = CommandNotify
|name = CommandNotify
|params = cmdID, cmdParams, cmdOptions
|args = cmdID, cmdParams, cmdOptions
|return = {{type|bool}} removeCmd
|return = {{type|bool}} removeCmd
|description = Called when a command is issued. Returning {{value|true}} deletes the command and does not send it through the network.
|info = Called when a command is issued. Returning {{value|true}} deletes the command and does not send it through the network.
}}
}}


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


{{LuaCallin
{{LuaCallin
|name = WorldTooltip
|name = WorldTooltip
|params = ttType, data1, data2, data3
|args = ttType, data1, data2, data3
|return = {{type|string}} newTooltip
|return = {{type|string}} newTooltip
|description = The parameters can be {{value|"unit"}}, {{var|unitID}}; {{value|"feature"}}, {{var|featureID}}; {{value|"ground"}}, {{var|posX}}, {{var|posY}}, {{var|posZ}} or {{value|"selection"}}.
|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
{{LuaCallin
|name = UnsyncedHeightMapUpdate
|name = UnsyncedHeightMapUpdate
|params = ???
|args = ???
|description = Called when the unsynced copy of the height-map is altered.
|info = Called when the unsynced copy of the height-map is altered.
}}
}}


{{LuaCallin
{{LuaCallin
|name = GameProgress
|name = GameProgress
|params = serverFrameNum
|args = serverFrameNum
|description = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
|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
{{LuaCallin
|name = GameSetup
|name = GameSetup
|params =  state, ready, playerStates
|args =  state, ready, playerStates
|return = {{type|bool}} success, {{type|bool}} newReady
|return = {{type|bool}} success, {{type|bool}} newReady
|description = ???
|info = ???
}}
}}


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


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


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


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


{{LuaCallin
{{LuaCallin
|name = Save
|name = Save
|params = zip
|args = zip
|description = 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]].
|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
{{LuaCallin
|name = LoadProgress
|name = LoadProgress
|params = message, replaceLastLine
|args = message, replaceLastLine
|description = Only available to LuaIntro.
|info = Only available to LuaIntro.
}}
}}


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


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


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


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


{{LuaCallin
{{LuaCallin
|name = KeyPress
|name = KeyPress
|params = key, mods, isRepeat
|args = key, mods, isRepeat
|return = {{type|bool}} becomeOwner
|return = {{type|bool}} becomeOwner
|description = 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.
|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.
}}
}}


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


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


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


{{LuaCallin
{{LuaCallin
|name = MousePress
|name = MousePress
|params = x, y, button
|args = x, y, button
|return = {{type|bool}} becomeMouseOwner
|return = {{type|bool}} becomeMouseOwner
|description = 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.
|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
{{LuaCallin
|name = MouseRelease
|name = MouseRelease
|params = x, y, button
|args = x, y, button
|return = bool becomeMouseOwner
|return = bool becomeMouseOwner
|description = 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}}.
|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
{{LuaCallin
|name = MouseWheel
|name = MouseWheel
|params = up, value
|args = up, value
|description = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
|info = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}
}}


{{LuaCallin
{{LuaCallin
|name = MouseMove
|name = MouseMove
|params = x, y, dx, dy, button
|args = x, y, dx, dy, button
|description = 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.
|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.
}}
}}


Line 193: Line 193:
{{LuaCallin
{{LuaCallin
|name = PlayerChanged
|name = PlayerChanged
|params = playerID
|args = playerID
|description = Called whenever a player's status changes e.g. becoming a spectator.
|info = Called whenever a player's status changes e.g. becoming a spectator.
}}
}}


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


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


Line 213: Line 213:
{{LuaCallin
{{LuaCallin
|name = ViewResize
|name = ViewResize
|params = viewSizeX, viewSizeY
|args = viewSizeX, viewSizeY
|description = Called whenever the window is resized.
|info = Called whenever the window is resized.
}}
}}


{{LuaCallin
{{LuaCallin
|name = Update
|name = Update
|params = dt
|args = dt
|description = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}
|info = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}


Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.
Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.
Line 226: Line 226:
{{LuaCallin
{{LuaCallin
|name = DrawGenesis
|name = DrawGenesis
|description = Doesn't render to screen! Use this callin to update textures, shaders, etc.
|info = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}
}}


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


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


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


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


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


{{LuaCallin
{{LuaCallin
|name = DrawScreen
|name = DrawScreen
|description = ???
|info = ???
}}
}}


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


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


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


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


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


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


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


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


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


Line 325: Line 325:
{{LuaCallin
{{LuaCallin
|name = GameID
|name = GameID
|params = gameID
|args = gameID
|description = Called once to deliver the {{var|gameID}}.
|info = Called once to deliver the {{var|gameID}}.
}}
}}


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


{{LuaCallin
{{LuaCallin
|name = GameOver
|name = GameOver
|params = winningAllyTeams
|args = winningAllyTeams
|description = The parameter is a {{type|table}} list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
|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
{{LuaCallin
|name = GameFrame
|name = GameFrame
|params = frame
|args = frame
|description = Called for every game simulation frame (30 per second).
|info = Called for every game simulation frame (30 per second).
}}
}}


{{LuaCallin
{{LuaCallin
|name = GamePreload
|name = GamePreload
|description = Called before the 0 gameframe.
|info = Called before the 0 gameframe.
}}
}}


{{LuaCallin
{{LuaCallin
|name = GameStart
|name = GameStart
|description = Called upon the start of the game.
|info = Called upon the start of the game.
}}
}}


Line 359: Line 359:
{{LuaCallin
{{LuaCallin
|name = TeamChanged
|name = TeamChanged
|params = teamID
|args = teamID
|description = ???
|info = ???
}}
}}


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


Line 372: Line 372:
{{LuaCallin
{{LuaCallin
|name = UnitCreated
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|args = unitID, unitDefID, unitTeam, builderID
|description = Called at the moment the unit is created.
|info = Called at the moment the unit is created.
}}
}}


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


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


{{LuaCallin
{{LuaCallin
|name = UnitGiven
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|args = unitID, unitDefID, newTeam, oldTeam
|description = Called when a unit is transferred between teams.
|info = Called when a unit is transferred between teams.
}}
}}


{{LuaCallin
{{LuaCallin
|name = UnitTaken
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|args = unitID, unitDefID, oldTeam, newTeam
|description = Called when a unit is transferred between teams.
|info = Called when a unit is transferred between teams.
}}
}}


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


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


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


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


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


{{LuaCallin
{{LuaCallin
|name = UnitFeatureCollision
|name = UnitFeatureCollision
|params = colliderID, collideeID
|args = colliderID, collideeID
|description = 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]].
|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
{{LuaCallin
|name = UnitCommand
|name = UnitCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|description = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
|info = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
}}
}}


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


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


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


{{LuaCallin
{{LuaCallin
|name = UnitExperience
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|args = unitID, unitDefID, unitTeam, experience, oldExperience
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
|info = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}
}}


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


Line 559: Line 559:
{{LuaCallin
{{LuaCallin
|name = FeatureCreated
|name = FeatureCreated
|params = featureID, allyTeamID
|args = featureID, allyTeamID
|description = Called when a feature is created.
|info = Called when a feature is created.
}}
}}


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


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


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


Line 586: Line 586:
{{LuaCallin
{{LuaCallin
|name = ProjectileCreated
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|args = proID, proOwnerID, weaponDefID
|description = 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}}.
|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
{{LuaCallin
|name = ProjectileDestroyed
|name = ProjectileDestroyed
|params = proID
|args = proID
|description = Called when the projectile is destroyed.
|info = Called when the projectile is destroyed.
}}
}}


Line 599: Line 599:
{{LuaCallin
{{LuaCallin
|name = CommandFallback
|name = CommandFallback
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = {{type|bool}} used, {{type|bool}} finished
|return = {{type|bool}} used, {{type|bool}} finished
|description = 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.
|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
{{LuaCallin
|name = AllowCommand
|name = AllowCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = 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.
|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
{{LuaCallin
|name = AllowUnitCreation
|name = AllowUnitCreation
|params = unitDefID, builderID, builderTeam, x, y, z, facing
|args = unitDefID, builderID, builderTeam, x, y, z, facing
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
|info = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}
}}


{{LuaCallin
{{LuaCallin
|name = AllowUnitTransfer
|name = AllowUnitTransfer
|params = unitID, unitDefID, oldTeam, newTeam, capture
|args = unitID, unitDefID, oldTeam, newTeam, capture
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
|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
{{LuaCallin
|name = AllowUnitBuildStep
|name = AllowUnitBuildStep
|params = builderID, builderTeam, unitID, unitDefID, part
|args = builderID, builderTeam, unitID, unitDefID, part
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
|info = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}
}}


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


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


{{LuaCallin
{{LuaCallin
|name = AllowResourceLevel
|name = AllowResourceLevel
|params = teamID, res, level
|args = teamID, res, level
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
|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
{{LuaCallin
|name = AllowResourceTransfer
|name = AllowResourceTransfer
|params = oldTeamID, newTeamID, res, amount
|args = oldTeamID, newTeamID, res, amount
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
|info = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}
}}


{{LuaCallin
{{LuaCallin
|name = AllowStartPosition
|name = AllowStartPosition
|params =  clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|args =  clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = {{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  
|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|0}} - player picked a position,  
* {{value|1}} - player clicked ready,  
* {{value|1}} - player clicked ready,  
Line 674: Line 674:
{{LuaCallin
{{LuaCallin
|name = AllowDirectUnitControl
|name = AllowDirectUnitControl
|params = unitID, unitDefID, unitTeam, playerID
|args = unitID, unitDefID, unitTeam, playerID
|return = {{type|bool}} allow
|return = {{type|bool}} allow
|description = Determines if this unit can be controlled directly in FPS view.
|info = Determines if this unit can be controlled directly in FPS view.
}}
}}


{{LuaCallin
{{LuaCallin
|name = AllowWeaponTargetCheck
|name = AllowWeaponTargetCheck
|params = attackerID, attackerWeaponNum, attackerWeaponDefID
|args = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = {{type|bool}} allowCheck, {{type|bool}} ignoreCheck
|return = {{type|bool}} allowCheck, {{type|bool}} ignoreCheck
|description = 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.
|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
{{LuaCallin
|name = AllowWeaponTarget
|name = AllowWeaponTarget
|params = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|args = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = {{type|bool}} allowed, {{type|number}} newPriority
|return = {{type|bool}} allowed, {{type|number}} newPriority
|description = 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.
|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
{{LuaCallin
|name = AllowWeaponInterceptTarget
|name = AllowWeaponInterceptTarget
|params = interceptorUnitID, interceptorWeaponID, targetProjectileID
|args = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = {{type|bool}} allowed
|return = {{type|bool}} allowed
|description = 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]].
|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
{{LuaCallin
|name = AllowBuilderHoldFire
|name = AllowBuilderHoldFire
|params = unitID, unitDefID, action
|args = unitID, unitDefID, action
|return = {{type|bool}} actionAllowed
|return = {{type|bool}} actionAllowed
|description = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}}  Called when a construction unit wants to "use his nano beams".<br>{{var|action}} is one of following:
|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|-1}} Build
* {{value|CMD.REPAIR}} Repair
* {{value|CMD.REPAIR}} Repair
Line 715: Line 715:
{{LuaCallin
{{LuaCallin
|name = Explosion
|name = Explosion
|params = weaponDefID, px, py, pz, AttackerID
|args = weaponDefID, px, py, pz, AttackerID
|return = {{type|bool}} noGfx
|return = {{type|bool}} noGfx
|description = Called when an explosion occurs. If it returns {{value|true}} then no graphical effects are drawn by the engine for this explosion.
|info = Called when an explosion occurs. If it returns {{value|true}} then no graphical effects are drawn by the engine for this explosion.
}}
}}


{{LuaCallin
{{LuaCallin
|name = TerraformComplete
|name = TerraformComplete
|params = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|args = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = {{type|bool}} stop
|return = {{type|bool}} stop
|description = 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.
|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
{{LuaCallin
|name = MoveCtrlNotify
|name = MoveCtrlNotify
|params = unitID, unitDefID, unitTeam, data
|args = unitID, unitDefID, unitTeam, data
|return = {{type|bool}} moveCtrlComplete
|return = {{type|bool}} moveCtrlComplete
|description = 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}}).
|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
{{LuaCallin
|name = RecvLuaMsg
|name = RecvLuaMsg
|params = msg, playerID
|args = msg, playerID
|description = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
|info = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}
}}


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


Line 758: Line 758:
{{LuaCallin
{{LuaCallin
|name = UnitPreDamaged
|name = UnitPreDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|description = 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.
|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
{{LuaCallin
|name = ShieldPreDamaged
|name = ShieldPreDamaged
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = {{type|bool}} handleCollision
|return = {{type|bool}} handleCollision
|description = 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.
|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.
}}
}}


{{LuaCallin
{{LuaCallin
|name = FeaturePreDamaged
|name = FeaturePreDamaged
|params = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|description = 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.
|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]]
[[Category: Lua]]

Revision as of 14:42, 18 June 2016

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.

Common

addon.Initialize()

Called when the addon is (re)loaded.


addon.Shutdown()

Called when the addon or the game is shutdown.


Unsynced Only

addon.DefaultCommand(type, id)
return: number 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 unitID or featureID respectively.


addon.CommandNotify(cmdID, cmdParams, cmdOptions)
return: bool removeCmd

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


addon.CommandsChanged(None)
return: ?

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


addon.WorldTooltip(ttType, data1, data2, data3)
return: string newTooltip

The parameters can be "unit", unitID; "feature", featureID; "ground", posX, posY, posZ or "selection".


addon.UnsyncedHeightMapUpdate(???)

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


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


addon.GameSetup(state, ready, playerStates)
return: bool success, bool newReady

???


addon.SunChanged(???)

???


addon.AddConsoleLine(msg, priority)

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


addon.RecvSkirmishAIMessage(aiTeam, dataStr)
return: ???

???


addon.RecvFromSynced(...)

Receives data sent via SendToUnsynced callout.


addon.Save(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.


addon.LoadProgress(message, replaceLastLine)

Only available to LuaIntro.


addon.GroupChanged(groupID)

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


addon.ConfigureLayout(???)
return: ???

???


Input

addon.IsAbove(x, y)
return: bool isAbove

Called every Update. Must return true for Mouse* events and GetToolTip to be called.


addon.GetTooltip(x, y)
return: string tooltip

Called when IsAbove returns true.


addon.KeyPress(key, mods, isRepeat)
return: bool becomeOwner

Called repeatedly when a key is pressed down. If you want an action to occur only once check for isRepeat == false. The mods parameter is a table, with keys "alt", "ctrl", "meta" and "shift" each having a boolean value. Return true if you don't want other callins or the engine to also receive this keypress.


addon.KeyRelease(key)
return: bool

Called when the key is released.


addon.TextInput(utf8char)

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


addon.JoystickEvent(???)

???


addon.MousePress(x, y, button)
return: bool becomeMouseOwner

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.


addon.MouseRelease(x, y, button)
return: bool becomeMouseOwner

Called when a mouse button is released. Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same addon that returns true.


addon.MouseWheel(up, value)

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


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

Called when the mouse is moved. The dx and dy parameters indicate the distance travelled, whereas the first two indicate the final position.


Players

addon.PlayerChanged(playerID)

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


addon.PlayerAdded(playerID)

Called whenever a new player joins the game.


addon.PlayerRemoved(playerID, reason)

Called whenever a player is removed from the game.


Drawing

addon.ViewResize(viewSizeX, viewSizeY)

Called whenever the window is resized.


addon.Update(dt)

Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.


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

addon.DrawGenesis()

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


addon.DrawWorldPreUnit()

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


addon.DrawWorld()

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


addon.DrawWorldShadow()

???


addon.DrawWorldReflection()

???


addon.DrawWorldRefraction()

???


addon.DrawScreen()

???


addon.DrawScreenEffects(vsx, vsy)

Where vsx, vsy are screen coordinates.


addon.DrawLoadScreen()

New in version 95.0 Only available to LuaIntro, draws custom load screens.


addon.DrawInMinimap(sx, sy)

Where sx, sy are values relative to the minimap's position and scale.


addon.DrawInMinimapBackground(sx, sy)

Where sx, sy are values relative to the minimap's position and scale.


Custom Object Rendering

For the following calls drawMode can be one of the following, notDrawing = 0, normalDraw = 1, shadowDraw = 2, reflectionDraw = 3, refractionDraw = 4.

addon.DrawUnit(unitID, drawMode)
return: bool suppressEngineDraw

For custom rendering of units, enabled here.


addon.DrawFeature(unitID, drawMode)
return: bool suppressEngineDraw

For custom rendering of features, enabled here.


addon.DrawShield(unitID, weaponID, drawMode)
return: bool suppressEngineDraw

For custom rendering of shields.


addon.DrawProjectile(projectileID, drawMode)
return: bool suppressEngineDraw

For custom rendering of weapon (& other) projectiles.


Synced - Unsynced Shared

addon.GotChatMsg(msg, player)

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


Game

addon.GameID(gameID)

Called once to deliver the gameID.


addon.GamePaused()

Called when the game is paused.


addon.GameOver(winningAllyTeams)

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


addon.GameFrame(frame)

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


addon.GamePreload()

Called before the 0 gameframe.


addon.GameStart()

Called upon the start of the game.


Teams

addon.TeamChanged(teamID)

???


addon.TeamDied(teamID)

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


Units

addon.UnitCreated(unitID, unitDefID, unitTeam, builderID)

Called at the moment the unit is created.


addon.UnitFinished(unitID, unitDefID, unitTeam)

Called at the moment the unit is completed.


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

Called when a factory finishes construction of a unit.


addon.UnitGiven(unitID, unitDefID, newTeam, oldTeam)

Called when a unit is transferred between teams.


addon.UnitTaken(unitID, unitDefID, oldTeam, newTeam)

Called when a unit is transferred between teams.


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

Called when a unit is damaged (after UnitPreDamaged).


addon.UnitDestroyed(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam)

Called when a unit is destroyed.


addon.RenderUnitDestroyed(unitID, unitDefID, unitTeam)

Called just before a unit is invalid, after it finishes its death animation. New in version 101.0


addon.UnitStunned(unitID, unitDefID, unitTeam, stunned)

Called when a unit changes its stun status. New in version 99.0


addon.UnitUnitCollision(colliderID, collideeID)

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


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


addon.UnitCommand(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag)

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


addon.UnitCmdDone(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag)

Called when a unit completes a command.


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

Called when a unit is loaded by a transport.


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

Called when a unit is unloaded by a transport.


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

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


addon.UnitIdle(unitID, unitDefID, unitTeam)

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


addon.UnitCloaked(unitID, unitDefID, unitTeam)

Called when a unit cloaks.


addon.UnitDecloaked(unitID, unitDefID, unitTeam)

Called when a unit decloaks.


addon.UnitMoved(???)

??? Not implemented in base handler


addon.UnitMoveFailed(???)

??? Not implemented in base handler


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

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


addon.UnitEnteredLos(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters LOS of an allyteam.


addon.UnitLeftLos(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit leaves LOS of an allyteam.


addon.UnitEnteredRadar(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters radar of an allyteam.


addon.UnitLeftRadar(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit leaves radar of an allyteam.


addon.UnitEnteredAir(???)

??? Not implemented by base handler


addon.UnitLeftAir(???)

??? Not implemented by base handler


addon.UnitEnteredWater(???)

??? Not implemented by base handler


addon.UnitLeftWater(???)

??? Not implemented by base handler


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

Called when a unit emits a seismic ping. See seismicSignature.


Features

addon.FeatureCreated(featureID, allyTeamID)

Called when a feature is created.


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

Called when a feature is damaged.


addon.FeatureDestroyed(featureID, allyTeamID)

Called when a feature is destroyed.


addon.FeatureMoved(???)

???


Projectiles

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

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


addon.ProjectileDestroyed(proID)

Called when the projectile is destroyed.


Synced Only

addon.CommandFallback(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag)
return: bool used, bool finished

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


addon.AllowCommand(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced)
return: bool 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.


addon.AllowUnitCreation(unitDefID, builderID, builderTeam, x, y, z, facing)
return: bool allow

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


addon.AllowUnitTransfer(unitID, unitDefID, oldTeam, newTeam, capture)
return: bool allow

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


addon.AllowUnitBuildStep(builderID, builderTeam, unitID, unitDefID, part)
return: bool allow

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


addon.AllowFeatureCreation(featureDefID, teamID, x, y, z)
return: bool allow

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


addon.AllowFeatureBuildStep(builderID, builderTeam, featureID, featureDefID, part)
return: bool allow

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


addon.AllowResourceLevel(teamID, res, level)
return: bool 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.


addon.AllowResourceTransfer(oldTeamID, newTeamID, res, amount)
return: bool allow

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


addon.AllowStartPosition(clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ)
return: bool allow

clamped{X,Y,Z} are the coordinates clamped into start-boxes, raw is where player tried to place their marker. The readyState can be any one of
  • 0 - player picked a position,
  • 1 - player clicked ready,
  • 2 - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
  • 3 - the player failed to load.
  • New in version 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.


addon.AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID)
return: bool allow

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


addon.AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID)
return: bool allowCheck, bool ignoreCheck

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


addon.AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority)
return: bool allowed, number 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 defPriority). Lower priority targets are targeted first.


addon.AllowWeaponInterceptTarget(interceptorUnitID, interceptorWeaponID, targetProjectileID)
return: bool allowed

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


addon.AllowBuilderHoldFire(unitID, unitDefID, action)
return: bool actionAllowed

New in version 98.0 5a82d750 Called when a construction unit wants to "use his nano beams".
action is one of following:
  • -1 Build
  • CMD.REPAIR Repair
  • CMD.RECLAIM Reclaim
  • CMD.RESTORE Restore
  • CMD.RESURRECT Resurrect
  • CMD.CAPTURE Capture


addon.Explosion(weaponDefID, px, py, pz, AttackerID)
return: bool noGfx

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


addon.TerraformComplete(unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam)
return: bool stop

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


addon.MoveCtrlNotify(unitID, unitDefID, unitTeam, data)
return: bool 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 1 ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled (false) or return to engine controlled movement (true).


addon.RecvLuaMsg(msg, playerID)

Receives messages from unsynced sent via Spring.SendLuaRulesMsg.


addon.Load(zip)

Called after GamePreload and before GameStart. See Lua_SaveLoad.


Damage Controllers

For the following callins, in addition to being a regular weapon, weaponDefID 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

addon.UnitPreDamaged(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)
return: number newDamage, number impulseMult

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


addon.ShieldPreDamaged(proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile)
return: bool handleCollision

Called before any engine shield-vs-projectile logic executes. If the return value is true the gadget handles the collision event and the engine does not remove the projectile.


addon.FeaturePreDamaged(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)
return: number newDamage, number impulseMult

Called before damage is applied to the feature, allows fine control over how much damage and impulse is applied.
Retrieved from "https://springrts-wiki.p2004a.com/mediawiki/index.php?title=Lua:Callins&oldid=10774"