Lua SyncedCtrl: Difference between revisions

From Spring
Jump to navigationJump to search
← Older edit
Flozi (talk | contribs)
0 edits
92.0 - add optional 4th argument to Spring.AddUnitImpulse to control a unit's impulse decay-rate (now unhardcoded)
Raaar (talk | contribs)
0 edits
 
(74 intermediate revisions by 14 users not shown)
Line 2: Line 2:


= Game End =
= Game End =
'''Spring.KillTeam''' {{new|83.0}}
  ( number teamID ) -> nil
<span class="note">Will declare a team to be dead ( no further orders can be assigned to such teams's units ), Gaia team cannot be killed.</span>


'''Spring.GameOver''' {{new|83.0}}
{{LuaCallout
  ( {number allyTeamID1, number allyTeamID2, ...} ) -> nil
|prefix = Spring.
<span class="note">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</span>
|name = KillTeam
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}<br> Will declare a team to be dead ( no further orders can be assigned to such teams's units ), Gaia team cannot be killed.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = GameOver
|arg1 = {{type|number}} allyTeamID1
|arg2 = {{type|number}} allyTeamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}<br> 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.
}}
 
= RulesParams =
<span class=warning>String values are new since 95.0. Attention: Numeric paramValues in quotes will be converted to number.</span>
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <span class=note>Possible keys for the losAccess table are:
    `private` : only readable by the ally (default)
    `allied`  : readable by ally + ingame allied
    `inlos`  : readable if the unit is in LOS
    `inradar` : readable if the unit is in AirLOS
    `public`  : readable by all
  note: if one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it<br/>    can read params with `inradar=true` even if the param has `inlos=false`)
  note2: all GameRulesParam are public, TeamRulesParams can just be `private`,`allied`<br/>    and/or `public`
  note3: You can read RulesParams from '''any''' Lua enviroments! With those losAccess<br/>    policies you can limit their access.</span>
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <span class=warning>New since 102.0.</span><br>See above for further documentation of losAccess.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetGameRulesParam
|arg1 = {{type|string}} paramName
|arg2 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg3 = {{type|table}} losAccess {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}


