# 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:
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... } |