Lua SyncedCtrl

Development < Lua Scripting < Lua SyncedCtrl

Game End

Spring.KillTeam New in version 0.83.x

 ( number teamID ) -> nil

will declare a team to be dead ( no further orders can be assigned to such teams's units )

Spring.GameOver New in version 0.83.x

 ( [ [1] = allyTeamID1, [2] = allyTeamID2, .. ] ) -> nil

will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed

Resources

Spring.AddTeamResource

 ( number teamID, string "metal" | "energy", number amount ) -> nil

Spring.UseTeamResource

 ( number teamID, 
   string "metal" | "energy",number amount |
   { metal = number amount, energy = number amount}
 ) -> nil | boolean hadEnough

Spring.SetTeamResource

 ( number teamID, string res, number amount ) -> nil

 possible values for res are:
   "m"  = metal
   "e"  = energy
   "ms"  = metal storage
   "es"  = energy storage

Spring.SetTeamShareLevel

 ( number teamID, string "metal" | "energy", number amount ) -> nil

Spring.ShareTeamResource 0.82 and later

 ( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

Unit Handling

Spring.CreateUnit note: offmap positions are clamped! (you still can use MoveCtrl todo so)

 ( string "defName" | number unitDefID,
   number x, number y, number z,
   (number facing | string "facing"),
   number teamID,
   [boolean build = false] ) -> number unitID

 possible values for facing are:
   "south" | "s" | 0
   "east"  | "e" | 1
   "north" | "n" | 2
   "west"  | "w" | 3
 if build is true the unit is created in "being built" state, with buildProgress = 0

Spring.DestroyUnit

 ( number unitID,
   [boolean selfd = false,]
   [boolean reclaimed = false,]
   [number attackerID] ) -> nil

selfd := makes the unit act like it self-destructed
reclaimed := don't show any DeathSequences, don't leave a wreckage.
  NOTE this does _not_ give back the resources to the team!

Spring.TransferUnit

 ( number unitID,
   numer newTeamID,
   [boolean given = true] ) -> nil

if given=false, the unit is captured

Unit Control

Spring.SetUnitCosts

 ( number unitID, { 
    [ buildTime  = number amount ],
    [ metalCost  = number amount ],
    [ energyCost = number amount ]
  } ) -> nil

Spring.SetUnitTooltip

 ( number unitID, string "tooltip" ) -> nil

Spring.SetUnitHealth

 ( number unitID,
   number health |
   { [ health   = number health ],
     [ capture  = number capture ],
     [ paralyze = number paralyze ],
     [ build    = number build ] }
 ) -> nil

Spring.SetUnitMaxHealth

 ( number unitID, number maxHealth ) -> nil

Spring.AddUnitDamage

 ( number unitID, number damage
   [, number paralyze = 0 [, number attackerID = -1 [, number weaponID = -1
     [, number impulse_x [, number impulse_y [, number impulse_z ]]] ]]] ) -> nil

Spring.SetUnitStockpile

 ( number unitID [, number stockpile [, number buildPercent ]]) -> nil

Spring.SetUnitExperience

 ( number unitID, number experience ) -> nil

Spring.SetUnitFuel

 ( number unitID, number fuel ) -> nil

Spring.SetUnitLineage Removed from version 0.83.x

 ( number unitID, number teamID [, boolean isRoot] ) -> nil

Spring.SetUnitNeutral

 ( number unitID, boolean neutral ) -> nil

Spring.SetUnitTarget

 ( number unitID,
   number enemyUnitID | number x, number y, number z,
   [ boolean dgun = false ] ) -> nil

Spring.SetUnitBlocking

 ( number unitID, boolean blocking [, boolean collide ] ) -> nil

Spring.SetUnitMetalExtraction

 ( number unitID, number depth [,number range] ) -> nil

Spring.SetUnitBuildSpeed

 ( number builderID,
   number buildSpeed, [ number repairSpeed [, number reclaimSpeed
 [,number resurrectSpeed [, number captureSpeed [, number terraformSpeed ]] ]]] ) -> nil

Spring.SetUnitArmored

 ( number unitID, boolean armored ) -> nil

Spring.SetUnitShieldState

 ( number unitID [, number weaponID = -1] [, boolean enabled] [, number power] ) -> nil

Spring.SetUnitFlanking

 ( number unitID, string "mode", number mode ) -> nil
 ( number unitID, string "moveFactor", number factor) -> nil
 ( number unitID, string "minDamage", number minDamage ) -> nil
 ( number unitID, string "mazDamage", number maxDamage ) -> nil
 ( number unitID, string "dir", number x, number y, number z) -> nil

Spring.SetUnitWeaponState

 ( number unitID, number weaponNum, table states ) -> nil
 ( number unitID, number weaponNum, string key, number value ) -> nil
 format of the states table:
   {
     ["reloadState" = number value,]
     ["reloadFrame" = number value,]   (synonym for reloadState!)
     ["reloadTime"  = number value,]
     ["accuracy"    = number value,]
     ["sprayAngle"  = number value,]
     ["range"       = number value,]
     ["projectileSpeed" = number value,]
     ["burst" = number value,]
     ["burstRate" = number value,]
     ["projectiles" = number value,]
     ["aimReady" = number value,] (<>0.0f := true)
   }
 

Spring.SetUnitCollisionVolumeData

 ( number unitID, number scaleX, number scaleY, number scaleZ,
   number offsetX, number offsetY, number offsetX,
   number vType, number tType, number Axis
 ) -> nil
 enum COLVOL_TYPES {
     COLVOL_TYPE_DISABLED = -1,
     COLVOL_TYPE_ELLIPSOID = 0,
     COLVOL_TYPE_CYLINDER,
     COLVOL_TYPE_BOX,
     COLVOL_TYPE_SPHERE,
     COLVOL_TYPE_FOOTPRINT, // intersection of sphere and footprint-prism
     COLVOL_NUM_TYPES       // number of non-disabled collision volume types
   };
   enum COLVOL_TESTS {
     COLVOL_TEST_DISC = 0,
     COLVOL_TEST_CONT = 1,
     COLVOL_NUM_TESTS = 2   // number of tests
   };
   enum COLVOL_AXES {
     COLVOL_AXIS_X   = 0,
     COLVOL_AXIS_Y   = 1,
     COLVOL_AXIS_Z   = 2,
     COLVOL_NUM_AXES = 3    // number of collision volume axes
   };
 

Spring.SetUnitPieceCollisionVolumeData

 ( number 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.SetUnitTravel

 ( number unitID, number travel [, number travelPeriod] ) -> nil

Spring.SetUnitMoveGoal used by default commands to get in build-,attackrange etc.

 ( number unitID, number x, number y, number z,
   [, number radius = 0 [, number speed = unit->maxSpeed * 2 ] ] ) -> nil

Spring.SetUnitPhysics

 ( number unitID,
   number posx, number posy, number posz,
   number velx, number vely, number velz,
   number rotx, number roty, number rotz,
 ) -> nil

Spring.SetUnitPosition

 ( number unitID, number x, number z [, boolean alwaysAboveSea] ) -> nil

Spring.SetUnitVelocity

 ( number unitID, number velx, number vely, number velz ) -> nil

Spring.SetUnitRotation

 ( number unitID, number rotx, number roty, number rotz ) -> nil

Spring.AddUnitImpulse

 ( number unitID, number x, number y, number z ) -> nil

Spring.AddUnitSeismicPing

 ( number unitID, number pingSize ) -> nil

Spring.RemoveBuildingDecal

 ( number unitID ) -> nil

Unit LOS

Spring.SetUnitCloak

 ( number unitID,
   boolean cloaked | number scriptCloak,
   [ number decloakDistance | boolean decloakAbs ] ) -> nil

 
 If the 2nd argument is a number, the value works like this:
  1:=normal cloak
  2:=for free cloak (cost no E)
  3:=for free + no decloaking (except the unit is stunned)
  4>=ultimative cloak (no ecost, no decloaking, no stunned decloak)

 The decloak distance is only changed if the 3th argument is a number or a boolean.
  If the boolean is false it takes the default decloak distance for that unitdef,
  if the boolean is true it takes the absolute value of it.

Spring.SetUnitSonarStealth

 ( number unitID, boolean sonarStealth ) -> nil

Spring.SetUnitStealth

 ( number unitID, boolean stealth ) -> nil

Spring.SetUnitAlwaysVisible

 ( number unitID, boolean alwaysVisible ) -> nil

Spring.SetUnitLosMask

 ( number unitID, number allyTeam, number los | table losTypes ) -> nil

the 3th argument is either the bit-and combination of the following numbers:

 LOS_INLOS     = 1
 LOS_INRADAR   = 2
 LOS_PREVLOS   = 4
 LOS_CONTRADAR = 8

or a table of the following form:

 losTypes = {
   [los = boolean,]
   [radar = boolean,]
   [prevLos = boolean,]
   [contRadar = boolean,]
 }

Spring.SetUnitLosState

 ( number unitID, number allyTeam, number los | table losTypes ) -> nil
 see above for more info on the arguments

Spring.SetUnitSensorRadius

 ( number unitID, string type, number radius ) -> nil | number newRadius
 type can be:
 "los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"

Unit Ressourcing

Spring.SetUnitResourcing

 ( number unitID,
   string res, number amount |
   { res = number amount, ... }
 ) -> nil

 possible values for res are: "[u|c][u|m][m|e]"
      unconditional | conditional
                use | make
              metal | energy

Spring.AddUnitResource

 ( number unitID, string "m" | "e", number amount ) -> nil

Spring.UseUnitResource

 ( number unitID, string "m" | "e", number amount ) -> nil | boolean okay
 ( number unitID, { ["m" | "metal" | "e" | "energy"] = amount, ... } ) -> nil | boolean okay

Feature Handling

Spring.CreateFeature

 ( string "defName" | number featureID, number x, number y, number z
  [,number heading [, number AllyTeamID ]] ) -> number featureID

Spring.DestroyFeature

 ( number featureID ) -> nil

Spring.TransferFeature

 ( number featureID, number teamID ) -> nil

Feature Control

Spring.SetFeatureHealth

 ( number featureID, number health) -> nil

Spring.SetFeatureReclaim

 ( number featureID, number reclaimLeft) -> nil

Spring.SetFeatureResurrect

 ( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil

 possible values for facing are:
   "south" | "s" | 0
   "east"  | "e" | 1
   "north" | "n" | 2
   "west"  | "w" | 3

Spring.SetFeaturePosition

 ( number featureID, number x, number y, number z [, boolean snapToGround]) -> nil

Spring.SetFeatureDirection

 ( number featureID, number x, number y, number z ) -> nil

Spring.SetFeatureNoSelect

 ( number featureID, boolean noSelect ) -> nil

Spring.SetFeatureAlwaysVisible

 ( number featureID, boolean enable ) -> nil

Spring.SetFeatureCollisionVolumeData

 ( number featureID, number scaleX, number scaleY, number scaleZ,
   number offsetX, number offsetY, number offsetX,
   number vType, number tType, number Axis
 ) -> nil
 check Spring.SetUnitCollisionVolumeData for further explanation of the arguments

Lua to COB

Spring.CallCOBScript

 ( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
   -> nil | 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

 ( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
   -> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

Spring.GetCOBScriptID

 ( number unitID, string funcName ) -> nil | number funcID

Note: Don't use Spring.[Get|Set]UnitCOBValue in LUS just because you are familar with it since bos/cob, use the mighty LuaSpringAPI instead!

Spring.GetUnitCOBValue

 ( number unitID [, boolean splitData=false], number COBValue
   [, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
 -> number result | number result1, number result2
 you find the possible values for `COBValue` in Lua_ConstCOB

Spring.SetUnitCOBValue

 ( number unitID, number COBValue, number param1 [,number param2] ) -> nil
 you find the possible values for `COBValue` in Lua_ConstCOB

Give Order

Spring.GiveOrderToUnit

 ( number unitID,
   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.GiveOrderToUnitArray

 ( unitArray = { [1] = unitID, etc... },
   number cmdID,
   params = {number, etc...},
   options = {"alt", "ctrl", "shift", "right"} ) -> nil

Spring.GiveOrderArrayToUnitMap

 ( unitMap = { [number unitID] = dontCare, etc... },
   orderArray = {
     { number cmdID,
       {number, etc...},     params
       {"alt", "ctrl", "shift", "right"}   options
     }, ..
   }
 ) -> nil

Spring.GiveOrderArrayToUnitArray

 ( unitArray = { [1] = number unitID, etc... },
   orderArray = {
     { number cmdID,
       {number, etc...},    params
       {"alt", "ctrl", "shift", "right"}   options
     }, ..
   }
 ) -> nil

Ground

Grass

Spring.AddGrass

 ( number x, number y, number z ) -> nil

Spring.RemoveGrass

 ( number x, number y, number z ) -> nil

Heightmap

Spring.LevelHeightMap

 ( number x1, number z1 [, number x2, number z2], number height ) -> nil

Spring.AdjustHeightMap (heightmap[x][z] += height;)

 ( number x1, number z1 [, number x2, number z2], number height ) -> nil

Spring.RevertHeightMap

 ( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil

Spring.SetHeightMapFunc

 ( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged

Spring.AddHeightMap can only be called in SetHeightMapFunc()

 ( number x, number z, number height ) -> nil | number newHeight

Spring.SetHeightMap can only be called in SetHeightMapFunc()

 ( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff

the terraform argument is a scaling factor: so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.

Spring.LevelSmoothMesh

 ( number x1, number z1 [, number x2, number z2], number height ) -> nil

Spring.AdjustSmoothMesh

 ( number x1, number z1 [, number x2, number z2], number height ) -> nil

Spring.RevertSmoothMesh

 ( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil

Spring.SetSmoothMeshFunc

 ( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged

Spring.AddSmoothMesh can only be called in SetSmoothMeshFunc()

 ( number x, number z, number height ) -> nil | number newHeight

Spring.SetSmoothMesh can only be called in SetSmoothMeshFunc()

 ( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff

TerrainTypes

Spring.SetMapSquareTerrainType

 ( number x, number z, int newType ) -> nil | int oldType

Spring.SetTerrainTypeData

 ( int typeIndex
 [, number speedTanks = nil ]
 [, number speedKBOTs = nil ]
 [, number speedHovers = nil ]
 [, number speedShips = nil ] ) -> nil | boolean true

Command Descriptions

Doesn't work in unsynced code!

Spring.EditUnitCmdDesc

 ( number unitID, number cmdDescID, table cmdArray ) -> nil

 structure of cmdArray:
 {
   [ id          = int ],
   [ type        = int ],
   [ name        = string ],
   [ action      = string ],
   [ tooltip     = string ],
   [ texture     = string ],
   [ cursor      = string ],
   [ hidden      = boolean ],
   [ disabled    = boolean ],
   [ showUnique  = boolean ],
   [ onlyTexture = boolean ],
   [ params      = { string = string, ... } ]
 }

Spring.InsertUnitCmdDesc

 ( number unitID [, number cmdDescID ] , table cmdArray ) -> nil

Spring.RemoveUnitCmdDesc

 ( number unitID [, number cmdDescID ] ) -> nil

Other

Spring.SetNoPause

 ( boolean noPause ) -> nil

Spring.SetUnitToFeature

 ( boolean tofeature ) -> nil

Spring.SetExperienceGrade

 ( number expGrade
  [, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]] ) -> nil

 expGrade defines how often UnitExperience() will be called,
  it is based on the following equation:
    (int) [exp/(exp+1)] / expGrade
  If this integer differs from the one before the experience change
  it will call UnitExperience().
 Also those 3 last params are only available in .cheat
 

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

Projectiles

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.SetProjectileVelocity

 ( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil

Spring.SetProjectileCollision

 ( number projID ) -> nil

Spring.SetProjectileGravity

 ( number projID [, number grav = 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.SetProjectileCEG

 ( number projID, string ceg_name ) -> nil