= Resources =
= 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'''
{{LuaCallout
  ( number teamID, string res, number amount ) -> nil
|prefix = Spring.
<font color="#55ee99">
|name = AddTeamResource
  possible values for res are:
|arg1 = {{type|number}} teamID
    "m"  = metal
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
    "e"  = energy
|arg3 = {{type|number}} amount
    "ms"  = metal storage
|arg4 =
    "es"  = energy storage
|arg5 =
</font>
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Adds metal or energy resources to the specified team.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Consumes metal and/or energy resources of the specified team.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible values for res are:<br>"m"  = metal<br>"e"  = energy<br>"ms"  = metal storage<br>"es"  = energy storage<br>
}}


'''Spring.SetTeamShareLevel'''
  ( number teamID, string "metal" | "energy", number amount ) -> nil


'''Spring.ShareTeamResource''' <span class=note>0.82 and later</span>
{{LuaCallout
  ( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil
|prefix = Spring.
|name = SetTeamShareLevel
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = ShareTeamResource
|arg1 = {{type|number}} teamID_src
|arg2 = {{type|number}} teamID_recv
|arg3 = {{type|string}} "metal" {{pipe}} "energy"
|arg4 = {{type|number}} amount
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Transfers resources between two teams.
}}
 
= Teams =
 
 
{{LuaCallout
|prefix = Spring.
|name = SetAlly
|arg1 = {{type|number}} firstAllyTeamID
|arg2 = {{type|number}} secondAllyTeamID
|arg3 = {{type|bool}} ally
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}}<br>Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = AssignPlayerToTeam
|arg1 = {{type|number}} playerID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}}<br>Assigns a player to a team.
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetGlobalLos
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|bool}} globallos
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}<br>Changes access to global line of sight for a team and its allies.
}}


= Unit Handling =
= Unit Handling =
'''Spring.CreateUnit''' <font color="#55ee99">note: offmap positions are clamped! (you still can use MoveCtrl todo so)</font>
  ( string "defName" | number unitDefID,
    number x, number y, number z,
    (number facing | string "facing"),
    number teamID
    [, boolean build = false
    [, boolean flattenGround = true
    [, number unitID
    [, number builderID ]]]]) -> number unitID
<font color="#55ee99">
  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
  unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with a specific ID.
</font>


'''Spring.DestroyUnit'''
{{LuaCallout
  ( number unitID
|prefix = Spring.
    [, boolean selfd = false]
|name = CreateUnit
    [, boolean reclaimed = false]
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number }} unitDefID
    [, number attackerID ] ) -> nil
|arg2 = {{type|number}} x
<font color="#55ee99">
|arg3 = {{type|number}} y
selfd := makes the unit act like it self-destructed
|arg4 = {{type|number}} z
reclaimed := don't show any DeathSequences, don't leave a wreckage.
|arg5 = {{type|string}} "facing" {{pipe}} {{type|number }} facing
  NOTE this does _not_ give back the resources to the team!
|arg6 = {{type|number}} teamID {{bracket}}
</font>
|arg7 = {{type|bool}} build = false {{bracket}}
|arg8 = {{type|bool}} flattenGround = true {{bracket}}
|arg9 = {{type|number}} builderID {{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|number}} unitID {{pipe}} {{type|nil}} (meaning unit was not created)
|info = Offmap positions are clamped! Use MoveCtrl to move to such positions.<br>Possible values for facing are:<br>"south" {{pipe}} "s" {{pipe}} 0<br>"east"  {{pipe}} "e" {{pipe}} 1<br>"north" {{pipe}} "n" {{pipe}} 2<br>"west"  {{pipe}} "w" {{pipe}} 3<br><br>If build is true, the unit is created in "being built" state with buildProgress = 0<br>unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with a specific ID.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = DestroyUnit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} selfd = false {{bracket}}
|arg3 = {{type|bool}} reclaimed = false {{bracket}}
|arg4 = {{type|number}} attackerID {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = selfd := Makes the unit act like it self-destructed.<br>reclaimed := Don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
}}


'''Spring.TransferUnit'''
  ( number unitID,
    numer newTeamID
    [, boolean given = true ] ) -> nil
<font color="#55ee99">if given=false, the unit is captured</font>


{{LuaCallout
|prefix = Spring.
|name = TransferUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} newTeamID {{bracket}}
|arg3 = {{type|bool}} given = true {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If given=false, the unit is captured.
}}


== Unit Control ==
== Unit Control ==
'''Spring.SetUnitCosts'''
  ( number unitID, {
    [ buildTime  = number amount ],
    [ metalCost  = number amount ],
    [ energyCost = number amount ]
  } ) -> nil


'''Spring.SetUnitTooltip'''
{{LuaCallout
  ( number unitID, string "tooltip" ) -> nil
|prefix = Spring.
|name = SetUnitCosts
|arg1 = {{type|number}} unitID  
|arg2 = { {{bracket}} buildTime = {{type|number}} amount {{rbracket}}
|arg3 = {{bracket}} metalCost = {{type|number}} amount  {{rbracket}}
|arg4 = {{bracket}} energyCost = {{type|number}} amount {{rbracket}} }
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


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


'''Spring.SetUnitMaxHealth'''
{{LuaCallout
  ( number unitID, number maxHealth ) -> nil
|prefix = Spring.
|name = SetUnitTooltip
|arg1 = {{type|number}} unitID  
|arg2 = {{type|string}} "tooltip"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''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'''
{{LuaCallout
  ( number unitID, number experience ) -> nil
|prefix = Spring.
|name = SetUnitHealth
|arg1 = {{type|number}} unitID  
|arg2 = {{type|number}} health {{pipe}} { {{bracket}} health = {{type|number}} health {{rbracket}}
|arg3 = {{bracket}} capture  = {{type|number}} capture  {{rbracket}}
|arg4 = {{bracket}} paralyze = {{type|number}} paralyze {{rbracket}}
|arg5 = {{bracket}} build    = {{type|number}} build {{rbracket}} }
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.SetUnitFuel'''
  ( number unitID, number fuel ) -> nil


'''Spring.SetUnitCrashing''' {{new|83.0}}
{{LuaCallout
  ( number unitID, boolean crashing ) -> boolean success
|prefix = Spring.
|name = SetUnitMaxHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxHealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.SetUnitLineage''' <span class="warning"> Removed from version 83.0</span> <br>
  ( number unitID, number teamID [, boolean isRoot] ) -> nil


'''Spring.SetUnitNeutral'''
{{LuaCallout
  ( number unitID, boolean neutral ) -> nil
|prefix = Spring.
|name = AddUnitDamage
|arg1 = {{type|number}} unitID  
|arg2 = {{type|number}} damage {{bracket}}
|arg3 = {{type|number}} paralyze = 0 {{bracket}}
|arg4 = {{type|number}} attackerID = -1 {{bracket}}
|arg5 = {{type|number}} weaponID = -1 {{bracket}}
|arg6 = {{type|number}} impulse_x {{bracket}}
|arg7 = {{type|number}} impulse_y {{bracket}}
|arg8 = {{type|number}} impulse_z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = The number in the paralyze parameter equals to the paralyzetime in the WeaponDef.
}}


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


'''Spring.SetUnitBlocking''' <span class="warning">crushable new in version 85.0</span>
{{LuaCallout
  ( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil
|prefix = Spring.
|name = SetUnitStockpile
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} stockpile {{bracket}}
|arg3 = {{type|number}} buildPercent {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.SetUnitMetalExtraction'''
  ( number unitID, number depth [,number range] ) -> nil


'''Spring.SetUnitBuildSpeed'''
{{LuaCallout
  ( number builderID,
|prefix = Spring.
    number buildSpeed, [ number repairSpeed [, number reclaimSpeed
|name = SetUnitExperience
  [,number resurrectSpeed [, number captureSpeed [, number terraformSpeed ]] ]]] ) -> nil
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} experience
|arg3 = {{type|number}} buildPercent
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.SetUnitNanoPieces''' {{new|92.0}}
  ( number builderID, table pieces ) -> nil


'''Spring.SetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
{{LuaCallout
  ( number unitID, boolean armored [, number armorMultiple] ) -> nil
|prefix = Spring.
|name = SetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} fuel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|101.0}}
}}


'''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'''
{{LuaCallout
  ( number unitID, number weaponNum, table states ) -> nil
|prefix = Spring.
  ( number unitID, number weaponNum, string key, number value ) -> nil
|name = SetUnitCrashing
  <span class="note">format of the states table:
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} crashing
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|83.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} teamID {{bracket}}
|arg3 = {{type|bool}} isRoot {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} neutral
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x {{pipe}} {{type|nil}}
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|bool}} dgun = false {{bracket}}
|arg6 = {{type|bool}} userTarget = false {{bracket}}
|arg7 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} enemyUnitID {{pipe}} {{type|nil}} {{bracket}}
|arg3 = {{type|bool}} dgun = false {{bracket}}
|arg4 = {{type|bool}} userTarget = false {{bracket}}
|arg5 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Defines a unit's target. Nil as 2nd argument drops the unit's current target.<br><span class="warning">UserTarget & success new in version 95.0, setting nil target new in version 99.0, weaponNum new in version 102.0.</span>
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxRange
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitMass
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} isblocking
|arg3 = {{type|bool}} isSolidObjectCollidable
|arg4 = {{type|bool}} isProjectileCollidable
|arg5 = {{type|bool}} isRaySegmentCollidable
|arg6 = {{type|bool}} crushable
|arg7 = {{type|bool}} blockEnemyPushing
|arg8 = {{type|bool}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}<br>Changed parameters.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} depth {{bracket}}
|arg3 = {{type|number}} range {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Parameter "depth" corresponds to metal extraction rate. Range value is similar to "extractsMetal" in unitDefs.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitBuildSpeed
|arg1 = {{type|number}} builderID
|arg2 = {{type|number}} buildSpeed {{bracket}}
|arg3 = {{type|number}} repairSpeed {{bracket}}
|arg4 = {{type|number}} reclaimSpeed{{bracket}}
|arg5 = {{type|number}} resurrectSpeed {{bracket}}
|arg6 = {{type|number}} captureSpeed {{bracket}}
|arg7 = {{type|number}} terraformSpeed {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitNanoPieces
|arg1 = {{type|number}} builderID
|arg2 = {{type|table}} pieces
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|92.0}}<br>This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end<br>Use it!
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = UnitAttach
|arg1 = {{type|number}} transporterID
|arg2 = {{type|number}} passengerID
|arg3 = {{type|number}} pieceNum
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = UnitDetach
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = UnitDetachFromAir
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitLoadingTransport
|arg1 = {{type|number}} passengerID
|arg2 = {{type|number}} transportID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}<br>Disables collisions between the two units to allow colvol intersection during the approach.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceParent
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} AlteredPiece
|arg3 = {{type|number}} ParentPiece
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}<br>Changes the pieces hierarchy of a unit by attaching a piece to a new parent.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 = {{type|table }} matrix
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}<br>Sets the local (i.e. parent-relative) matrix of the given piece if any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed (matrix should be an array of 16 floats, but is not otherwise sanity-checked).
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} armored {{bracket}}
|arg3 = {{type|number}} armorMultiple {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <span class="warning">armorMultiple new in version 0.83.x</span>
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{bracket}}
|arg3 = {{type|bool}} enabled {{bracket}}
|arg4 = {{type|number}} power {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode"
|arg3 = {{type|number }} mode
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "moveFactor"
|arg3 = {{type|number }} factor
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "minDamage"
|arg3 = {{type|number }} minDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "maxDamage"
|arg3 = {{type|number }} maxDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 = {{type|number }} x
|arg4 = {{type|number }} y
|arg5 = {{type|number }} z
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table }} states  
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string }} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<span class="note">Format of the states table:
     {
     {
       ["reloadState" = number value,]
       ["reloadState"     = number value,]
       ["reloadFrame" = number value,]   (synonym for reloadState!)
       ["reloadFrame"     = number value,] (synonym for reloadState!)
       ["reloadTime" = number value,]
       ["reloadTime"     = number value,]
       ["accuracy"   = number value,]
       ["accuracy"       = number value,]
       ["sprayAngle" = number value,]
       ["sprayAngle"     = number value,]
       ["range"       = number value,]
       ["range"           = number value,] (*)
       ["projectileSpeed" = number value,]
       ["projectileSpeed" = number value,]
       ["burst" = number value,]
       ["burst"           = number value,]
       ["burstRate" = number value,]
       ["burstRate"       = number value,]
       ["projectiles" = number value,]
       ["projectiles"     = number value,]
       ["aimReady" = number value,] <span class=note>(<>0.0f := true)</span>
      ["salvoLeft"      = number value,]
      ["nextSalvo"      = number value,]
       ["aimReady"       = number value,] (<>0.0f := true)
     }
     }
  (*) if you change the range of a weapon with dynamic damage
  make sure you use SetUnitWeaponDamages to change dynDamageRange as well.
   </span>
   </span>
'''Spring.SetUnitCollisionVolumeData'''
 
  ( number unitID, number scaleX, number scaleY, number scaleZ,
 
    number offsetX, number offsetY, number offsetX,
{{LuaCallout
    number vType, number tType, number Axis
|prefix = Spring.
  ) -> nil
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
<span class="note">Format of the damages table:
  {
      ["paralyzeDamageTime" = number value,] 
      ["impulseFactor"      = number value,]
      ["impulseBoost"      = number value,]
      ["craterMult"        = number value,]
      ["craterBoost"        = number value,]
      ["dynDamageExp"      = number value,]
      ["dynDamageMin"      = number value,]
      ["dynDamageRange"    = number value,]
      ["dynDamageInverted"  = number value,] (<>0.0f := true)
      ["craterAreaOfEffect" = number value,]
      ["damageAreaOfEffect" = number value,]
      ["edgeEffectiveness"  = number value,]
      ["explosionSpeed"    = number value,]
      [number armorType    = number value,] (changes the damage against this armor type)
    }
  </span>
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
   <span class="note">enum COLVOL_TYPES {
   <span class="note">enum COLVOL_TYPES {
       COLVOL_TYPE_DISABLED = -1,
       COLVOL_TYPE_DISABLED = -1,
Line 195: Line 1,005:
   </span>
   </span>


'''Spring.SetUnitPieceCollisionVolumeData'''
  ( number unitID, number pieceIndex, boolean enableLocal,
    number scaleX, number scaleY, number scaleZ,
    number offsetX, number offsetY, number offsetZ,
    number vType, number Axis
  ) -> nil


'''Spring.SetUnitTravel'''
{{LuaCallout
  ( number unitID, number travel [, number travelPeriod] ) -> nil
|prefix = Spring.
|name = SetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ {{bracket}}
|arg6 = {{type|number}} volumeType {{bracket}}
|arg7 = {{type|number}} primaryAxis {{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} travel {{bracket}}
|arg3 = {{type|number}} travelPeriod {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitMoveGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{bracket}}
|arg4 = {{type|number}} moveSpeed {{bracket}}
|arg5 = {{type|bool}} moveRaw {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <span class="note">Used by default commands to get in build-, attackrange etc.</span><br>{{new|98.0}} <span class="note">moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]</span>
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitLandGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}<br>Used in conjunction with {{name|Spring.UnitAttach}} et al. to re-implement old airbase & fuel system in Lua.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = ClearUnitGoal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|102.0}}
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <span class="warning">Drag new in version 95.0</span>
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitPosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|bool}} alwaysAboveSea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|90.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} velX
|arg3 = {{type|number}} velY
|arg4 = {{type|number}} velZ
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} yaw
|arg3 = {{type|number}} pitch
|arg4 = {{type|number}} roll
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = AddUnitImpulse
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} decayRate {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = AddUnitSeismicPing
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pingSize
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetGroundMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|table}} properties
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this function to control movement properties for ground units. Known properties : maxSpeed, maxWantedSpeed, turnRate, ... (TODO fix/update)
}}


'''Spring.SetUnitMoveGoal'''  <span class="note">used by default commands to get in build-,attackrange etc.</span>
  ( 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'''
{{LuaCallout
  ( number unitID, number x, number z [, boolean alwaysAboveSea] ) -> nil
|prefix = Spring.
|name = SetAirMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|table}} properties
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this function to control movement properties for non-gunship air units. Known properties : maxSpeed, maxWantedSpeed, ... (TODO fix/update)
}}


'''Spring.SetUnitDirection''' {{new|90.0}}
  ( number unitID, number x, number y, number z ) -> nil


'''Spring.SetUnitVelocity'''
  ( number unitID, number velx, number vely, number velz ) -> nil


'''Spring.SetUnitRotation'''
{{LuaCallout
  ( number unitID, number rotx, number roty, number rotz ) -> nil
|prefix = Spring.
|name = SetGunshipMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|table}} properties
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this function to control movement properties for air gunships. Known properties : maxSpeed, maxWantedSpeed, turnRate, ... (TODO fix/update)
}}


'''Spring.AddUnitImpulse'''
  ( number unitID, number x, number y, number z [, decayRate ] ) -> nil


'''Spring.AddUnitSeismicPing'''
{{LuaCallout
  ( number unitID, number pingSize ) -> nil
|prefix = Spring.
|name = RemoveBuildingDecal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.RemoveBuildingDecal'''
  ( number unitID ) -> nil


'''Spring.SetUnitMidAndAimPos''' {{new|89.0}}
  ( number unitID,
    number mpx, number mpy, number mpz,
    number apx, number apy, number apz,
    [, boolean relative] ) -> boolean success


<font color="#55ee99">
{{LuaCallout
mpx, mpy, mpz: new middle position of unit
|prefix = Spring.
|name = SetUnitMidAndAimPos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}<br>mpx, mpy, mpz: New middle position of unit<br>apx, apy, apz: New position that enemies aim at on this unit<br>relative: Are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!
}}


apx, apy, apz: new position that enemies aim at on this unit


relative: are the new coordinates relative to world or unit coordinates?
{{LuaCallout
</font>
|prefix = Spring.
|name = SetUnitRadiusAndHeight
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}




'''Spring.SetUnitRadiusAndHeight''' {{new|89.0}}
{{LuaCallout
  ( number unitID, number radius, number height ) -> boolean success
|prefix = Spring.
|name = UnitWeaponFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = UnitWeaponHoldFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


== Unit LOS ==
== Unit LOS ==
'''Spring.SetUnitCloak'''
  ( number unitID,
    boolean cloaked | number scriptCloak,
    [ number decloakDistance | boolean decloakAbs ] ) -> nil


  <font color="#55ee99">
{{LuaCallout
  If the 2nd argument is a number, the value works like this:
|prefix = Spring.
  1:=normal cloak
|name = SetUnitCloak
  2:=for free cloak (cost no E)
|arg1 = {{type|number}} unitID
  3:=for free + no decloaking (except the unit is stunned)
|arg2 = {{type|bool}} cloaked {{pipe}} {{type|number}} scriptCloak {{bracket}}
  4>=ultimative cloak (no ecost, no decloaking, no stunned decloak)
|arg3 = {{type|bool}} decloakAbs {{pipe}} {{type|number}} decloakDistance {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If the 2nd argument is a number, the value works like this:<br>1:=normal cloak<br>2:=for free cloak (cost no E)<br>3:=for free + no decloaking (except the unit is stunned)<br>4:=ultimative cloak (no ecost, no decloaking, no stunned decloak)<br><br>The decloak distance is only changed:<br>- if the 3th argument is a number or a boolean.<br>- if the boolean is false it takes the default decloak distance for that unitdef,<br>- if the boolean is true it takes the absolute value of it.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitSonarStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} sonarStealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} stealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitAlwaysVisible
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitLosMask
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los  {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = The 3rd argument is either the bit-and combination of the following numbers:<br>LOS_INLOS    = 1<br>LOS_INRADAR  = 2<br>LOS_PREVLOS  = 4<br>LOS_CONTRADAR = 8<br><br>or a table of the following form:<br>losTypes = {<br>[los = boolean,]<br>[radar = boolean,]<br>[prevLos = boolean,]<br>[contRadar = boolean]<br>}
}}
 


  The decloak distance is only changed if the 3th argument is a number or a boolean.
{{LuaCallout
  If the boolean is false it takes the default decloak distance for that unitdef,
|prefix = Spring.
  if the boolean is true it takes the absolute value of it.</font>
|name = SetUnitLosState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los  {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for more info on the arguments.
}}


'''Spring.SetUnitSonarStealth'''
  ( number unitID, boolean sonarStealth ) -> nil


'''Spring.SetUnitStealth'''
{{LuaCallout
  ( number unitID, boolean stealth ) -> nil
|prefix = Spring.
|name = SetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} type
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newRadius
|info = Type can be:<br>"los", "airLos", "radar", "sonar", "seismic", "radarJammer", "sonarJammer"
}}


'''Spring.SetUnitAlwaysVisible'''
  ( number unitID, boolean alwaysVisible ) -> nil


'''Spring.SetUnitLosMask'''
{{LuaCallout
  ( number unitID, number allyTeam, number los | table losTypes ) -> nil
|prefix = Spring.
<font color="#55ee99">the 3th argument is either the bit-and combination of the following numbers:
|name = SetRadarErrorParams
  LOS_INLOS    = 1
|arg1 = {{type|number}} allyTeamID
  LOS_INRADAR  = 2
|arg2 = {{type|number }} allyteamErrorSize {{bracket}}
  LOS_PREVLOS  = 4
|arg3 = {{type|number}} baseErrorSize {{bracket}}
  LOS_CONTRADAR = 8
|arg4 = {{type|number}} baseErrorMult {{rbracket}}{{rbracket}}
</font><font color="#55ee99">or a table of the following form:
|arg5 =  
  losTypes = {
|arg6 =  
    [los = boolean,]
|arg7 =  
    [radar = boolean,]
|arg8 =  
    [prevLos = boolean,]
|arg9 =  
    [contRadar = boolean,]
|return = {{type|nil}}
  }</font>
|info = {{new|95.0}}
}}


'''Spring.SetUnitLosState'''
  ( number unitID, number allyTeam, number los | table losTypes ) -> nil
  <font color="#55ee99">see above for more info on the arguments</font>


'''Spring.SetUnitSensorRadius'''
{{LuaCallout
  ( number unitID, string type, number radius ) -> nil | number newRadius
|prefix = Spring.
  <font color="#55ee99">type can be:
|name = SetUnitPosErrorParams
  "los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"</font>
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z,
|arg3 = {{type|number}} posErrorDelta.x, {{type|number}} number posErrorDelta.y, {{type|number}} posErrorDelta.z {{bracket}}
|arg4 = {{type|number}} nextPosErrorUpdate {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}


== Unit Resourcing ==
== Unit Resourcing ==
'''Spring.SetUnitResourcing'''
  ( number unitID,
    string res, number amount |
    { res = number amount, ... }
  ) -> nil
<font color="#55ee99">
  possible values for res are: "[u|c][u|m][m|e]"
      unconditional | conditional
                use | make
              metal | energy
</font>


'''Spring.AddUnitResource'''
  ( number unitID, string "m" | "e", number amount ) -> nil


'''Spring.UseUnitResource'''
{{LuaCallout
  ( number unitID, string "m" | "e", number amount ) -> nil | boolean okay
|prefix = Spring.
  ( number unitID, { ["m" | "metal" | "e" | "energy"] = amount, ... } ) -> nil | boolean okay
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = { res = {{type|number}} amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =  Possible values for res are: "[u{{pipe}}c][u{{pipe}}m][m{{pipe}}e]"<br>unconditional {{pipe}} conditional<br>use {{pipe}} make<br>metal {{pipe}} energy
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = AddUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount  
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info = 
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = { {{bracket}} "m" {{pipe}} "metal" {{pipe}} "e" {{pipe}} "energy" {{rbracket}} = amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info = 
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} metal
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =  {{new|97.0}}<br>See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}


= Feature Handling =
= Feature Handling =
'''Spring.CreateFeature'''
  ( string "defName" | number featureDefID,
    number x, number y, number z
    [, number heading
    [, number AllyTeamID
    [, number featureID ]]] ) -> number featureID


'''Spring.DestroyFeature'''
{{LuaCallout
  ( number featureID ) -> nil
|prefix = Spring.
|name = CreateFeature
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number}} featureDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|number}} heading {{bracket}}
|arg4 = {{type|number}} AllyTeamID {{bracket}}
|arg5 = {{type|number}} featureID {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} featureID
|info = 
}}


'''Spring.TransferFeature'''
  ( number featureID, number teamID ) -> nil


{{LuaCallout
|prefix = Spring.
|name = DestroyFeature
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 
}}
{{LuaCallout
|prefix = Spring.
|name = TransferFeature
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 
}}


== Feature Control ==
== Feature Control ==
'''Spring.SetFeatureHealth'''
  ( number featureID, number health) -> nil


'''Spring.SetFeatureReclaim'''
{{LuaCallout
  ( number featureID, number reclaimLeft) -> nil
|prefix = Spring.
|name = SetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} health
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} metal
|arg3 = {{type|number}} energy {{bracket}}
|arg4 = {{type|number}} reclaimTime {{bracket}}
|arg5 = {{type|number}} reclaimLeft {{rbracket}}{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =  {{new|104.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureReclaim
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} reclaimLeft
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 


'''Spring.SetFeatureResurrect'''
{{LuaCallout
  ( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil
|prefix = Spring.
<font color="#55ee99">
|name = SetFeatureResurrect
  possible values for facing are:
|arg1 = {{type|number}} featureID
    "south" | "s" | 0
|arg2 = {{type|number}} unitDefID {{pipe}} {{type|string}} unitDefName {{bracket}}
    "east"  | "e" | 1
|arg3 = {{type|number}} facing {{pipe}} {{type|string}} "facing" {{bracket}}
    "north" | "n" | 2
|arg4 = {{type|number}} progress {{rbracket}}{{rbracket}}
    "west"  | "w" | 3
|arg5 =
</font>
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing {{value|-1}}. The level of progress can now be set via the additional 4th param.<br>Possible values for facing are:<br>"south" {{pipe}} "s" {{pipe}} 0<br>"east"  {{pipe}} "e" {{pipe}} 1<br>"north" {{pipe}} "n" {{pipe}} 2<br>"west"  {{pipe}} "w" {{pipe}} 3
}}


'''Spring.SetFeaturePosition'''
  ( number featureID, number x, number y, number z [, boolean snapToGround]) -> nil


'''Spring.SetFeatureDirection'''
{{LuaCallout
  ( number featureID, number x, number y, number z ) -> nil
|prefix = Spring.
|name = SetFeaturePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} snapToGround {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.SetFeatureNoSelect'''
  ( number featureID, boolean noSelect ) -> nil


'''Spring.SetFeatureAlwaysVisible'''
{{LuaCallout
  ( number featureID, boolean enable ) -> nil
|prefix = Spring.
|name = SetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.SetFeatureCollisionVolumeData'''
  ( number featureID, number scaleX, number scaleY, number scaleZ,
    number offsetX, number offsetY, number offsetX,
    number vType, number tType, number Axis
  ) -> nil
  <span class=note>check Spring.SetUnitCollisionVolumeData for further explanation of the arguments</span>


'''Spring.SetFeatureMidAndAimPos''' {{new|89.0}}
{{LuaCallout
  ( number unitID,  
|prefix = Spring.
    number mpx, number mpy, number mpz,
|name = SetFeatureRotation
    number apx, number apy, number apz,
|arg1 = {{type|number}} featureID
    [, boolean relative] ) -> boolean success
|arg2 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}


  <span class=note>check Spring.SetUnitMidAndAimPos for further explanation of the arguments</span>


{{LuaCallout
|prefix = Spring.
|name = SetFeatureVelocity
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}


'''Spring.SetFeatureRadiusAndHeight''' {{new|89.0}}
 
  ( number unitID, number radius, number height ) -> boolean success
{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureMoveCtrl
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} enable {{bracket}}
|arg3 = {{type|number*}} args {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this callout to control feature movement. The number* arguments are parsed as follows and all optional:<br><br>If enable is true:<br>{{bracket}}, velVector(x,y,z) -- initial velocity for feature<br>{{bracket}}, accVector(x,y,z) -- acceleration added every frame{{rbracket}}{{rbracket}}<br><br>If enable is false:<br>{{bracket}}, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl<br>{{bracket}},  impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl<br>{{bracket}}, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl{{rbracket}}{{rbracket}}{{rbracket}}<br><br>As of spring 103.0 it is necessary to unlock feature movement on x,z axis before changing feature physics. For example use "Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)" to unlock all movement prior to making SetFeatureVelocity calls.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureAlwaysVisible
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg6 = {{type|number}} Axis
|arg7 = {{type|number}} volumeType {{bracket}}
|arg8 = {{type|number}} primaryAxis {{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureMidAndAimPos
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}<br>Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureRadiusAndHeight
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 = {{type|boolean}} isBlocking
|arg3 = {{type|boolean}} isSolidObjectCollidable
|arg4 = {{type|boolean}} isProjectileCollidable
|arg5 = {{type|boolean}} isRaySegmentCollidable
|arg6 = {{type|boolean}} crushable
|arg7 = {{type|boolean}} blockEnemyPushing
|arg8 = {{type|boolean}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}<br> Changed parameters.
}}


= Lua to COB =
= Lua to COB =
'''Spring.CallCOBScript'''
  ( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
    -> nil | number returnValue, number retArg1, number retArg2, ...


'''Spring.CallCOBScriptCB'''<br>
{{LuaCallout
<font style="color:red;font-weight:600">broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement</font>
|prefix = Spring.
  ( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
|name = CallCOBScript
    -> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} funcID {{pipe}} {{type|string}} funcName
|arg3 = {{type|number}} retArgs
|arg4 = COBArg1
|arg5 = COBArg2
|arg6 = ...
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} returnValue, {{type|number}} retArg1, {{type|number}} retArg2, ...
|info =
}}


'''Spring.GetCOBScriptID'''
  ( number unitID, string funcName ) -> nil | number funcID


{{LuaCallout
|prefix = Spring.
|name = GetCOBScriptID
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} funcName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} funcID
|info =
}}




<span class="warning"><b>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!</b></span>
{{LuaCallout
|prefix = Spring.
|name = GetUnitCOBValue
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} splitData=false {{rbracket}}
|arg3 = {{type|number}} COBValue {{bracket}}
|arg4 = {{type|number}} param1 {{bracket}}
|arg5 = {{type|number}} param2 {{bracket}}
|arg6 = {{type|number}} param3 {{bracket}}
|arg7 =  {{type|number}} param4 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|number}} result {{pipe}} {{type|number}} result1, {{type|number}} result2
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead!<br>You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}


'''Spring.GetUnitCOBValue'''
  ( number unitID [, boolean splitData=false], number COBValue
    [, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
  -> number result | number result1, number result2
  <span class=note>you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]</span>
  <span class=note> also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]</span>


'''Spring.SetUnitCOBValue'''
{{LuaCallout
  ( number unitID, number COBValue, number param1 [,number param2] ) -> nil
|prefix = Spring.
  <span class=note>you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]</span>
|name = SetUnitCOBValue
  <span class=note> also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]</span>
|arg1 = {{type|number}} unitID  
|arg2 = {{type|number}} COBValue
|arg3 = {{type|number}} param1 {{bracket}}
|arg4 = {{type|number}} param2 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead!<br>You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}


= Give Order =
= Give Order =
'''Spring.GiveOrderToUnit'''
  ( number unitID,
    number cmdID,
    params = {number, etc...},
    options = {"alt", "ctrl", "shift", "right"} ) -> nil


'''Spring.GiveOrderToUnitMap'''
Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation)<br>
  ( unitMap = { [unitID] = dontCare, etc... },
See [[Lua CMDs]] for relevant constants.
    number cmdID,
 
    params = {number, etc...},
 
    options = {"alt", "ctrl", "shift", "right"} ) -> nil
{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = unitMap = { {{bracket}}unitID{{rbracket}} = example, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


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


'''Spring.GiveOrderArrayToUnitMap'''
{{LuaCallout
  ( unitMap = { [number unitID] = dontCare, etc... },
|prefix = Spring.
    orderArray = {
|name = GiveOrderArrayToUnitMap
      { number cmdID,
|arg1 = unitMap = { {{bracket}}{{type|number}} unitID{{rbracket}} = example, etc... }
        {number, etc...},     <font color="#55ee99">params</font>
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
        {"alt", "ctrl", "shift", "right"}   <font color="#55ee99">options</font>
|arg3 =
      }, ..
|arg4 =
    }
|arg5 =
  ) -> nil
|arg6 =
|arg7 =
|arg8 =
|arg9 =  
|return = {{type|nil}}
|info =
}}


'''Spring.GiveOrderArrayToUnitArray'''
  ( unitArray = { [1] = number unitID, etc... },
    orderArray = {
      { number cmdID,
        {number, etc...},    <font color="#55ee99">params</font>
        {"alt", "ctrl", "shift", "right"}  <font color="#55ee99">options</font>
      }, ..
    }
  ) -> nil


{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = {{type|number}} unitID, etc... }
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


=Ground=
=Ground=
== Grass ==
== Grass ==
'''Spring.AddGrass'''
  ( number x, number y, number z ) -> nil


'''Spring.RemoveGrass'''
{{LuaCallout
  ( number x, number y, number z ) -> nil
|prefix = Spring.
|name = AddGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = RemoveGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


== Heightmap ==
== Heightmap ==
<span class="note">Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is Game.squareSize.</span>
<span class="note">Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is [[Lua_ConstGame|Game.squareSize]].</span>


'''Spring.LevelHeightMap'''
{{LuaCallout
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil
|prefix = Spring.
|name = LevelHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2  
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.AdjustHeightMap''' <span class="note">(heightmap[x][z] += height;)</span>
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil


'''Spring.RevertHeightMap'''
{{LuaCallout
  ( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil
|prefix = Spring.
|name = AdjustHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2  
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = (heightmap[x][z] += height;)
}}




{{LuaCallout
|prefix = Spring.
|name = RevertHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}




'''Spring.SetHeightMapFunc'''
{{LuaCallout
  ( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
|prefix = Spring.
<span class="note">Example code:</span><code><pre>
|name = SetHeightMapFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =  
}}
Example code:<pre>
Spring.SetHeightMapFunc(function()
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for z=0,Game.mapSizeZ, Game.squareSize do
Line 489: Line 2,245:
end
end
end
end
end)
end)</pre>
</pre></code>
'''Spring.AddHeightMap''' <span class="warning">can only be called in SetHeightMapFunc()</span>
  ( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' <span class="warning">can only be called in SetHeightMapFunc()</span>
  ( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
<span class="note">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.</span>




{{LuaCallout
|prefix = Spring.
|name = AddHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetHeightMapFunc()
}}




{{LuaCallout
|prefix = Spring.
|name = SetHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetHeightMapFunc(). The terraform argument is a scaling factor:<br>
If =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished.
}}




'''Spring.LevelSmoothMesh'''
{{LuaCallout
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil
|prefix = Spring.
'''Spring.AdjustSmoothMesh'''
|name = LevelSmoothMesh
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil
|arg1 = {{type|number}} x1
'''Spring.RevertSmoothMesh'''
|arg2 = {{type|number}} z1 {{bracket}}
  ( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil
|arg3 = {{type|number}} x2  
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height  
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


'''Spring.SetSmoothMeshFunc'''
 
  ( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
{{LuaCallout
'''Spring.AddSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
|prefix = Spring.
  ( number x, number z, number height ) -> nil | number newHeight
|name = AdjustSmoothMesh
'''Spring.SetSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
|arg1 = {{type|number}} x1
  ( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = RevertSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetSmoothMeshFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = AddSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetSmoothMeshFunc().
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetSmoothMeshFunc().
}}


== TerrainTypes ==
== TerrainTypes ==
'''Spring.SetMapSquareTerrainType'''
 
  ( number x, number z, int newType ) -> nil | int oldType
{{LuaCallout
'''Spring.SetTerrainTypeData'''
|prefix = Spring.
  ( int typeIndex
|name = SetMapSquareTerrainType
  [, number speedTanks = nil ]
|arg1 = {{type|number}} x
  [, number speedKBOTs = nil ]
|arg2 = {{type|number}} z
  [, number speedHovers = nil ]
|arg3 = {{type|number}} newType
  [, number speedShips = nil ] ) -> nil | boolean true
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} oldType
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetTerrainTypeData
|arg1 = {{type|number}} typeIndex {{bracket}}
|arg2 = {{type|number}} speedTanks = nil {{bracket}}
|arg3 = {{type|number}} speedKBOts = nil {{bracket}}
|arg4 = {{type|number}} speedHovers = nil {{bracket}}
|arg5 = {{type|number}} speedShips = nil {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetSquareBuildingMask
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|103.0}}
}}
 
See also {{xtaglink|Gamedev:UnitDefs|buildingMask}} unitdef tag.


== MetalAmount ==
== MetalAmount ==
'''Spring.SetMetalAmount''' {{new|83.0}}
 
  ( number x, number z, number metalAmount)
{{LuaCallout
<span class="note">x & z coords are in worldspace/16<br>metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua)</span>
|prefix = Spring.
|name = SetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} metalAmount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}<br>x & z coords are in worldspace/16. metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).
}}


= Command Descriptions =
= Command Descriptions =
<font color="red" style="font-size:120%; font-weight:600">Doesn't work in unsynced code!</font><br><br>
<font color="red" style="font-size:120%; font-weight:600">Doesn't work in unsynced code!</font><br><br>


'''Spring.EditUnitCmdDesc'''
{{LuaCallout
  ( number unitID, number cmdDescID, table cmdArray ) -> nil
|prefix = Spring.
<font color="#55ee99">
|name = EditUnitCmdDesc
  structure of cmdArray:
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdDescID
|arg3 = {{type|table}} cmdArray  
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>structure of cmdArray:
   {
   {
     [ id          = int ],
     [ id          = int ],
Line 547: Line 2,485:
     [ texture    = string ],
     [ texture    = string ],
     [ cursor      = string ],
     [ cursor      = string ],
    [ queueing    = boolean ],
     [ hidden      = boolean ],
     [ hidden      = boolean ],
     [ disabled    = boolean ],
     [ disabled    = boolean ],
Line 552: Line 2,491:
     [ onlyTexture = boolean ],
     [ onlyTexture = boolean ],
     [ params      = { string = string, ... } ]
     [ params      = { string = string, ... } ]
   }
   }</pre>
</font>
{{var|queueing}} is {{new|101.0}} and allows custom commands to be non-queueing (handy for state toggles).


'''Spring.InsertUnitCmdDesc'''
  ( number unitID [, number cmdDescID ] , table cmdArray ) -> nil


'''Spring.RemoveUnitCmdDesc'''
{{LuaCallout
  ( number unitID [, number cmdDescID ] ) -> nil
|prefix = Spring.
|name = InsertUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 = {{type|table}} cmdArray
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = RemoveUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}


= Other =
= Other =
'''Spring.SetNoPause'''
  ( boolean noPause ) -> nil


'''Spring.SetUnitToFeature'''
{{LuaCallout
  ( boolean tofeature ) -> nil
|prefix = Spring.
<font color="#55ee99">
|name = SetNoPause
an ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag)
|arg1 = {{type|bool}} noPause
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]
|arg2 =
</font>
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetUnitToFeature
|arg1 = {{type|bool}} tofeature  
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = An ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag) [http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetExperienceGrade
|arg1 = {{type|number}} expGrade {{bracket}}
|arg2 = {{type|number}} ExpPowerScale {{bracket}}
|arg3 = {{type|number}} ExpHealthScale {{bracket}}
|arg4 = {{type|number}} ExpReloadScale {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = expGrade defines how often UnitExperience() will be called.<br>Prior to 104.0 it is based on the following equation:<br>(int) {{bracket}}exp/(exp+1){{rbracket}} / expGrade<br><br>Post 104.0 it is the raw change.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SpawnExplosion
|arg1 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg2 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg3 = {{type|table}} explosionParams
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}
  <pre>Possible keys of explosionParams are:
    weaponDef = number,
    owner = number,
    hitUnit = number,
    hitFeature = number,
    craterAreaOfEffect = number,
    damageAreaOfEffect = number,
    edgeEffectiveness = number,
    explosionSpeed = number,
    gfxMod = number,
    impactOnly = boolean,
    ignoreOwner = boolean,
    damageGround = boolean
 
Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef.
The weapondefID is only used for visuals and for passing into callins like UnitDamaged.</pre>
 


'''Spring.SetExperienceGrade'''
{{LuaCallout
  ( number expGrade
|prefix = Spring.
  <font color=#55ee99>[, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]]</font> ) -> nil
|name = SpawnCEG
|arg1 = {{type|string}} "cegname" | {{type|number}} cegID
|arg2 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg3 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg4 = {{type|number}} radius = 0
|arg5 = {{type|number}} damage = 0
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success, {{type|number}} cegID
|info = cegID new in 95.0.
}}


  <font color="#55ee99">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
  </font>


'''Spring.SpawnCEG'''
{{LuaCallout
  ( string "cegname",
|prefix = Spring.
    number posX = 0, number posY = 0, number posZ = 0,
|name = SpawnSFX
    number dirX = 0, number dirY = 0, number dirZ = 0,
|arg1 = {{type|number}} unitID
    number radius = 0, number damage = 0
|arg2 = {{type|number}} sfxID
  ) -> nil
|arg3 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg4 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg5 = {{type|number}} radius = 0
|arg6 = {{type|number}} damage = 0 {{bracket}}
|arg7 = {{type|bool}} absolute {{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}}
}}
 
Equal to the [[Animation-LuaCallouts#Effects|UnitScript versions of EmitSFX]], but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.


= Projectiles =
= Projectiles =
'''Spring.SetProjectileMoveControl''' <span class=note>(disables engine movecontrol, so lua can fully control the physics)</span>
 
  ( number projID, boolean enable ) -> nil
{{LuaCallout
'''Spring.SetProjectilePosition'''
|prefix = Spring.
  ( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
|name = SpawnProjectile
'''Spring.SetProjectileVelocity'''
|arg1 = {{type|number}} weaponDefID
  ( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
|arg2 = {{type|table}} projectileParams
'''Spring.SetProjectileCollision'''
|arg3 =
   ( number projID ) -> nil
|arg4 =
'''Spring.SetProjectileGravity'''
|arg5 =
  ( number projID [, number grav = 0] ) -> nil
|arg6 =
'''Spring.SetProjectileSpinAngle'''
|arg7 =
  ( number projID [, number spinAngle = 0] ) -> nil
|arg8 =
'''Spring.SetProjectileSpinSpeed'''
|arg9 =
  ( number projID [, number speed = 0] ) -> nil
|return = {{type|nil}} {{pipe}} {{type|number}} projectileID
'''Spring.SetProjectileSpinVec'''
|info =
  ( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
}}
'''Spring.SetProjectileCEG'''
  <pre>Possible keys of projectileParams are:
  ( number projID, string ceg_name ) -> nil
    pos = {number x, number y, number z},
    end = {number x, number y, number z},
    speed = {number x, number y, number z},
    spread = {number x, number y, number z},
    error = {number x, number y, number z},
    owner = number,
    team = number,
    ttl = number,
    gravity = number,
    tracking = number,
    maxRange = number,
    startAlpha = number,
    endAlpha = number,
    model = string,
    cegTag = string</pre>
 
{{LuaCallout
|prefix = Spring.
|name = DeleteProjectile
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}<br>Silently removes projectiles (no explosion).
}}
 
 
<span class = "warning">Pre 95.0:</span>
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|string}} targetTypeStr {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}
 
<span class = "warning">Post 95.0:</span>
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|number}} targetType {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}
  <pre>targetTypeStr can be one of:
    'u' - unit
    'f' - feature
    'p' - projectile
   while targetTypeInt is one of:
    string.byte('g') := GROUND
    string.byte('u') := UNIT
    string.byte('f') := FEATURE
    string.byte('p') := PROJECTILE</pre>
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileIgnoreTrackingError
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} ignore
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileIsIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|99.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileMoveControl
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Disables engine movecontrol, so lua can fully control the physics.
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectilePosition
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} posX = 0 {{bracket}}
|arg3 = {{type|number}} posY = 0 {{bracket}}
|arg4 = {{type|number}} posZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileVelocity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} velX = 0 {{bracket}}
|arg3 = {{type|number}} velY = 0 {{bracket}}
|arg4 = {{type|number}} velZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileCollision
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileGravity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} grav = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinAngle
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinAngle = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} speed = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinVec
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinX = 0 {{bracket}}
|arg3 = {{type|number}} spinY = 0 {{bracket}}
|arg4 = {{type|number}} spinZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileCEG
|arg1 = {{type|number}} projectileID
|arg2 = {{type|string}} ceg_name
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
 
 
{{LuaCallout
|prefix = Spring.
|name = SetPieceProjectileParams
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} explosionFlags {{bracket}}
|arg3 = {{type|number}} spinAngle {{bracket}}
|arg4 = {{type|number}} spinSpeed {{bracket}}
|arg5 = {{type|number}} spinVector.x {{bracket}}
|arg6 = {{type|number}} spinVector.y {{bracket}}
|arg7 = {{type|number}} spinVector.z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileAlwaysVisible
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}
 
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
 
or
 
{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
<pre>Format of the damages table:
  {
      ["paralyzeDamageTime" = number value,] 
      ["impulseFactor"      = number value,]
      ["impulseBoost"      = number value,]
      ["craterMult"        = number value,]
      ["craterBoost"        = number value,]
      ["dynDamageExp"      = number value,]
      ["dynDamageMin"      = number value,]
      ["dynDamageRange"    = number value,]
      ["dynDamageInverted"  = number value,] (<>0.0f := true)
      ["craterAreaOfEffect" = number value,]
      ["damageAreaOfEffect" = number value,]
      ["edgeEffectiveness"  = number value,]
      ["explosionSpeed"    = number value,]
      [number armorType    = number value,] (changes the damage against this armor type)
    }</pre>


[[category: Lua]]
[[category: Lua]]

Latest revision as of 20:58, 13 May 2023

Development < Lua Scripting < Lua SyncedCtrl

Game End

Spring.KillTeam ( number teamID )
return: nil

New in version 83.0
Will declare a team to be dead ( no further orders can be assigned to such teams's units ), Gaia team cannot be killed.


Spring.GameOver ( number allyTeamID1, number allyTeamID2, ... )
return: nil

New in version 83.0
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.

RulesParams

String values are new since 95.0. Attention: Numeric paramValues in quotes will be converted to number.

Spring.SetUnitRulesParam ( number unitID, string paramName, number|string paramValue [, table losAccess ] )
return: nil

Possible keys for the losAccess table are:
   `private` : only readable by the ally (default)
   `allied`  : readable by ally + ingame allied
   `inlos`   : readable if the unit is in LOS
   `inradar` : readable if the unit is in AirLOS
   `public`  : readable by all
  note: if one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it
     can read params with `inradar=true` even if the param has `inlos=false`)
  note2: all GameRulesParam are public, TeamRulesParams can just be `private`,`allied`
     and/or `public`
  note3: You can read RulesParams from any Lua enviroments! With those losAccess
     policies you can limit their access.


Spring.SetFeatureRulesParam ( number featureID, string paramName, number|string paramValue [, table losAccess ] )
return: nil

New since 102.0.
See above for further documentation of losAccess.


Spring.SetTeamRulesParam ( number teamID, string paramName, number|string paramValue [, table losAccess ] )
return: nil

See above for further documentation of losAccess.


Spring.SetGameRulesParam ( string paramName, number|string paramValue [, table losAccess ] )
return: nil

See above for further documentation of losAccess.

Resources

Spring.AddTeamResource ( number teamID, string "metal" | "energy", number amount )
return: nil

Adds metal or energy resources to the specified team.


Spring.UseTeamResource ( number teamID, string "metal" | "energy", number amount | { metal = number amount, energy = number amount } )
return: nil | bool hadEnough

Consumes metal and/or energy resources of the specified team.


Spring.SetTeamResource ( number teamID, string res, number amount )
return: 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 )
return: nil

Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible.


Spring.ShareTeamResource ( number teamID_src, number teamID_recv, string "metal" | "energy", number amount )
return: nil

Transfers resources between two teams.

Teams

Spring.SetAlly ( number firstAllyTeamID, number secondAllyTeamID, bool ally )
return: nil

New in version 98.0
Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.


Spring.AssignPlayerToTeam ( number playerID, number teamID )
return: nil

New in version 98.0
Assigns a player to a team.


Spring.SetGlobalLos ( number allyTeamID, bool globallos )
return: nil

New in version 101.0
Changes access to global line of sight for a team and its allies.

Unit Handling

Spring.CreateUnit ( string "defName" | number unitDefID, number x, number y, number z, string "facing" | number facing, number teamID [, bool build = false [, bool flattenGround = true [, number builderID ]]] )
return: number unitID | nil (meaning unit was not created)

Offmap positions are clamped! Use MoveCtrl to move to such positions.
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
unitID and builderID are New in version 92.0, the former allowing to spawn a unit with a specific ID.


Spring.DestroyUnit ( number unitID [, bool selfd = false [, bool reclaimed = false [, number attackerID ]]] )
return: nil

selfd := Makes the unit act like it self-destructed.
reclaimed := Don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!


Spring.TransferUnit ( number unitID, number newTeamID [, bool given = true ] )
return: nil

If given=false, the unit is captured.

Unit Control

Spring.SetUnitCosts ( number unitID, { [ buildTime = number amount ], [ metalCost = number amount ], [ energyCost = number amount ] } )
return: nil


Spring.SetUnitTooltip ( number unitID, string "tooltip" )
return: nil


Spring.SetUnitHealth ( number unitID, number health | { [ health = number health ], [ capture = number capture ], [ paralyze = number paralyze ], [ build = number build ] } )
return: nil


Spring.SetUnitMaxHealth ( number unitID, number maxHealth )
return: 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 ]]]]]] )
return: nil

