Lua Callins

From Zero-K
Jump to navigation Jump to search

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.

Related Sourcecode : 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,

    function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
        ...  
    end

Some functions may differ between (synced) gadget and widgets; those are in the #Synced_-_Unsynced_Shared section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.

Attention: some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace. This document will be continuously updated to properly alert about those situations.

Common

Template:PrefixTemplate:NameTemplate:CodeStyle()

Called when the addon is (re)loaded.


Template:PrefixTemplate:NameTemplate:CodeStyle()

Called when the addon or the game is shutdown.


Unsynced Only

Template:PrefixTemplate:NameTemplate:CodeStyle(type, id)
return: Template:CodeStyleTemplate:Type cmdID

Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either "unit or "feature") and the second is its Template:CodeStyleunitID or Template:CodeStylefeatureID respectively.


Template:PrefixTemplate:NameTemplate:CodeStyle(cmdID, cmdParams, cmdOptions)
return: Template:CodeStyleTemplate:Type removeCmd

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


Template:PrefixTemplate:NameTemplate:CodeStyle(None)
return: Template:CodeStyle?

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


Template:PrefixTemplate:NameTemplate:CodeStyle(ttType, data1, data2, data3)
return: Template:CodeStyleTemplate:Type newTooltip

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


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(serverFrameNum)

Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.


Template:PrefixTemplate:NameTemplate:CodeStyle(state, ready, playerStates)
return: Template:CodeStyleTemplate:Type success, Template:Type newReady

???


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

???


Template:PrefixTemplate:NameTemplate:CodeStyle(msg, priority)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(aiTeam, dataStr)
return: Template:CodeStyle???

???


Template:PrefixTemplate:NameTemplate:CodeStyle(...)

Receives data sent via SendToUnsynced callout.


Template:PrefixTemplate:NameTemplate:CodeStyle(zip)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(message, replaceLastLine)

Only available to LuaIntro.


Template:PrefixTemplate:NameTemplate:CodeStyle(groupID)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(???)
return: Template:CodeStyle???

???


Input

Template:PrefixTemplate:NameTemplate:CodeStyle(x, y)
return: Template:CodeStyleTemplate:Type isAbove

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


Template:PrefixTemplate:NameTemplate:CodeStyle(x, y)
return: Template:CodeStyleTemplate:Type tooltip

Called when Template:Name returns Template:Value.


Template:PrefixTemplate:NameTemplate:CodeStyle(key, mods, isRepeat)
return: Template:CodeStyleTemplate:Type becomeOwner

Called repeatedly when a key is pressed down. If you want an action to occur only once check for Template:CodeStyleisRepeat == Template:Value. The Template:CodeStylemods parameter is a Template:Type, with keys Template:Value, Template:Value, Template:Value and Template:Value each having a boolean value. Return Template:Value if you don't want other callins or the engine to also receive this keypress. A list of key codes can be seen at the SDL wiki.


Template:PrefixTemplate:NameTemplate:CodeStyle(key)
return: Template:CodeStyleTemplate:Type

Called when the key is released.


Template:PrefixTemplate:NameTemplate:CodeStyle(utf8char)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

???


Template:PrefixTemplate:NameTemplate:CodeStyle(x, y, button)
return: Template:CodeStyleTemplate:Type becomeMouseOwner

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


Template:PrefixTemplate:NameTemplate:CodeStyle(x, y, button)
return: Template:CodeStylebool becomeMouseOwner

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


Template:PrefixTemplate:NameTemplate:CodeStyle(up, value)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(x, y, dx, dy, button)

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


Players

Template:PrefixTemplate:NameTemplate:CodeStyle(playerID)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(playerID)

Called whenever a new player joins the game.


Template:PrefixTemplate:NameTemplate:CodeStyle(playerID, reason)

Called whenever a player is removed from the game.


Downloads

Template:PrefixTemplate:NameTemplate:CodeStyle(id)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(id)

Called when a Pr-downloader download finishes successfully.


Template:PrefixTemplate:NameTemplate:CodeStyle(id, errorID)

Called when a Pr-downloader download fails to complete.


Template:PrefixTemplate:NameTemplate:CodeStyle(id, downloaded, total)

Called incrementally during a Pr-downloader download.


Drawing

Template:PrefixTemplate:NameTemplate:CodeStyle(viewSizeX, viewSizeY)

Called whenever the window is resized.


Template:PrefixTemplate:NameTemplate:CodeStyle(dt)

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


Draw* Functions

Inside the Draw* functions, you can use the Lua OpenGL Api to draw graphics.
Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

??? Template:New


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

???


Template:PrefixTemplate:NameTemplate:CodeStyle()

???


Template:PrefixTemplate:NameTemplate:CodeStyle()

???


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle(vsx, vsy)

??? Also available to LuaMenu.


Template:PrefixTemplate:NameTemplate:CodeStyle(vsx, vsy)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(vsx, vsy)

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle(sx, sy)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(sx, sy)

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


Custom Object Rendering

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

Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of units, enabled here.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of features, enabled here.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, weaponID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of shields.


Template:PrefixTemplate:NameTemplate:CodeStyle(projectileID, drawMode)
return: Template:CodeStyleTemplate:Type suppressEngineDraw

For custom rendering of weapon (& other) projectiles.


Unsynced Menu Only

Template:PrefixTemplate:NameTemplate:CodeStyle()
return: Template:CodeStyleTemplate:Type allowDraw

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

