Lua:Callins: Difference between revisions

From Spring
Jump to navigationJump to search
← Older editNewer edit →
Flozi (talk | contribs)
0 edits
fancify with templates - unsynced callins so far
Flozi (talk | contribs)
0 edits
→Synced - Unsynced Shared: template styling
Line 318: Line 318:
|name = GotChatMsg
|name = GotChatMsg
|params = msg, player
|params = msg, player
|return = none
|description = Called when a player issues a UI command e.g. types {{var|/foo}} or {{var|/luarules foo}}.
|description = Called when a player issues a UI command e.g. types <code>/foo</code> or <code>/luarules foo</code>.
}}
}}


Line 327: Line 326:
|name = GameID
|name = GameID
|params = gameID
|params = gameID
|return = none
|description = Called once to deliver the {{var|gameID}}.
|description = Called once to deliver the gameID.
}}
}}


{{LuaCallin
{{LuaCallin
|name = GamePaused
|name = GamePaused
|params =
|return = none
|description = Called when the game is paused.
|description = Called when the game is paused.
}}
}}
Line 341: Line 337:
|name = GameOver
|name = GameOver
|params = winningAllyTeams
|params = winningAllyTeams
|return = none
|description = The parameter is a {{type|table}} list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
|description = The parameter is a list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}
}}


Line 348: Line 343:
|name = GameFrame
|name = GameFrame
|params = frame
|params = frame
|return = none
|description = Called for every game simulation frame (30 per second).
|description = Called for every game simulation frame (30 per second).
}}
}}
Line 354: Line 348:
{{LuaCallin
{{LuaCallin
|name = GamePreload
|name = GamePreload
|params =
|return = none
|description = Called before the 0 gameframe.
|description = Called before the 0 gameframe.
}}
}}
Line 361: Line 353:
{{LuaCallin
{{LuaCallin
|name = GameStart
|name = GameStart
|params =
|return = none
|description = Called upon the start of the game.
|description = Called upon the start of the game.
}}
}}
Line 370: Line 360:
|name = TeamChanged
|name = TeamChanged
|params = teamID
|params = teamID
|return = none
|description = ???
|description = ???
}}
}}
Line 377: Line 366:
|name = TeamDied
|name = TeamDied
|params = teamID
|params = teamID
|return = none
|description = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
|description = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}
}}
Line 385: Line 373:
|name = UnitCreated
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|params = unitID, unitDefID, unitTeam, builderID
|return = none
|description = Called at the moment the unit is created.
|description = Called at the moment the unit is created.
}}
}}
Line 392: Line 379:
|name = UnitFinished
|name = UnitFinished
|params = unitID, unitDefID, unitTeam
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called at the moment the unit is completed.
|description = Called at the moment the unit is completed.
}}
}}
Line 399: Line 385:
|name = UnitFromFactory
|name = UnitFromFactory
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|return = none
|description = Called when a factory finishes construction of a unit.
|description = Called when a factory finishes construction of a unit.
}}
}}
Line 406: Line 391:
|name = UnitGiven
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|params = unitID, unitDefID, newTeam, oldTeam
|return = none
|description = Called when a unit is transferred between teams.
|description = Called when a unit is transferred between teams.
}}
}}
Line 413: Line 397:
|name = UnitTaken
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|params = unitID, unitDefID, oldTeam, newTeam
|return = none
|description = Called when a unit is transferred between teams.
|description = Called when a unit is transferred between teams.
}}
}}
Line 420: Line 403:
|name = UnitDamaged
|name = UnitDamaged
|params =  unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|params =  unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is damaged (after {{name|UnitPreDamaged}}).
|description = Called when a unit is damaged (after <code>UnitPreDamaged</code>).
}}
}}


Line 427: Line 409:
|name = UnitDestroyed
|name = UnitDestroyed
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is destroyed.
|description = Called when a unit is destroyed.
}}
}}
Line 434: Line 415:
|name = RenderUnitDestroyed
|name = RenderUnitDestroyed
|params = unitID, unitDefID, unitTeam
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called just before a unit is invalid, after it finishes its death animation. {{new|101.0}}
|description = Called just before a unit is invalid, after it finishes its death animation. {{new|101.0}}
}}
}}
Line 441: Line 421:
|name = UnitStunned
|name = UnitStunned
|params =  unitID, unitDefID, unitTeam, stunned
|params =  unitID, unitDefID, unitTeam, stunned
|return = none
|description = Called when a unit changes its stun status. {{new|99.0}}
|description = Called when a unit changes its stun status. {{new|99.0}}
}}
}}
Line 448: Line 427:
|name = UnitUnitCollision
|name = UnitUnitCollision
|params = colliderID, collideeID
|params = colliderID, collideeID
|return = none
|description = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
|description = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}
}}
Line 455: Line 433:
|name = UnitFeatureCollision
|name = UnitFeatureCollision
|params = colliderID, collideeID
|params = colliderID, collideeID
|return = none
|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]].
|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]].
}}
}}
Line 462: Line 439:
|name = UnitCommand
|name = UnitCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}
}}