The number in the paralyze parameter equals to the paralyzetime in the WeaponDef.


Spring.SetUnitStockpile ( number unitID [, number stockpile [, number buildPercent ]] )
return: nil


Spring.SetUnitExperience ( number unitID, number experience, number buildPercent )
return: nil


Spring.SetUnitFuel ( number unitID, number fuel )
return: nil

Removed from version 101.0


Spring.SetUnitCrashing ( number unitID, bool crashing )
return: bool success

New in version 83.0


Spring.SetUnitLineage ( number unitID, number teamID [, bool isRoot ] )
return: nil

Removed from version 83.0


Spring.SetUnitNeutral ( number unitID, bool neutral )
return: nil

Removed from version 83.0


Spring.SetUnitTarget ( number unitID, number x | nil, number y, number z [, bool dgun = false [, bool userTarget = false [, number weaponNum = -1 ]]] )
return: bool success

or

Spring.SetUnitTarget ( number unitID, number enemyUnitID | nil [, bool dgun = false [, bool userTarget = false [, number weaponNum = -1 ]]] )
return: bool success

Defines a unit's target. Nil as 2nd argument drops the unit's current target.
UserTarget & success new in version 95.0, setting nil target new in version 99.0, weaponNum new in version 102.0.


Spring.SetUnitMaxRange ( number unitID, number maxRange )
return: nil


