Lua:Callins

Lua Callins

This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the 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.

Warning: Some callins, such as KeyPress, may return a bool, to indicate that they grabbed the event and that it should not be available for others, despite being marked with none return on this list.

Common

addon.Initialize()
return: none

{{{info}}}

addon.Shutdown()
return: none

{{{info}}}

Unsynced Only

addon.DefaultCommand()
return: number cmdID

{{{info}}}

addon.CommandNotify()
return: bool removeCmd

{{{info}}}

addon.WorldTooltip()
return: string newTooltip

{{{info}}}

addon.UnsyncedHeightMapUpdate()
return: none

{{{info}}}

addon.GameProgress()
return: none

{{{info}}}

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

{{{info}}}

addon.SunChanged()
return: none

{{{info}}}

addon.AddConsoleLine()
return: none

{{{info}}}

addon.RecvSkirmishAIMessage()
return: ???

{{{info}}}

addon.RecvFromSynced()
return: none

{{{info}}}

addon.Save()
return: none

{{{info}}}

addon.LoadProgress()
return: none

{{{info}}}

addon.GroupChanged()
return: none

{{{info}}}

addon.ConfigureLayout()
return: ???

{{{info}}}

Input

addon.IsAbove()
return: bool isAbove

{{{info}}}

addon.GetTooltip()
return: string tooltip

{{{info}}}

addon.KeyPress()
return: none

{{{info}}}

addon.KeyRelease()
return: none

{{{info}}}

addon.TextInput()
return: none

{{{info}}}

addon.JoystickEvent()
return: none

{{{info}}}

addon.MousePress()
return: bool becomeMouseOwner

{{{info}}}

addon.MouseRelease()
return: bool becomeMouseOwner

{{{info}}}

addon.MouseWheel()
return: none

{{{info}}}

addon.MouseMove()
return: none

{{{info}}}

Players

addon.PlayerChanged()
return: none

{{{info}}}

addon.PlayerAdded()
return: none

{{{info}}}

addon.PlayerRemoved()
return: none

{{{info}}}

Drawing

addon.ViewResize()
return: none

{{{info}}}

addon.Update()
return: none

{{{info}}}

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

addon.DrawGenesis()
return: none

{{{info}}}

addon.DrawWorldPreUnit()
return: none

{{{info}}}

addon.DrawWorld()
return: none

{{{info}}}

addon.DrawWorldShadow()
return: none

{{{info}}}

addon.DrawWorldReflection()
return: none

{{{info}}}

addon.DrawWorldRefraction()
return: none

{{{info}}}

addon.DrawScreen()
return: none

{{{info}}}

addon.DrawScreenEffects()
return: none

{{{info}}}

addon.DrawLoadScreen()
return: none

{{{info}}}

addon.DrawInMinimap()
return: none

{{{info}}}

addon.DrawInMinimapBackground()
return: none

{{{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()
return: none

{{{info}}}

Game

addon.GameID()
return: none

{{{info}}}

addon.GamePaused()
return: none

{{{info}}}

addon.GameOver()
return: none

{{{info}}}

addon.GameFrame()
return: none

{{{info}}}

addon.GamePreload()
return: none

{{{info}}}

addon.GameStart()
return: none

{{{info}}}

Teams

addon.TeamChanged()
return: none

{{{info}}}

addon.TeamDied()
return: none

{{{info}}}

Units

addon.UnitCreated()
return: none

{{{info}}}

addon.UnitFinished()
return: none

{{{info}}}

addon.UnitFromFactory()
return: none

{{{info}}}

addon.UnitGiven()
return: none

{{{info}}}

addon.UnitTaken()
return: none

{{{info}}}

addon.UnitDamaged()
return: none

{{{info}}}

addon.UnitDestroyed()
return: none

{{{info}}}

addon.UnitStunned()
return: none

{{{info}}}

addon.UnitUnitCollision()
return: none

{{{info}}}

addon.UnitFeatureCollision()
return: none

{{{info}}}

addon.UnitCommand()
return: none

{{{info}}}

addon.UnitCmdDone()
return: none

{{{info}}}

addon.UnitLoaded()
return: none

{{{info}}}

addon.UnitUnloaded()
return: none

{{{info}}}

addon.UnitExperience()
return: none

{{{info}}}

addon.UnitIdle()
return: none

{{{info}}}

addon.UnitCloaked()
return: none

{{{info}}}

addon.UnitDecloaked()
return: none

{{{info}}}

addon.UnitMoved()
return: none

{{{info}}}

addon.UnitMoveFailed()
return: none

{{{info}}}

addon.StockpileChanged()
return: none

{{{info}}}

addon.UnitEnteredLos()
return: none

{{{info}}}

addon.UnitLeftLos()
return: none

{{{info}}}

addon.UnitEnteredRadar()
return: none

{{{info}}}

addon.UnitLeftRadar()
return: none

{{{info}}}

addon.UnitEnteredAir()
return: none

{{{info}}}

addon.UnitLeftAir()
return: none

{{{info}}}

addon.UnitEnteredWater()
return: none

{{{info}}}

addon.UnitLeftWater()
return: none

{{{info}}}

addon.UnitSeismicPing()
return: none

{{{info}}}

Features

addon.FeatureCreated()
return: none

{{{info}}}

addon.FeatureDamaged()
return: none

{{{info}}}

addon.FeatureDestroyed()
return: none

{{{info}}}

addon.FeatureMoved()
return: none

{{{info}}}

Projectiles

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

addon.ProjectileCreated()
return: none

{{{info}}}

addon.ProjectileDestroyed()
return: none

{{{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}}}