Line 469: Line 445:
|name = UnitCmdDone
|name = UnitCmdDone
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called when a unit completes a command.
|description = Called when a unit completes a command.
}}
}}
Line 476: Line 451:
|name = UnitLoaded
|name = UnitLoaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is loaded by a transport.
|description = Called when a unit is loaded by a transport.
}}
}}
Line 483: Line 457:
|name = UnitUnloaded
|name = UnitUnloaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is unloaded by a transport.
|description = Called when a unit is unloaded by a transport.
}}
}}
Line 490: Line 463:
|name = UnitExperience
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|return = none
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}
}}
Line 497: Line 469:
|name = UnitIdle
|name = UnitIdle
|params = unitID, unitDefID, unitTeam
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit is idle (empty command queue).
|description = Called when a unit is idle (empty command queue).
}}
}}
Line 504: Line 475:
|name = UnitCloaked
|name = UnitCloaked
|params = unitID, unitDefID, unitTeam
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit cloaks.
|description = Called when a unit cloaks.
}}
}}
Line 511: Line 481:
|name = UnitDecloaked
|name = UnitDecloaked
|params = unitID, unitDefID, unitTeam
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit decloaks.
|description = Called when a unit decloaks.
}}
}}
Line 518: Line 487:
|name = UnitMoved
|name = UnitMoved
|params = ???
|params = ???
|return = none
|description = ??? Not implemented in base handler
|description = ??? Not implemented in base handler
}}
}}
Line 525: Line 493:
|name = UnitMoveFailed
|name = UnitMoveFailed
|params = ???
|params = ???
|return = none
|description = ??? Not implemented in base handler
|description = ??? Not implemented in base handler
}}
}}
Line 532: Line 499:
|name = StockpileChanged
|name = StockpileChanged
|params = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|params = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|return = none
|description = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
|description = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}
}}
Line 539: Line 505:
|name = UnitEnteredLos
|name = UnitEnteredLos
|params = unitID, unitTeam, allyTeam, unitDefID
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters LOS of an allyteam.
|description = Called when a unit enters LOS of an allyteam.
}}
}}
Line 546: Line 511:
|name = UnitLeftLos
|name = UnitLeftLos
|params = unitID, unitTeam, allyTeam, unitDefID
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves LOS of an allyteam.
|description = Called when a unit leaves LOS of an allyteam.
}}
}}
Line 553: Line 517:
|name = UnitEnteredRadar
|name = UnitEnteredRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters radar of an allyteam.
|description = Called when a unit enters radar of an allyteam.
}}
}}
Line 560: Line 523:
|name = UnitLeftRadar
|name = UnitLeftRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves radar of an allyteam.
|description = Called when a unit leaves radar of an allyteam.
}}
}}
Line 567: Line 529:
|name = UnitEnteredAir
|name = UnitEnteredAir
|params = ???
|params = ???
|return = none
|description = ??? Not implemented by base handler
|description = ??? Not implemented by base handler
}}
}}
Line 574: Line 535:
|name = UnitLeftAir
|name = UnitLeftAir
|params = ???
|params = ???
|return = none
|description = ??? Not implemented by base handler
|description = ??? Not implemented by base handler
}}
}}
Line 581: Line 541:
|name = UnitEnteredWater
|name = UnitEnteredWater
|params = ???
|params = ???
|return = none
|description = ??? Not implemented by base handler
|description = ??? Not implemented by base handler
}}
}}
Line 588: Line 547:
|name = UnitLeftWater
|name = UnitLeftWater
|params = ???
|params = ???
|return = none
|description = ??? Not implemented by base handler
|description = ??? Not implemented by base handler
}}
}}
Line 595: Line 553:
|name = UnitSeismicPing
|name = UnitSeismicPing
|params = x, y, z, strength, allyTeam, unitID, unitDefID
|params = x, y, z, strength, allyTeam, unitID, unitDefID
|return = none
|description = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
|description = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}
}}
Line 603: Line 560:
|name = FeatureCreated
|name = FeatureCreated
|params = featureID, allyTeamID
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is created.
|description = Called when a feature is created.
}}
}}
Line 610: Line 566:
|name = FeatureDamaged
|name = FeatureDamaged
|params =  featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|params =  featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a feature is damaged.
|description = Called when a feature is damaged.
}}
}}
Line 617: Line 572:
|name = FeatureDestroyed
|name = FeatureDestroyed
|params = featureID, allyTeamID
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is destroyed.
|description = Called when a feature is destroyed.
}}
}}
Line 624: Line 578:
|name = FeatureMoved
|name = FeatureMoved
|params = ???
|params = ???
|return = none
|description = ???
|description = ???
}}
}}
Line 634: Line 587:
|name = ProjectileCreated
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|params = proID, proOwnerID, weaponDefID
|return = none
|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}}.
|description = Called when the projectile is created.
}}
}}
:<span class=warning>note1 <code>weaponDefID</code> is missing in case the projectile is spawned as part of the burst</span>
:
:note2: <code>Spring.GetProjectileDefID</code> and <code>Spring.GetProjectileName</code> still work in callin scope using <code>proID</code>