Spring.SetUnitMass ( number unitID, number mass )
return: nil

New in version 101.0


Spring.SetUnitBlocking ( number unitID, bool isblocking, bool isSolidObjectCollidable, bool isProjectileCollidable, bool isRaySegmentCollidable, bool crushable, bool blockEnemyPushing, bool blockHeightChanges )
return: nil

New in version 95.0
Changed parameters.


Spring.SetUnitMetalExtraction ( number unitID, number depth [, number range ] )
return: nil

Parameter "depth" corresponds to metal extraction rate. Range value is similar to "extractsMetal" in unitDefs.


Spring.SetUnitBuildSpeed ( number builderID, number buildSpeed [, number repairSpeed [, number reclaimSpeed[, number resurrectSpeed [, number captureSpeed [, number terraformSpeed ]]]]] )
return: nil


Spring.SetUnitNanoPieces ( number builderID, table pieces )
return: nil

New in version 92.0
This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end
Use it!


Spring.UnitAttach ( number transporterID, number passengerID, number pieceNum )
return: nil

New in version 101.0


Spring.UnitDetach ( number passengerID )
return: nil

New in version 101.0


Spring.UnitDetachFromAir ( number passengerID )
return: nil

New in version 101.0


Spring.SetUnitLoadingTransport ( number passengerID, number transportID )
return: nil

