Lua in SpringRTS/Callouts

Callouts are just functions defined in Spring that you can run at any point. The difference between callins and callouts is that callins are practically event invokers while callouts are functions that are ready to be used by you. The nature of callous is exactly the same with any function. They can return values, they can change values or both. Keep in mind that the synced/unsynced theory should still be taken in consideration.
Trying for example to change the value of a game parameter via a callout in a widget is not permitted.

Example of callout:

teamID=Spring.GetUnitTeam(unitID)

In the above example we pass unitID as an argument to function GetUnitTeam(). GetUnitTeam returns the ID of the team which we store to our variable(teamID).


Callout name Description Synced mode Unsynced mode Arguments Return values
Spring.AddGrass x, y, z nil
Spring.AddHeightMap can only be called in SetHeightMapFunc x, z, height nil
number newHeight
Spring.AddSmoothMesh can only be called in SetSmoothMeshFunc x, z, height nil
number newHeight
Spring.AddTeamResource teamID, resourceName, resourceAmount nil
Spring.AddUnitDamage unitID, damageAmount [, number paralyze = 0 [, attackerID = -1 [, weaponID = -1[, impulse_x [, impulse_y [, impulse_z ]]] ]]] nil
Spring.AddUnitImpulse unitID, x, y, z nil
Spring.AddUnitResource unitID, resourceName, resourceAmount nil
Spring.AddUnitSeismicPing unitID, pingSize nil
Spring.AdjustHeightMap x1, z1 [, x2, z2], height nil
Spring.AdjustSmoothMesh x1, z1 [, x2, z2], height nil
Spring.CallCOBScript unitID, funcID
string funcName, number retArgs, COBArg1, COBArg2, ...
number returnValue, number retArg1, number retArg2, ...
Spring.CallCOBScriptCB broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement funcName, number retArgs, COBArg1, COBArg2, ... number returnValue, number CallbackData, number retArg1, number retArg2, ...
Spring.CreateFeature defName
featureID, x, y, z[,number heading [, allyTeamID ]]
featureID
Spring.CreateUnit offmap positions are clamped! you still can use MoveCtrl todo so number unitDefID, x, y, z, number facing string "facing", teamID, [boolean build = false] unitID,
Spring.DestroyFeature featureID nil
Spring.DestroyUnit unitID, [boolean selfd = false,], [boolean reclaimed = false,], [number attackerID] nil
Spring.EditUnitCmdDesc Yes No unitID, number cmdDescID, table cmdArray nil
Spring.GameOver Will declare game over. New in version 0.83.x [ [1] = allyTeamID1, [2] = allyTeamID2, .. ] nil
Spring.GetCOBScriptID unitID, funcName funcID
Spring.GetUnitCOBValue unitID, [, boolean splitData=false], number COBValue[, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] number result1, number result2
Spring.GiveOrderArrayToUnitArray unitArray = { [1] = unitID, etc... },orderArray = {{ number cmdID,{number, etc...}, params{"alt", "ctrl", "shift", "right"} options}, ..} nil
Spring.GiveOrderArrayToUnitMap unitMap = { [unitID] = dontCare, etc... }, orderArray = {{ number cmdID,{number, etc...}, params{"alt", "ctrl", "shift", "right"} options}, ..} nil
Spring.GiveOrderToUnit unitID, number cmdID, params = {number, etc...}, options = {"alt", "ctrl", "shift", "right"} nil
Spring.GiveOrderToUnitArray unitArray = { [1] = unitID, etc... },number cmdID,params = {number, etc...},options = {"alt", "ctrl", "shift", "right"} nil
Spring.GiveOrderToUnitMap unitMap = { [unitID] = dontCare, etc... },number cmdID,params = {number, etc...},options = {"alt", "ctrl", "shift", "right"} nil
Spring.InsertUnitCmdDesc unitID, [, number cmdDescID ] , table cmdArray nil
Spring.KillTeam Will declare a team to be dead. New in version 0.83.x teamID nil
Spring.LevelHeightMap x1, z1 [, x2, z2], height nil
Spring.LevelSmoothMesh x1, z1 [, x2, z2], height nil
Spring.RemoveBuildingDecal unitID, nil
Spring.RemoveGrass x, y, z nil
Spring.RemoveUnitCmdDesc unitID, [, number cmdDescID ] nil
Spring.RevertHeightMap x1, z1 [, x2, z2], number origFactor nil
Spring.RevertSmoothMesh x1, z1 [, x2, z2], number origFactor nil
Spring.SetExperienceGrade number expGrade[, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]] nil
Spring.SetFeatureAlwaysVisible featureID, boolean enable nil
Spring.SetFeatureCollisionVolumeData featureID, number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetX, number vType, number tType, number Axis nil
Spring.SetFeatureDirection featureID, x, y, z nil
Spring.SetFeatureHealth featureID, number health nil
Spring.SetFeatureNoSelect featureID, boolean noSelect nil
Spring.SetFeaturePosition featureID, x, y, z [, boolean snapToGround] nil
Spring.SetFeatureReclaim featureID, number reclaimLeft nil
Spring.SetFeatureResurrect string facing ] nil
Spring.SetHeightMap can only be called in SetHeightMapFunc x, z, number height [,number terraform = 1] number absHeightDiff
Spring.SetHeightMapFunc lua_function [, arg1 ,[ arg2 [, ... ] ] number absTotalHeightMapAmountChanged
Spring.SetMapSquareTerrainType x, z, int newType int oldType
Spring.SetNoPause boolean noPause nil
Spring.SetProjectileCEG number projID, string ceg_name nil
Spring.SetProjectileCollision number projID nil
Spring.SetProjectileGravity number projID [, number grav = 0] nil
Spring.SetProjectileMoveControl disables engine movecontrol, so lua can fully control the physics number projID, boolean enable nil
Spring.SetProjectilePosition number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] nil
Spring.SetProjectileSpinAngle number projID [, number spinAngle = 0] nil
Spring.SetProjectileSpinSpeed number projID [, number speed = 0] nil
Spring.SetProjectileSpinVec number projID [, number x = 0 [, number y = 0 [, number z = 0]]] nil
Spring.SetProjectileVelocity number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] nil
Spring.SetSmoothMesh can only be called in SetSmoothMeshFunc x, z, number height [,number terraform = 1] number absHeightDiff
Spring.SetSmoothMeshFunc lua_function [, arg1 ,[ arg2 [, ... ] ] number absTotalHeightMapAmountChanged
Spring.SetTeamResource teamID, string resource, number amount nil
Spring.SetTeamShareLevel "energy", number amount nil
Spring.SetTerrainTypeData int typeIndex[, number speedTanks = nil ][, number speedKBOTs = nil ][, number speedHovers = nil ][, number speedShips = nil ] boolean true
Spring.SetUnitAlwaysVisible unitID, boolean alwaysVisible nil
Spring.SetUnitArmored unitID, boolean armored nil
Spring.SetUnitBlocking unitID, boolean blocking [, boolean collide ] nil
Spring.SetUnitBuildSpeed number builderID, number buildSpeed, [ number repairSpeed [, number reclaimSpeed [,number resurrectSpeed [, number captureSpeed [, number terraformSpeed ]] ]]] nil
Spring.SetUnitCOBValue unitID, number COBValue, number param1 [,number param2] nil
Spring.SetUnitCloak number scriptCloak, [ number decloakDistance | boolean decloakAbs ] nil
Spring.SetUnitCollisionVolumeData unitID, number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetX, number vType, number tType, number Axis nil
Spring.SetUnitCosts unitID, { [ buildTime = number amount ], [ metalCost = number amount ], [ energyCost = number amount ]} nil
Spring.SetUnitExperience unitID, number experience nil
Spring.SetUnitFlanking unitID, string "mode", number mode nil
Spring.SetUnitFuel unitID, number fuel nil
Spring.SetUnitHealth { [ health = number health ],[ capture = number capture ],[ paralyze = number paralyze ],[ build = number build ] } nil
Spring.SetUnitLineage Removed from version 0.83.x unitID, number teamID [, boolean isRoot] nil
Spring.SetUnitLosMask table losTypes nil
Spring.SetUnitLosState table losTypes nil
Spring.SetUnitMaxHealth unitID, number maxHealth nil
Spring.SetUnitMetalExtraction unitID, number depth [,number range] nil
Spring.SetUnitMoveGoal used by default commands to get in build-,attackrange etc. unitID, x, y, z, [, number radius = 0 [, number speed = unit] ] nil
Spring.SetUnitNeutral unitID, boolean neutral nil
Spring.SetUnitPhysics unitIDnumber posx, number posy, number posz,number velx, number vely, number velz,number rotx, number roty, number rotz, nil
Spring.SetUnitPieceCollisionVolumeData unitID, number pieceIndex, boolean affectLocal, boolean affectGlobal, boolean enableLocal, boolean enableGlobal, number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetZ, number vType, number Axis nil
Spring.SetUnitPosition unitID, x, number z [, boolean alwaysAboveSea] nil
Spring.SetUnitResourcing unitID, resourceName, resourceAmount
unitID, resourceName=resourceAmount
nil
Spring.SetUnitRotation unitID, number rotx, number roty, number rotz nil
Spring.SetUnitSensorRadius unitID, string type, number radius number newRadius
Spring.SetUnitShieldState unitID, [, number weaponID = -1] [, boolean enabled] [, number power] nil
Spring.SetUnitSonarStealth unitID, boolean sonarStealth nil
Spring.SetUnitStealth unitID, boolean stealth nil
Spring.SetUnitStockpile unitID, [, number stockpile [, number buildPercent ]] nil
Spring.SetUnitTarget x, y, z, [ boolean dgun = false ] nil
Spring.SetUnitToFeature boolean tofeature nil
Spring.SetUnitTooltip unitID, string "tooltip" nil
Spring.SetUnitTravel unitID, number travel [, number travelPeriod] nil
Spring.SetUnitVelocity unitID, number velx, number vely, number velz nil
Spring.SetUnitWeaponState table states nil
Spring.ShareTeamResource 0.82 and later number teamID_src, number teamID_recv, resource, number amount nil
Spring.SpawnCEG string "cegname", number posX = 0, number posY = 0, number posZ = 0, number dirX = 0, number dirY = 0, number dirZ = 0, number radius = 0, number damage = 0 nil
Spring.TransferFeature featureID number teamID nil
Spring.TransferUnit unitID, numer newTeamID,[boolean given = true] nil
Spring.UseTeamResource { metal = number amount, energy = number amount} boolean hadEnough
Spring.UseUnitResource unitID, resourceName, resourceAmount
unitID, resourceName = resourceAmount}
boolean success
Spring.GetAllyTeamList { [1] = number allyTeamID, etc... }