{{LuaCallin
{{LuaCallin
|name = ProjectileDestroyed
|name = ProjectileDestroyed
|params = proID
|params = proID
|return = none
|description = Called when the projectile is destroyed.
|description = Called when the projectile is destroyed.
}}
}}

Revision as of 23:32, 17 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()

{{{info}}}


addon.Shutdown()

{{{info}}}


Unsynced Only

addon.DefaultCommand()
return: number cmdID

{{{info}}}


addon.CommandNotify()
return: bool removeCmd

{{{info}}}


addon.CommandsChanged()
return: ?

{{{info}}}


addon.WorldTooltip()
return: string newTooltip

{{{info}}}


addon.UnsyncedHeightMapUpdate()

{{{info}}}


addon.GameProgress()

{{{info}}}


addon.GameSetup()
return: bool success, bool newReady

{{{info}}}


addon.SunChanged()

{{{info}}}


addon.AddConsoleLine()

{{{info}}}


addon.RecvSkirmishAIMessage()
return: ???

{{{info}}}


addon.RecvFromSynced()

{{{info}}}


addon.Save()

{{{info}}}


addon.LoadProgress()

{{{info}}}


addon.GroupChanged()

{{{info}}}


addon.ConfigureLayout()
return: ???

{{{info}}}


Input

addon.IsAbove()
return: bool isAbove

{{{info}}}


addon.GetTooltip()
return: string tooltip

{{{info}}}


addon.KeyPress()
return: bool becomeOwner

{{{info}}}


addon.KeyRelease()
return: bool

{{{info}}}


addon.TextInput()

{{{info}}}


addon.JoystickEvent()

{{{info}}}


addon.MousePress()
return: bool becomeMouseOwner

{{{info}}}


addon.MouseRelease()
return: bool becomeMouseOwner

{{{info}}}


addon.MouseWheel()

{{{info}}}


addon.MouseMove()

{{{info}}}


Players

addon.PlayerChanged()

{{{info}}}


addon.PlayerAdded()

{{{info}}}


addon.PlayerRemoved()

{{{info}}}


Drawing

addon.ViewResize()

{{{info}}}


addon.Update()

{{{info}}}


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

addon.DrawGenesis()

{{{info}}}


addon.DrawWorldPreUnit()

{{{info}}}


addon.DrawWorld()

{{{info}}}


addon.DrawWorldShadow()

{{{info}}}


addon.DrawWorldReflection()

{{{info}}}


addon.DrawWorldRefraction()

{{{info}}}


addon.DrawScreen()

{{{info}}}


addon.DrawScreenEffects()

{{{info}}}


addon.DrawLoadScreen()

{{{info}}}


addon.DrawInMinimap()

{{{info}}}


addon.DrawInMinimapBackground()

{{{info}}}


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()
return: bool suppressEngineDraw

{{{info}}}


addon.DrawFeature()
return: bool suppressEngineDraw

{{{info}}}


addon.DrawShield()
return: bool suppressEngineDraw

{{{info}}}


addon.DrawProjectile()
return: bool suppressEngineDraw