New in version 101.0
Disables collisions between the two units to allow colvol intersection during the approach.


Spring.SetUnitPieceParent ( number unitID, number AlteredPiece, number ParentPiece )
return: nil

New in version 101.0
Changes the pieces hierarchy of a unit by attaching a piece to a new parent.


Spring.SetUnitPieceMatrix ( number unitID, number pieceNum, table matrix )
return: nil

New in version 104.0
Sets the local (i.e. parent-relative) matrix of the given piece if any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed (matrix should be an array of 16 floats, but is not otherwise sanity-checked).


Spring.SetUnitArmored ( number unitID, bool armored [, number armorMultiple ] )
return: nil

armorMultiple new in version 0.83.x


Spring.SetUnitShieldState ( number unitID [, number weaponID = -1 [, bool enabled [, number power ]]] )
return: nil


Spring.SetUnitFlanking ( number unitID, string "mode", number mode )
return: nil

or

Spring.SetUnitFlanking ( number unitID, string "moveFactor", number factor )
return: nil

or

Spring.SetUnitFlanking ( number unitID, string "minDamage", number minDamage )
return: nil

or

Spring.SetUnitFlanking ( number unitID, string "maxDamage", number maxDamage )
return: nil

or

Spring.SetUnitFlanking ( number unitID, string "dir", number x, number y, number z )
return: nil