Called whenever LuaMenu is on with no game loaded.


Template:PrefixTemplate:NameTemplate:CodeStyle()

Called whenever LuaMenu is on with a game loaded.


Synced - Unsynced Shared

Template:PrefixTemplate:NameTemplate:CodeStyle(msg, player)

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


Game

Template:PrefixTemplate:NameTemplate:CodeStyle(gameID)

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

Called when the game is paused.


Template:PrefixTemplate:NameTemplate:CodeStyle(winningAllyTeams)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(frame)

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Template:PrefixTemplate:NameTemplate:CodeStyle()

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


Teams

Template:PrefixTemplate:NameTemplate:CodeStyle(teamID)

???


Template:PrefixTemplate:NameTemplate:CodeStyle(teamID)

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


Units

Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, builderID)

Called at the moment the unit is created.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam)

Called at the moment the unit is completed.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, factID, factDefID, userOrders)

Called when a factory finishes construction of a unit.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam)

Called when a living unit becomes a nanoframe again.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, newTeam, oldTeam)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, oldTeam, newTeam)

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


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

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam)

Called when a unit is destroyed.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, stunned)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(colliderID, collideeID)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(colliderID, collideeID)

Called when a unit collides with a feature. The unit must be registered with Script.SetWatchUnit and the feature registered with Script.SetWatchFeature.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag)

Called when a unit completes a command.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, transportID, transportTeam)

Called when a unit is loaded by a transport.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, transportID, transportTeam)

Called when a unit is unloaded by a transport.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, experience, oldExperience)

Called when a unit gains experience greater or equal to the minimum limit set by calling Spring.SetExperienceGrade. Should be called more reliably with small values of experience grade in 104.0+.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam)

Called when a unit cloaks.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam)

Called when a unit decloaks.


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

??? Not implemented in base handler


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

??? Not implemented in base handler


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters LOS of an allyteam.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit leaves LOS of an allyteam.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit enters radar of an allyteam.


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitTeam, allyTeam, unitDefID)

Called when a unit leaves radar of an allyteam.


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

??? Not implemented by base handler


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

??? Not implemented by base handler


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

??? Not implemented by base handler


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

??? Not implemented by base handler


Template:PrefixTemplate:NameTemplate:CodeStyle(x, y, z, strength, allyTeam, unitID, unitDefID)

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


Features

Template:PrefixTemplate:NameTemplate:CodeStyle(featureID, allyTeamID)

Called when a feature is created.


Template:PrefixTemplate:NameTemplate:CodeStyle(featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

Called when a feature is damaged.


Template:PrefixTemplate:NameTemplate:CodeStyle(featureID, allyTeamID)

Called when a feature is destroyed.


Template:PrefixTemplate:NameTemplate:CodeStyle(???)

???


Projectiles

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

Template:PrefixTemplate:NameTemplate:CodeStyle(proID, proOwnerID, weaponDefID)

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


Template:PrefixTemplate:NameTemplate:CodeStyle(proID)

Called when the projectile is destroyed.


Synced Only

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

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


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

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


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

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, oldTeam, newTeam, capture)
return: Template:CodeStyleTemplate:Type allow

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


Template:PrefixTemplate:NameTemplate:CodeStyle(builderID, builderTeam, unitID, unitDefID, part)
return: Template:CodeStyleTemplate:Type allow

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


Template:PrefixTemplate:NameTemplate:CodeStyle(featureDefID, teamID, x, y, z)
return: Template:CodeStyleTemplate:Type allow

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


Template:PrefixTemplate:NameTemplate:CodeStyle(builderID, builderTeam, featureID, featureDefID, part)
return: Template:CodeStyleTemplate:Type allow

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


Template:PrefixTemplate:NameTemplate:CodeStyle(teamID, res, level)
return: Template:CodeStyleTemplate:Type allow

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


Template:PrefixTemplate:NameTemplate:CodeStyle(oldTeamID, newTeamID, res, amount)
return: Template:CodeStyleTemplate:Type allow

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


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

Template:CodeStyleclamped{X,Y,Z} are the coordinates clamped into start-boxes, Template:CodeStyleraw is where player tried to place their marker. The Template:CodeStylereadyState can be any one of
  • Template:Value - player picked a position,
  • Template:Value - player clicked ready,
  • Template:Value - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
  • Template:Value - the player failed to load.
  • Template:New the default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, playerID)
return: Template:CodeStyleTemplate:Type allow

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


Template:PrefixTemplate:NameTemplate:CodeStyle(attackerID, attackerWeaponNum, attackerWeaponDefID)
return: Template:CodeStyleTemplate:Type allowCheck, Template:Type ignoreCheck

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


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

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


Template:PrefixTemplate:NameTemplate:CodeStyle(interceptorUnitID, interceptorWeaponID, targetProjectileID)
return: Template:CodeStyleTemplate:Type allowed

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, action)
return: Template:CodeStyleTemplate:Type actionAllowed

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


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

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


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

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


Template:PrefixTemplate:NameTemplate:CodeStyle(unitID, unitDefID, unitTeam, data)
return: Template:CodeStyleTemplate:Type moveCtrlComplete

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


Template:PrefixTemplate:NameTemplate:CodeStyle(msg, playerID)

Receives messages from unsynced sent via Spring.SendLuaRulesMsg.


Template:PrefixTemplate:NameTemplate:CodeStyle(zip)

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


Damage Controllers

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

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

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

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


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

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


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

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