{{{info}}}


Synced - Unsynced Shared

addon.GotChatMsg()

{{{info}}}


Game

addon.GameID()

{{{info}}}


addon.GamePaused()

{{{info}}}


addon.GameOver()

{{{info}}}


addon.GameFrame()

{{{info}}}


addon.GamePreload()

{{{info}}}


addon.GameStart()

{{{info}}}


Teams

addon.TeamChanged()

{{{info}}}


addon.TeamDied()

{{{info}}}


Units

addon.UnitCreated()

{{{info}}}


addon.UnitFinished()

{{{info}}}


addon.UnitFromFactory()

{{{info}}}


addon.UnitGiven()

{{{info}}}


addon.UnitTaken()

{{{info}}}


addon.UnitDamaged()

{{{info}}}


addon.UnitDestroyed()

{{{info}}}


addon.RenderUnitDestroyed()

{{{info}}}


addon.UnitStunned()

{{{info}}}


addon.UnitUnitCollision()

{{{info}}}


addon.UnitFeatureCollision()

{{{info}}}


addon.UnitCommand()

{{{info}}}


addon.UnitCmdDone()

{{{info}}}


addon.UnitLoaded()

{{{info}}}


addon.UnitUnloaded()

{{{info}}}


addon.UnitExperience()

{{{info}}}


addon.UnitIdle()

{{{info}}}


addon.UnitCloaked()

{{{info}}}


addon.UnitDecloaked()

{{{info}}}


addon.UnitMoved()

{{{info}}}


addon.UnitMoveFailed()

{{{info}}}


addon.StockpileChanged()

{{{info}}}


addon.UnitEnteredLos()

{{{info}}}


addon.UnitLeftLos()

{{{info}}}


addon.UnitEnteredRadar()

{{{info}}}


addon.UnitLeftRadar()

{{{info}}}


addon.UnitEnteredAir()

{{{info}}}


addon.UnitLeftAir()

{{{info}}}


addon.UnitEnteredWater()

{{{info}}}


addon.UnitLeftWater()

{{{info}}}


addon.UnitSeismicPing()

{{{info}}}


Features

addon.FeatureCreated()

{{{info}}}


addon.FeatureDamaged()

{{{info}}}


addon.FeatureDestroyed()

{{{info}}}


addon.FeatureMoved()

{{{info}}}


Projectiles

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

addon.ProjectileCreated()

{{{info}}}


addon.ProjectileDestroyed()

{{{info}}}


Synced Only

addon.CommandFallback()
return: bool used, bool finished

{{{info}}}


addon.AllowCommand()
return: bool allow

{{{info}}}


addon.AllowUnitCreation()
return: bool allow

{{{info}}}


addon.AllowUnitTransfer()
return: bool allow

{{{info}}}


addon.AllowUnitBuildStep()
return: bool allow

{{{info}}}


addon.AllowFeatureCreation()
return: bool allow

{{{info}}}


addon.AllowFeatureBuildStep()
return: bool allow

{{{info}}}


addon.AllowResourceLevel()
return: bool allow

{{{info}}}


addon.AllowResourceTransfer()
return: bool allow

{{{info}}}


addon.AllowStartPosition()
return: bool allow

{{{info}}}


addon.AllowDirectUnitControl()
return: bool allow

{{{info}}}


addon.AllowWeaponTargetCheck()
return: bool allowCheck, bool ignoreCheck

{{{info}}}


addon.AllowWeaponTarget()
return: bool allowed, number newPriority

{{{info}}}


addon.AllowWeaponInterceptTarget()
return: bool allowed

{{{info}}}


addon.AllowBuilderHoldFire()
return: bool actionAllowed

{{{info}}}


addon.Explosion()
return: bool noGfx

{{{info}}}


addon.TerraformComplete()
return: bool stop

{{{info}}}


addon.MoveCtrlNotify()
return: bool moveCtrlComplete

{{{info}}}


addon.RecvLuaMsg()
return: none

{{{info}}}


addon.Load()
return: none

{{{info}}}


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()
return: number newDamage, number impulseMult

{{{info}}}


addon.ShieldPreDamaged()
return: bool handleCollision

{{{info}}}


addon.FeaturePreDamaged()
return: number newDamage, number impulseMult

{{{info}}}
Retrieved from "https://springrts-wiki.p2004a.com/mediawiki/index.php?title=Lua:Callins&oldid=10772"