Spring.SetUnitWeaponState ( number unitID, number weaponNum, table states )
return: nil

or

Spring.SetUnitWeaponState ( number unitID, number weaponNum, string key, number value )
return: 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,]
     ["salvoLeft"       = number value,]
     ["nextSalvo"       = number value,]
     ["aimReady"        = number value,] (<>0.0f := true)
   }
 (*) if you change the range of a weapon with dynamic damage
 make sure you use SetUnitWeaponDamages to change dynDamageRange as well.


Spring.SetUnitWeaponDamages ( number unitID, number weaponNum | string "selfDestruct" | string "explode", table damages )
return: nil

or

Spring.SetUnitWeaponDamages ( number unitID, number weaponNum | string "selfDestruct" | string "explode", string key, number value )
return: nil

New in version 101.0

Format of the damages table: 

  {
     ["paralyzeDamageTime" = number value,]  
     ["impulseFactor"      = number value,]
     ["impulseBoost"       = number value,]
     ["craterMult"         = number value,]
     ["craterBoost"        = number value,]
     ["dynDamageExp"       = number value,]
     ["dynDamageMin"       = number value,]
     ["dynDamageRange"     = number value,]
     ["dynDamageInverted"  = number value,] (<>0.0f := true)
     ["craterAreaOfEffect" = number value,]
     ["damageAreaOfEffect" = number value,]
     ["edgeEffectiveness"  = number value,]
     ["explosionSpeed"     = number value,]
     [number armorType     = number value,] (changes the damage against this armor type)
   }


Spring.SetUnitCollisionVolumeData ( number unitID, number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetZ, number vType, number tType, number Axis )
return: nil 

 enum COLVOL_TYPES {
     COLVOL_TYPE_DISABLED = -1,
     COLVOL_TYPE_ELLIPSOID = 0,
     COLVOL_TYPE_CYLINDER,
     COLVOL_TYPE_BOX,
     COLVOL_TYPE_SPHERE,
     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, bool enable, number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetZ [, number volumeType [, number primaryAxis ]] )
return: nil

As of 101.0 this is 1-based piece index argument (was 0-based).


Spring.SetUnitTravel ( number unitID, number travel [, number travelPeriod ] )
return: nil


Spring.SetUnitMoveGoal ( number unitID, number goalX, number goalY, number goalZ [, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )
return: nil

Used by default commands to get in build-, attackrange etc.
New in version 98.0 moveRaw: allow unit to dumbly move to a coordinate without calculating path.


Spring.SetUnitLandGoal ( number unitID, number goalX, number goalY, number goalZ [, number goalRadius ] )
return: nil

New in version 101.0
Used in conjunction with Spring.UnitAttach et al. to re-implement old airbase & fuel system in Lua.


Spring.ClearUnitGoal ( number unitID )
return: nil

New in version 102.0


Spring.SetUnitPhysics ( number unitID, number posX, number posY, number posZ, number velX, number velY, number velZ, number rotX, number rotY, number rotZ, number dragX, number dragY, number dragZ )
return: nil

Drag new in version 95.0


Spring.SetUnitPosition ( number unitID, number x, number z [, bool alwaysAboveSea ] )
return: nil


Spring.SetUnitDirection ( number unitID, number x, number y, number z )
return: nil

New in version 90.0


Spring.SetUnitVelocity ( number unitID, number velX, number velY, number velZ )
return: nil


Spring.SetUnitRotation ( number unitID, number yaw, number pitch, number roll )
return: nil


Spring.AddUnitImpulse ( number unitID, number x, number y, number z [, number decayRate ] )
return: nil


Spring.AddUnitSeismicPing ( number unitID, number pingSize )
return: nil


Spring.SetGroundMoveTypeData ( number unitID, table properties )
return: nil

Use this function to control movement properties for ground units. Known properties : maxSpeed, maxWantedSpeed, turnRate, ... (TODO fix/update)


Spring.SetAirMoveTypeData ( number unitID, table properties )
return: nil

Use this function to control movement properties for non-gunship air units. Known properties : maxSpeed, maxWantedSpeed, ... (TODO fix/update)


Spring.SetGunshipMoveTypeData ( number unitID, table properties )
return: nil

Use this function to control movement properties for air gunships. Known properties : maxSpeed, maxWantedSpeed, turnRate, ... (TODO fix/update)


Spring.RemoveBuildingDecal ( number unitID )
return: nil


Spring.SetUnitMidAndAimPos ( number unitID, number mpX, number mpY, number mpZ, number apX, number apY, number apZ [, bool relative ] )
return: bool success

New in version 89.0
mpx, mpy, mpz: New middle position of unit
apx, apy, apz: New position that enemies aim at on this unit
relative: Are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!


Spring.SetUnitRadiusAndHeight ( number unitID, number radius, number height )
return: bool success

New in version 89.0


Spring.UnitWeaponFire ( number unitID, number weaponID )
return: nil


Spring.UnitWeaponHoldFire ( number unitID, number weaponID )
return: nil

Unit LOS

Spring.SetUnitCloak ( number unitID, bool cloaked | number scriptCloak [, bool decloakAbs | number decloakDistance ] )
return: 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, bool sonarStealth )
return: nil


Spring.SetUnitStealth ( number unitID, bool stealth )
return: nil


Spring.SetUnitAlwaysVisible ( number unitID, bool alwaysVisible )
return: nil


Spring.SetUnitLosMask ( number unitID, number allyTeam, number los | table losTypes )
return: nil

The 3rd 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 )
return: nil

See above for more info on the arguments.


Spring.SetUnitSensorRadius ( number unitID, string type, number radius )
return: nil | number newRadius

Type can be:
"los", "airLos", "radar", "sonar", "seismic", "radarJammer", "sonarJammer"


Spring.SetRadarErrorParams ( number allyTeamID, number allyteamErrorSize [, number baseErrorSize [, number baseErrorMult ]] )
return: nil

New in version 95.0


Spring.SetUnitPosErrorParams ( number unitID, number posErrorVector.x, number posErrorVector.y, number posErrorVector.z,, number posErrorDelta.x, number number posErrorDelta.y, number posErrorDelta.z [, number nextPosErrorUpdate ] )
return: nil

New in version 95.0

Unit Resourcing

Spring.SetUnitResourcing ( number unitID, string res, number amount )
return: nil

or

Spring.SetUnitResourcing ( number unitID, { res = number amount, ... } )
return: 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 )
return: nil


Spring.UseUnitResource ( number unitID, string "m" | "e", number amount )
return: nil | bool okay

or

Spring.UseUnitResource ( number unitID, { [ "m" | "metal" | "e" | "energy" ] = amount, ... } )
return: nil | bool okay


Spring.SetUnitHarvestStorage ( number unitID, number metal )
return: nil

New in version 97.0
See also harvestStorage UnitDef tag.

Feature Handling

Spring.CreateFeature ( string "defName" | number featureDefID, number x, number y, number z [, number heading [, number AllyTeamID [, number featureID ]]] )
return: number featureID


Spring.DestroyFeature ( number featureDefID )
return: nil


Spring.TransferFeature ( number featureDefID, number teamID )
return: nil

Feature Control

Spring.SetFeatureHealth ( number featureID, number health )
return: nil


Spring.SetFeatureResources ( number featureID, number metal, number energy [, number reclaimTime [, number reclaimLeft ]{rbracket, {{{arg6}}}, {{{arg7}}}, {{{arg8}}}, {{{arg9}}} )

|arg6 = |arg7 = |arg8 = |arg9 = |return = nil |info = New in version 104.0 }}


Spring.SetFeatureReclaim ( number featureID, number reclaimLeft )
return: nil


Spring.SetFeatureResurrect ( number featureID, number unitDefID | string unitDefName [, number facing | string "facing" [, number progress ]] )
return: nil

New in version 104.0 Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing -1. The level of progress can now be set via the additional 4th param.
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 [, bool snapToGround ] )
return: nil


Spring.SetFeatureDirection ( number featureID, number dirX, number dirY, number dirZ )
return: nil


Spring.SetFeatureRotation ( number featureID, number rotX, number rotY, number rotZ )
return: nil

New in version 101.0


Spring.SetFeatureVelocity ( number featureID, number velX, number velY, number velZ )
return: nil

New in version 95.0


Spring.SetUnitPhysics ( number featureID, number posX, number posY, number posZ, number velX, number velY, number velZ, number rotX, number rotY, number rotZ, number dragX, number dragY, number dragZ )
return: nil

New in version 95.0


Spring.SetFeatureMoveCtrl ( number featureID [, bool enable [, number* args ]] )
return: nil

Use this callout to control feature movement. The number* arguments are parsed as follows and all optional:

If enable is true:
[, velVector(x,y,z) -- initial velocity for feature
[, accVector(x,y,z) -- acceleration added every frame]]

If enable is false:
[, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl
[, impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl
[, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl]]]

As of spring 103.0 it is necessary to unlock feature movement on x,z axis before changing feature physics. For example use "Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)" to unlock all movement prior to making SetFeatureVelocity calls.


Spring.SetFeatureNoSelect ( number featureID, bool noSelect )
return: nil


Spring.SetFeatureAlwaysVisible ( number featureID, bool enable )
return: nil


Spring.SetFeatureCollisionVolumeData ( number featureID, number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetZ, number vType, number tType, number Axis )
return: nil

Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.


Spring.SetFeaturePieceCollisionVolumeData ( number featureID, number pieceIndex, bool enable, number scaleX, number scaleY, number scaleZ, number offsetX, number offsetY, number offsetZ, number Axis, number volumeType [, number primaryAxis ] )
return: nil

New in version 101.0


Spring.SetFeatureMidAndAimPos ( number featureID, number mpX, number mpY, number mpZ, number apX, number apY, number apZ [, bool relative )
return: bool success

New in version 89.0
Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.


Spring.SetFeatureRadiusAndHeight ( number featureID, number radius, number height )
return: bool success

New in version 89.0


Spring.SetFeatureMass ( number featureID, number mass )
return: nil

New in version 101.0


Spring.SetFeatureBlocking ( number featureID, boolean isBlocking, boolean isSolidObjectCollidable, boolean isProjectileCollidable, boolean isRaySegmentCollidable, boolean crushable, boolean blockEnemyPushing, boolean blockHeightChanges )
return: nil

New in version 95.0
Changed parameters.

Lua to COB

Spring.CallCOBScript ( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
return: nil | number returnValue, number retArg1, number retArg2, ...


Spring.GetCOBScriptID ( number unitID, string funcName )
return: nil | number funcID


Spring.GetUnitCOBValue ( number unitID [, bool splitData=false ], number COBValue [, number param1 [, number param2 [, number param3 [, number param4 ]]]] )
return: number result | number result1, number result2

Note: Don't use Spring.[Get|Set]UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead!
You can find the possible values for `COBValue` in Lua_ConstCOB. Also see Custom_Variables.


Spring.SetUnitCOBValue ( number unitID, number COBValue, number param1 [, number param2 ] )
return: nil

Note: Don't use Spring.[Get|Set]UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead!
You can find the possible values for `COBValue` in Lua_ConstCOB. Also see Custom_Variables.

Give Order

Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation)
See Lua CMDs for relevant constants.


Spring.GiveOrderToUnit ( number unitID, number cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} )
return: nil


Spring.GiveOrderToUnitMap ( unitMap = { [unitID] = example, etc... }, number cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} )
return: nil


Spring.GiveOrderToUnitArray ( unitArray = { [1] = unitID, etc... }, number cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} )
return: nil


Spring.GiveOrderArrayToUnitMap ( unitMap = { [number unitID] = example, etc... }, orderArray = { { number cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } } )
return: nil


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

Ground

Grass

Spring.AddGrass ( number x, number z )
return: nil


Spring.RemoveGrass ( number x, number z )
return: nil

Heightmap

Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is Game.squareSize.

Spring.LevelHeightMap ( number x1, number z1 [, number x2, number z2 ], number height )
return: nil


Spring.AdjustHeightMap ( number x1, number z1 [, number x2, number z2 ], number height )
return: nil

(heightmap[x][z] += height;)


Spring.RevertHeightMap ( number x1, number z1 [, number x2, number z2 ], number origFactor )
return: nil


Spring.SetHeightMapFunc ( lua_function [, arg1 [, arg2 [, ... ]]] )
return: nil | number absTotalHeightMapAmountChanged

Example code:

Spring.SetHeightMapFunc(function()
	for z=0,Game.mapSizeZ, Game.squareSize do
		for x=0,Game.mapSizeX, Game.squareSize do
			Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
		end
	end
end)


Spring.AddHeightMap ( number x, number z, number height )
return: nil | number newHeight

Can only be called in SetHeightMapFunc()


Spring.SetHeightMap ( number x, number z, number height [, number terraform = 1 ] )
return: nil | number absHeightDiff

Can only be called in SetHeightMapFunc(). The terraform argument is a scaling factor:

If =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished.


Spring.LevelSmoothMesh ( number x1, number z1 [, number x2, number z2 ], number height )
return: nil


Spring.AdjustSmoothMesh ( number x1, number z1 [, number x2, number z2 ], number height )
return: nil


Spring.RevertSmoothMesh ( number x1, number z1 [, number x2, number z2 ], number origFactor )
return: nil


Spring.SetSmoothMeshFunc ( lua_function [, arg1 [, arg2 [, ... ]]] )
return: nil | number absTotalHeightMapAmountChanged


Spring.AddSmoothMesh ( number x, number z, number height )
return: nil | number newHeight

Can only be called in SetSmoothMeshFunc().


Spring.SetSmoothMesh ( number x, number z, number height [, number terraform = 1 ] )
return: nil | number absHeightDiff

Can only be called in SetSmoothMeshFunc().

TerrainTypes

Spring.SetMapSquareTerrainType ( number x, number z, number newType )
return: nil | number oldType


Spring.SetTerrainTypeData ( number typeIndex [, number speedTanks = nil [, number speedKBOts = nil [, number speedHovers = nil [, number speedShips = nil ]]]] )
return: nil | bool true


Spring.SetSquareBuildingMask ( number x, number z, number mask )
return: nil

New in version 103.0

See also buildingMask unitdef tag.

MetalAmount

Spring.SetMetalAmount ( number x, number z, number metalAmount )
return: nil

New in version 83.0
x & z coords are in worldspace/16. metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).

Command Descriptions

Doesn't work in unsynced code!

Spring.EditUnitCmdDesc ( number unitID, number cmdDescID, table cmdArray )
return: nil 

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

queueing is New in version 101.0 and allows custom commands to be non-queueing (handy for state toggles).


Spring.InsertUnitCmdDesc ( number unitID [, number cmdDescID ], table cmdArray )
return: nil


Spring.RemoveUnitCmdDesc ( number unitID [, number cmdDescID ] )
return: nil

Other

Spring.SetNoPause ( bool noPause )
return: nil


Spring.SetUnitToFeature ( bool tofeature )
return: nil

An ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag) thread


Spring.SetExperienceGrade ( number expGrade [, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]] )
return: nil

expGrade defines how often UnitExperience() will be called.
Prior to 104.0 it is based on the following equation:
(int) [exp/(exp+1)] / expGrade

Post 104.0 it is the raw change.


Spring.SpawnExplosion ( number posX = 0, number posY = 0, number posZ = 0, number dirX = 0, number dirY = 0, number dirZ = 0, table explosionParams )
return: nil

New in version 104.0
Possible keys of explosionParams are:
    weaponDef = number,
    owner = number,
    hitUnit = number,
    hitFeature = number,
    craterAreaOfEffect = number,
    damageAreaOfEffect = number,
    edgeEffectiveness = number,
    explosionSpeed = number,
    gfxMod = number,
    impactOnly = boolean,
    ignoreOwner = boolean,
    damageGround = boolean

Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef.
The weapondefID is only used for visuals and for passing into callins like UnitDamaged.


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 )
return: nil | bool success, number cegID

cegID new in 95.0.


Spring.SpawnSFX ( number unitID, number sfxID, number posX = 0, number posY = 0, number posZ = 0, number dirX = 0, number dirY = 0, number dirZ = 0, number radius = 0, number damage = 0 [, bool absolute ] )
return: nil | bool success

New in version 104.0

Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

Projectiles

Spring.SpawnProjectile ( number weaponDefID, table projectileParams )
return: nil | number projectileID 

Possible keys of projectileParams are:
    pos = {number x, number y, number z},
    end = {number x, number y, number z},
    speed = {number x, number y, number z},
    spread = {number x, number y, number z},
    error = {number x, number y, number z},
    owner = number,
    team = number,
    ttl = number,
    gravity = number,
    tracking = number,
    maxRange = number,
    startAlpha = number,
    endAlpha = number,
    model = string,
    cegTag = string

Spring.DeleteProjectile ( number projectileID )
return: nil

New in version 101.0
Silently removes projectiles (no explosion).


Pre 95.0: Spring.SetProjectileTarget ( number projectileID, [ number targetID, string targetTypeStr ] | [ number posX = 0, number posY = 0, number posZ = 0 ] )
return: nil | bool validTarget

Post 95.0: Spring.SetProjectileTarget ( number projectileID, [ number targetID, number targetType ] | [ number posX = 0, number posY = 0, number posZ = 0 ] )
return: nil | bool validTarget 

targetTypeStr can be one of: 
    'u' - unit
    'f' - feature
    'p' - projectile
  while targetTypeInt is one of:
    string.byte('g') := GROUND
    string.byte('u') := UNIT
    string.byte('f') := FEATURE
    string.byte('p') := PROJECTILE


Spring.SetProjectileIgnoreTrackingError ( number projectileID, bool ignore )
return: nil

New in version 101.0


Spring.SetProjectileIsIntercepted ( number projectileID )
return: nil

New in version 99.0


Spring.SetProjectileMoveControl ( number projectileID, bool enable )
return: nil

Disables engine movecontrol, so lua can fully control the physics.


Spring.SetProjectilePosition ( number projectileID [, number posX = 0 [, number posY = 0 [, number posZ = 0 ]]] )
return: nil


Spring.SetProjectileVelocity ( number projectileID [, number velX = 0 [, number velY = 0 [, number velZ = 0 ]]] )
return: nil


Spring.SetProjectileCollision ( number projectileID )
return: nil


Spring.SetProjectileGravity ( number projectileID [, number grav = 0 ] )
return: nil


Spring.SetProjectileSpinAngle ( number projectileID [, number spinAngle = 0 ] )
return: nil

Removed from version 95.0


Spring.SetProjectileSpinSpeed ( number projectileID [, number speed = 0 ] )
return: nil

Removed from version 95.0


Spring.SetProjectileSpinVec ( number projectileID [, number spinX = 0 [, number spinY = 0 [, number spinZ = 0 ]]] )
return: nil

Removed from version 95.0


Spring.SetProjectileCEG ( number projectileID, string ceg_name )
return: nil


Spring.SetPieceProjectileParams ( number projectileID [, number explosionFlags [, number spinAngle [, number spinSpeed [, number spinVector.x [, number spinVector.y [, number spinVector.z ]]]]]] )
return: nil

New in version 95.0


Spring.SetProjectileAlwaysVisible ( number projectileID, bool alwaysVisible )
return: nil

New in version 95.0


Spring.SetProjectileDamages ( number unitID, number weaponNum, table damages )
return: nil

or

Spring.SetProjectileDamages ( number unitID, number weaponNum, string key, number value )
return: nil

New in version 101.0
Format of the damages table:
   {
      ["paralyzeDamageTime" = number value,]  
      ["impulseFactor"      = number value,]
      ["impulseBoost"       = number value,]
      ["craterMult"         = number value,]
      ["craterBoost"        = number value,]
      ["dynDamageExp"       = number value,]
      ["dynDamageMin"       = number value,]
      ["dynDamageRange"     = number value,]
      ["dynDamageInverted"  = number value,] (<>0.0f := true)
      ["craterAreaOfEffect" = number value,]
      ["damageAreaOfEffect" = number value,]
      ["edgeEffectiveness"  = number value,]
      ["explosionSpeed"     = number value,]
      [number armorType     = number value,] (changes the damage against this armor type)
    }
Retrieved from "https://springrts-wiki.p2004a.com/mediawiki/index.php?title=Lua_SyncedCtrl&oldid=11820"