User:Master-athmos: Difference between revisions

From Spring
Jump to navigationJump to search
← Older editNewer edit →
No edit summary
No edit summary
Line 54: Line 54:
[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}
[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}


= Game End =


= Engine =
{{LuaCallout
|prefix = Spring.
|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.
}}


{{LuaConstant
= RulesParams =
|type = string
<span class=warning>String values are new since 95.0. Attention: Numeric paramValues in quotes will be converted to number.</span>
|name = Game.version
 
|info = {{removed|104.0}} Now in [[Lua_ConstEngine]]
{{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>
}}
}}




{{LuaConstant
{{LuaCallout
|type = string
|prefix = Spring.
|name = Game.buildFlags
|name = SetFeatureRulesParam
|info = {{removed|104.0}} Now in [[Lua_ConstEngine]]
|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.
}}
}}




{{LuaConstant
{{LuaCallout
|type = number
|prefix = Spring.
|name = Game.gameID
|name = SetTeamRulesParam
|info = <span class="warning">Replaced in 89.0 with GameID(string gameID) synced callin</span>
|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.
}}
}}




{{LuaConstant
 
|type = number
{{LuaCallout
|name = Game.maxUnits
|prefix = Spring.
|info =
|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 =


{{LuaConstant
{{LuaCallout
|type = number
|prefix = Spring.
|name = Game.maxTeams
|name = AddTeamResource
|info =
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Adds metal or energy resources to the specified team.
}}
}}




{{LuaConstant
{{LuaCallout
|type = number
|prefix = Spring.
|name = Game.maxPlayers
|name = UseTeamResource
|info =
|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.
}}
}}




{{LuaConstant
{{LuaCallout
|type = number
|prefix = Spring.
|name = Game.squareSize
|name = SetTeamResource
|info = <span class="note">Divide Game.mapSizeX or Game.mapSizeZ by this to get engine's "mapDims" coordinates</span>
|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>
}}
}}




{{LuaConstant
{{LuaCallout
|type = number
|prefix = Spring.
|name = Game.gameSpeed
|name = SetTeamShareLevel
|info =
|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.
}}
}}


= Host =


{{LuaConstant
{{LuaCallout
|type = number
|prefix = Spring.
|name = Game.gameMode
|name = ShareTeamResource
|info = <span class="warning"> Removed from version 83.x</span>
|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 =




{{LuaConstant
{{LuaCallout
|type = number
|prefix = Spring.
|name = Game.startPosType
|name = SetAlly
|info =
|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.
}}
}}




{{LuaConstant
{{LuaCallout
|type = bool
|prefix = Spring.
|name = Game.commEnds
|name = AssignPlayerToTeam
|info = <span class="warning"> Removed from version 83.x</span>
|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.
}}
}}




{{LuaConstant
 
|type = bool
{{LuaCallout
|name = Game.limitDGun
|prefix = Spring.
|info = <span class="warning"> Removed from version 83.x</span>
|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 =


{{LuaConstant
{{LuaCallout
|type = bool
|prefix = Spring.
|name = Game.ghostedBuildings
|name = CreateUnit
|info =
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number }} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|string}} "facing" {{pipe}} {{type|number }} facing
|arg6 = {{type|number}} teamID {{bracket}}
|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.
}}
}}


= Checksums =


{{LuaConstant
{{LuaCallout
|type = string
|prefix = Spring.
|name = Game.mapChecksum
|name = DestroyUnit
|info =
|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!
}}
}}






{{LuaConstant
{{LuaCallout
|type = string
|prefix = Spring.
|name = Game.modChecksum
|name = TransferUnit
|info =
|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.
}}
}}


= Map =
== Unit Control ==


{{LuaConstant
{{LuaCallout
|type = bool
|prefix = Spring.
|name = Game.mapDamage
|name = SetUnitCosts
|info =
|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 =  
}}
}}




{{LuaConstant
'''Spring.SetUnitCosts'''
|type = string
  ( number unitID, {  
|name = Game.mapName
    [ buildTime  = number amount ],
|info =
    [ metalCost  = number amount ],
}}
    [ energyCost = number amount ]
  } ) -> nil
 
'''Spring.SetUnitTooltip'''
  ( number unitID, string "tooltip" ) -> nil
 
'''Spring.SetUnitHealth'''
  ( number unitID,
    number health |
    { [ health  = number health ],
      [ capture  = number capture ],
      [ paralyze = number paralyze ],
      [ build    = number build ] }
  ) -> nil


'''Spring.SetUnitMaxHealth'''
  ( number unitID, number maxHealth ) -> nil


{{LuaConstant
'''Spring.AddUnitDamage'''
|type = string
  ( number unitID, number damage
|name = Game.mapDescription
    [, number paralyze = 0 [, number attackerID = -1 [, number weaponID = -1
|info = = {{type|string}} '''Game.mapHumanName'''
      [, number impulse_x [, number impulse_y [, number impulse_z ]]] ]]] ) -> nil
}}
<font color="#55ee99">the number in the paralyze parameter equals to paralyzetime in the WeaponDef</font>


'''Spring.SetUnitStockpile'''
  ( number unitID [, number stockpile [, number buildPercent ]]) -> nil


{{LuaConstant
'''Spring.SetUnitExperience'''
|type = number
  ( number unitID, number experience ) -> nil
|name = Game.mapHardness
|info =
}}


'''Spring.SetUnitFuel''' {{removed|101.0}}
  ( number unitID, number fuel ) -> nil


{{LuaConstant
'''Spring.SetUnitCrashing''' {{new|83.0}}
|type = number
  ( number unitID, boolean crashing ) -> boolean success
|name = Game.mapX
|info =
}}


'''Spring.SetUnitLineage''' {{removed|83.0}}
  ( number unitID, number teamID [, boolean isRoot] ) -> nil


{{LuaConstant
'''Spring.SetUnitNeutral'''
|type = number
  ( number unitID, boolean neutral ) -> nil
|name = Game.mapY
|info =
}}


'''Spring.SetUnitTarget''' <span class="warning">userTarget & success new in version 95.0, setting nil target new in 99.0, weaponNum new in 102.0</span>
  ( number unitID,
    number enemyUnitID | number x, number y, number z, | nil,
    [ boolean dgun = false [, boolean userTarget = false [, number weaponNum = -1 ]]] ) ->  success


{{LuaConstant
'''Spring.SetUnitMaxRange'''
|type = number
  ( number unitID, number maxRange ) -> nil
|name = Game.mapSizeX
|info = <font color="#55ee99">  in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates</font>
}}


'''Spring.SetUnitMass''' {{new|101.0}}
  ( number unitID, number mass ) -> nil


{{LuaConstant
'''Spring.SetUnitBlocking''' <span class="warning">crushable new in version 85.0</span>
|type = number
  ( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil
|name = Game.mapSizeZ
|info = <font color="#55ee99"> in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates</font>
}}


'''Spring.SetUnitBlocking''' {{new|95.0}} changed parameters:
  number unitID,
  boolean isBlocking,
  boolean isSolidObjectCollidable,
  boolean isProjectileCollidable,
  boolean isRaySegmentCollidable,
  boolean crushable,
  boolean blockEnemyPushing,
  boolean blockHeightChanges


'''Spring.SetUnitMetalExtraction''' <span class="warning">&nbsp;&nbsp;&nbsp;"depth" corresponds to metal extraction rate (value range similar to "extractsMetal" unitDef)</span>
  ( number unitID, number depth [,number range] ) -> nil


{{LuaConstant
'''Spring.SetUnitBuildSpeed'''
|type = number
  ( number builderID,
|name = Game.gravity
    number buildSpeed, [ number repairSpeed [, number reclaimSpeed
|info =
  [,number resurrectSpeed [, number captureSpeed [, number terraformSpeed ]] ]]] ) -> nil
}}


'''Spring.SetUnitNanoPieces''' {{new|92.0}}
  ( number builderID, table pieces ) -> nil
This saves a lot of engine calls, by replacing:
function script.QueryNanoPiece() return currentpiece end
Use it!


{{LuaConstant
'''Spring.UnitAttach''' {{new|101.0}}
|type = number
  ( number transporterID, number passengerID, number pieceNum ) -> nil
|name = Game.tidal
|info =
}}


'''Spring.UnitDetach''' {{new|101.0}}
  ( number passengerID ) -> nil


'''Spring.UnitDetachFromAir''' {{new|101.0}}
  ( number passengerID ) -> nil


{{LuaConstant
'''Spring.SetUnitLoadingTransport''' {{new|101.0}}
|type = number
  ( number passengerID, number transportID ) -> nil
|name = Game.windMin
|info =
}}


<span class="note">Disables collisions between the two units to allow colvol intersection during the approach.</span>


{{LuaConstant
'''Spring.SetUnitPieceParent''' {{new|101.0}}
|type = number
  ( number unitID, number AlteredPiece, number ParentPiece ) -> nil
|name = Game.windMax
Changes the pieces hierarchy of a unit, by attaching a piece to a new parent.
|info =
}}


'''Spring.SetUnitPieceMatrix''' {{new|104.0}}
  ( number unitID, number pieceNum, table matrix )


{{LuaConstant
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).
|type = number
|name = Game.extractorRadius
|info =
}}


'''Spring.SetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
  ( number unitID, boolean armored [, number armorMultiple] ) -> nil


{{LuaConstant
'''Spring.SetUnitShieldState'''
|type = number
  ( number unitID [, number weaponID = -1] [, boolean enabled] [, number power] ) -> nil
|name = Game.waterDamage
|info =
}}


'''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


{{LuaConstant
'''Spring.SetUnitWeaponState'''
|type = table
  ( number unitID, number weaponNum, table states ) -> nil
|name = Game.envDamageTypes
  ( number unitID, number weaponNum, string key, number value ) -> nil
|info = <font color="#55ee99">Containing {def}IDs of environmental-damage sources {{new|104.0}}.</font>
  <span class="note">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.
  </span>


= Mod =
'''Spring.SetUnitWeaponDamages''' {{new|101.0}}
  ( number unitID, number weaponNum | "selfDestruct" | "explode", table damages ) -> nil
  ( number unitID, number weaponNum | "selfDestruct" | "explode", string key, number value ) -> nil
  <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>


{{LuaConstant
'''Spring.SetUnitCollisionVolumeData'''
|type = string
  ( number unitID, number scaleX, number scaleY, number scaleZ,
|name = Game.gameName
    number offsetX, number offsetY, number offsetX,
|info = {{new|95.0}}
    number vType, number tType, number Axis
}}
  ) -> nil
  <span class="note">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
    };
  </span>


'''Spring.SetUnitPieceCollisionVolumeData'''
  ( number unitID, number pieceIndex, boolean enable,
    number scaleX, number scaleY, number scaleZ,
    number offsetX, number offsetY, number offsetZ
    [, number volumeType [, number primaryAxis]]
  ) -> nil
As of 101.0 this is 1-based piece index argument (was 0-based).


{{LuaConstant
'''Spring.SetUnitTravel'''
|type = string
  ( number unitID, number travel [, number travelPeriod] ) -> nil
|name = Game.gameShortName
|info = {{new|95.0}}
}}


'''Spring.SetUnitMoveGoal'''  <span class="note">used by default commands to get in build-,attackrange etc.</span>
  (number unitID, number goalx, number goaly, number goalz
  [, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )
{{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>


{{LuaConstant
'''Spring.SetUnitLandGoal'''  {{new|101.0}}
|type = string
  (number unitID, number goalx, number goaly, number goalz [, number goalRadius ] ) -> nil
|name = Game.gameVersion
Used in conjunction with {{name|Spring.UnitAttach}} et al to re-implement old airbase & fuel system in lua.
|info = {{new|95.0}}
}}


'''Spring.ClearUnitGoal''' {{new|102.0}}
  (number unitID) -> nil


{{LuaConstant
'''Spring.SetUnitPhysics''' <span class="warning">drag new in version 95.0</span>
|type = string
  ( number unitID,
|name = Game.gameMutator
    number posx, number posy, number posz,
|info = {{new|95.0}}
    number velx, number vely, number velz,
}}
    number rotx, number roty, number rotz,
    number dragx, number dragy, number dragz,
  ) -> nil


'''Spring.SetUnitPosition'''
  ( number unitID, number x, number z [, boolean alwaysAboveSea] ) -> nil


{{LuaConstant
'''Spring.SetUnitDirection''' {{new|90.0}}
|type = string
  ( number unitID, number x, number y, number z ) -> nil
|name = Game.gameDesc
|info = {{new|95.0}}
}}


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


{{LuaConstant
'''Spring.SetUnitRotation'''
|type = string
  ( number unitID, number rotx, number roty, number rotz ) -> nil
|name = Game.modName
|info = <span class=warning>deprecated (it is in contrast to gameName appended with gameVersion!)</span>
}}


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


{{LuaConstant
'''Spring.AddUnitSeismicPing'''
|type = string
  ( number unitID, number pingSize ) -> nil
|name = Game.modShortName
|info = <span class=warning>deprecated</span><br>
}}


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


{{LuaConstant
'''Spring.SetUnitMidAndAimPos''' {{new|89.0}}
|type = string
  ( number unitID,
|name = Game.modVersion
    number mpx, number mpy, number mpz,
|info = <span class=warning>deprecated</span><br>
    number apx, number apy, number apz,
}}
    [, boolean relative] ) -> boolean success


<font color="#55ee99">
mpx, mpy, mpz: new middle position of unit


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


{{LuaConstant
relative: are the new coordinates relative to world or unit coordinates?
|type = string
</font>
|name = Game.modMutator
|info = <span class=warning>deprecated</span><br>
}}




{{LuaConstant
'''Spring.SetUnitRadiusAndHeight''' {{new|89.0}}
|type = string
  ( number unitID, number radius, number height ) -> boolean success
|name = Game.modDesc
|info = <span class=warning>deprecated</span><br>
}}


'''Spring.UnitWeaponFire'''
  ( number unitID, number weaponID ) -> nil
'''Spring.UnitWeaponHoldFire'''
  ( number unitID, number weaponID ) -> nil


{{LuaConstant
== Unit LOS ==
|type = bool
'''Spring.SetUnitCloak'''
|name = Game.allowTeamColors
  ( number unitID,
|info =
    boolean cloaked | number scriptCloak,
}}
    [ number decloakDistance | boolean decloakAbs ] ) -> nil


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


{{LuaConstant
'''Spring.SetUnitSonarStealth'''
|type = bool
  ( number unitID, boolean sonarStealth ) -> nil
|name = Game.requireSonarUnderWater
|info =
}}


'''Spring.SetUnitStealth'''
  ( number unitID, boolean stealth ) -> nil


{{LuaConstant
'''Spring.SetUnitAlwaysVisible'''
|type = number
  ( number unitID, boolean alwaysVisible ) -> nil
|name = Game.transportAir
|info =
}}


'''Spring.SetUnitLosMask'''
  ( number unitID, number allyTeam, number los | table losTypes ) -> nil
<font color="#55ee99">the 3th argument is either the bit-and combination of the following numbers:
  LOS_INLOS    = 1
  LOS_INRADAR  = 2
  LOS_PREVLOS  = 4
  LOS_CONTRADAR = 8
</font><font color="#55ee99">or a table of the following form:
  losTypes = {
    [los = boolean,]
    [radar = boolean,]
    [prevLos = boolean,]
    [contRadar = boolean,]
  }</font>


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


'''Spring.SetUnitSensorRadius'''
  ( number unitID, string type, number radius ) -> nil | number newRadius
  <font color="#55ee99">type can be:
  "los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"</font>


{{LuaConstant
|type = number
|name = Game.transportHover
|info =
}}


'''Spring.SetRadarErrorParams''' {{new|95.0}}
  (number allyTeamID, number allyteamErrorSize
  [, number baseErrorSize [, number baseErrorMult ]]) -> nil


{{LuaConstant
|type = number
|name = Game.transportGround
|info =
}}


'''Spring.SetUnitPosErrorParams''' {{new|95.0}}
  (number unitID, number posErrorVector.x, number posErrorVector.y, number posErrorVector.z,
  number posErrorDelta.x, number posErrorDelta.y, number posErrorDelta.z
  [ , number nextPosErrorUpdate]) --> nil


{{LuaConstant
== Unit Resourcing ==
|type = number
'''Spring.SetUnitResourcing'''
|name = Game.fireAtKilled
  ( number unitID,
|info =
    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


{{LuaConstant
'''Spring.UseUnitResource'''
|type = number
  ( number unitID, string "m" | "e", number amount ) -> nil | boolean okay
|name = Game.fireAtCrashing
  ( number unitID, { ["m" | "metal" | "e" | "energy"] = amount, ... } ) -> nil | boolean okay
|info =
}}


= Constructor =
'''Spring.SetUnitHarvestStorage''' {{new|97.0}}
  ( number unitid, number metal )


{{LuaConstant
<span class = "note">See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.</span>
|type = bool
|name = Game.constructionDecay
|info =
}}


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


{{LuaConstant
'''Spring.DestroyFeature'''
|type = bool
  ( number featureID ) -> nil
|name = Game.reclaimAllowEnemies
|info =
}}


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


{{LuaConstant
|type = bool
|name = Game.reclaimAllowAllies
|info =
}}


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


{{LuaConstant
'''Spring.SetFeatureResources''' {{new|104.0}}
|type = number
  ( number featureID, number metal, number energy [, number reclaimTime [, number reclaimLeft ]] )
|name = Game.constructionDecayTime
|info =
}}


'''Spring.SetFeatureReclaim'''
  ( number featureID, number reclaimLeft) -> nil


'''Spring.SetFeatureResurrect'''
  ( number featureID, number unitDefID | string unitDefName [, number facing | string "facing" [, number progress ]] ) -> nil
<font color="#55ee99">
  possible values for facing are:
    "south" | "s" | 0
    "east"  | "e" | 1
    "north" | "n" | 2
    "west"  | "w" | 3
</font>
{{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.


{{LuaConstant
'''Spring.SetFeaturePosition'''
|type = number
  ( number featureID, number x, number y, number z [, boolean snapToGround]) -> nil
|name = Game.constructionDecaySpeed
|info =
}}


'''Spring.SetFeatureDirection'''
  ( number featureID, number x, number y, number z ) -> nil


'''Spring.SetFeatureRotation''' {{new|101.0}}
  ( number featureID, number x, number y, number z ) -> nil


{{LuaConstant
'''Spring.SetFeatureVelocity''' {{New|95.0}}
|type = number
|name = Game.multiReclaim
|info =
}}


'''Spring.SetFeaturePhysics''' {{New|95.0}}


{{LuaConstant
(like their feature counterparts at [[Lua_SyncedCtrl#Unit_Control]])
|type = number
|name = Game.reclaimMethod
|info =
}}


'''Spring.SetFeatureMoveCtrl'''
  ( number featureID [, boolean enable [, number* args]]) 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
    ]]]


{{LuaConstant
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.
|type = number
|name = Game.reclaimUnitMethod
|info =
}}


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


{{LuaConstant
'''Spring.SetFeatureAlwaysVisible'''
|type = number
  ( number featureID, boolean enable ) -> nil
|name = Game.reclaimUnitEnergyCostFactor
|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>


{{LuaConstant
'''Spring.SetFeaturePieceCollisionVolumeData''' {{new|101.0}}
|type = number
  ( number featureID, number pieceIndex, boolean enable,
|name = Game.reclaimUnitEfficiency
    number scaleX, number scaleY, number scaleZ,
|info =
    number offsetX, number offsetY, number offsetZ
}}
    [, number volumeType [, number primaryAxis]]
  ) -> nil


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


{{LuaConstant
  <span class=note>check Spring.SetUnitMidAndAimPos for further explanation of the arguments</span>
|type = number
|name = Game.reclaimFeatureEnergyCostFactor
|info =
}}




{{LuaConstant
'''Spring.SetFeatureRadiusAndHeight''' {{new|89.0}}
|type = number
  ( number unitID, number radius, number height ) -> boolean success
|name = Game.repairEnergyCostFactor
|info =
}}


'''Spring.SetFeatureMass''' {{new|101.0}}
  ( number featureID, number mass ) -> nil


{{LuaConstant
'''Spring.SetFeatureBlocking'''
|type = number
  (number featureID, boolean blocking, boolean collidable) --> boolean
|name = Game.resurrectEnergyCostFactor
|info =
}}


'''Spring.SetFeatureBlocking''' {{new|95.0}} changed parameters:
  number featureID,
  boolean isBlocking,
  boolean isSolidObjectCollidable,
  boolean isProjectileCollidable,
  boolean isRaySegmentCollidable,
  boolean crushable,
  boolean blockEnemyPushing,
  boolean blockHeightChanges


{{LuaConstant
= Lua to COB =
|type = number
'''Spring.CallCOBScript'''
|name = Game.captureEnergyCostFactor
  ( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
|info =
    -> nil | number returnValue, number retArg1, number retArg2, ...
}}


= Categories =
'''Spring.CallCOBScriptCB'''<br>
<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>
  ( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
    -> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...


{{LuaConstant
'''Spring.GetCOBScriptID'''
|type = table
   ( number unitID, string funcName ) -> nil | number funcID
|name = Game.springCategories
|info = <font color="#55ee99">
  example: {
    ["vtol"]        = 0,  ["special"]      = 1,  ["noweapon"]    = 2,
    ["notair"]      = 3,  ["notsub"]      = 4,  ["all"]          = 5,
    ["weapon"]      = 6,  ["notship"]      = 7,  ["notland"]      = 8,
    ["mobile"]      = 9,  ["kbot"]        = 10, ["antigator"]    = 11,
    ["tank"]        = 12, ["plant"]        = 13, ["ship"]        = 14,
    ["antiemg"]      = 15, ["antilaser"]    = 16, ["antiflame"]    = 17,
    ["underwater"]   = 18, ["hover"]        = 19, ["phib"]        = 20,
    ["constr"]      = 21, ["strategic"]    = 22, ["commander"]    = 23,
    ["paral"]        = 24, ["jam"]          = 25, ["mine"]        = 26,
    ["kamikaze"]    = 27, ["minelayer"]    = 28, ["notstructure"] = 29,
    ["air"]          = 30
  }</font>
}}




{{LuaConstant
|type = table
|name = Game.armorTypes
|info = <font color="#55ee99">(bidirectional)</font>
<font color="#55ee99">
  example: {
    [1]  = amphibious,  [2] = anniddm,    [3] = antibomber,
    [4]  = antifighter,  [5] = antiraider,  [6] = atl,
    [7]  = blackhydra,  [8] = bombers,    [9] = commanders,
    [10] = crawlingbombs, ...


    ["amphibious"]  = 1, ["anniddm"]    = 2, ["antibomber"] = 3
<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>
    ["antifighter"] = 4, ["antiraider"] = 5, ["atl"]        = 6
    ["blackhydra"]  = 7, ["bombers"]    = 8, ["commanders"] = 9
    ["crawlingbombs"]= 10, ...
  }</font>
}}


= Water Visuals =
'''Spring.GetUnitCOBValue'''
{{removed|104.0}} - No longer constant as are now runtime mutable (Use gl.GetWaterRendering(name) instead).
  ( 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>


{{LuaConstant
'''Spring.SetUnitCOBValue'''
|type = bool
  ( number unitID, number COBValue, number param1 [,number param2] ) -> nil
|name = Game.waterVoid
  <span class=note>you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]</span>
|info =
  <span class=note> also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]</span>
}}


= Give Order =
<font color="#55ee99">options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation)<br>
see [[Lua CMDs]] for relevant constants
</font>


{{LuaConstant
'''Spring.GiveOrderToUnit'''
|type = bool
  ( number unitID,
|name = Game.waterPlane
    number cmdID,
|info =
    params = {number, etc...},
}}
    options = {"alt", "ctrl", "shift", "right"} ) -> nil


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


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


{{LuaConstant
'''Spring.GiveOrderArrayToUnitMap'''
|type = string
  ( unitMap = { [number unitID] = dontCare, etc... },
|name = Game.waterTexture
    orderArray = {
|info =
      { number cmdID,
}}
        {number, etc...},    <font color="#55ee99">params</font>
        {"alt", "ctrl", "shift", "right"}  <font color="#55ee99">options</font>
      }, ..
    }
  ) -> nil


'''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


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


{{LuaConstant
'''Spring.RemoveGrass'''
|type = string
  ( number x, number z ) -> nil
|name = Game.waterFoamTexture
|info =
}}


== Heightmap ==
<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'''
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil


{{LuaConstant
'''Spring.AdjustHeightMap''' <span class="note">(heightmap[x][z] += height;)</span>
|type = string
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil
|name = Game.waterNormalTexture
|info =
}}


'''Spring.RevertHeightMap'''
  ( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil


{{LuaConstant
|type = number
|name = Game.waterRepeatX
|info =
}}






{{LuaConstant
'''Spring.SetHeightMapFunc'''
|type = number
  ( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
|name = Game.waterRepeatY
<span class="note">Example code:</span><code><pre>
|info =
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)
</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>






{{LuaConstant
|type = number
|name = Game.waterSurfaceAlpha
|info =
}}




{{LuaConstant
|type = number
|name = Game.waterSpecularFactor
|info =
}}


'''Spring.LevelSmoothMesh'''
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil
'''Spring.AdjustSmoothMesh'''
  ( number x1, number z1 [, number x2, number z2], number height ) -> nil
'''Spring.RevertSmoothMesh'''
  ( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil


{{LuaConstant
'''Spring.SetSmoothMeshFunc'''
|type = number
  ( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
|name = Game.waterFresnelMin
'''Spring.AddSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
|info =
  ( number x, number z, number height ) -> nil | number newHeight
}}
'''Spring.SetSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
  ( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff


== TerrainTypes ==
'''Spring.SetMapSquareTerrainType'''
  ( number x, number z, int newType ) -> nil | int oldType
'''Spring.SetTerrainTypeData'''
  ( int typeIndex
  [, number speedTanks = nil ]
  [, number speedKBOTs = nil ]
  [, number speedHovers = nil ]
  [, number speedShips = nil ] ) -> nil | boolean true


{{LuaConstant
'''Spring.SetSquareBuildingMask''' {{new|103.0}}
|type = number
  ( number x, number z, int mask ) -> nil
|name = Game.waterFresnelMax
|info =
}}


See also {{xtaglink|Gamedev:UnitDefs|buildingMask}} unitdef tag.


{{LuaConstant
== MetalAmount ==
|type = number
'''Spring.SetMetalAmount''' {{new|83.0}}
|name = Game.waterFresnelPower
  ( number x, number z, number metalAmount)
|info =
<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>
}}


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


'''Spring.EditUnitCmdDesc'''
  ( number unitID, number cmdDescID, table cmdArray ) -> nil
<font color="#55ee99">
  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, ... } ]
  }
</font>
{{var|queueing}} is {{new|101.0}} and allows custom commands to be non-queueing (handy for state toggles).


{{LuaConstant
'''Spring.InsertUnitCmdDesc'''
|type = table
  ( number unitID [, number cmdDescID ] , table cmdArray ) -> nil
|name = Game.waterCausticTextures
|info = <font color="#55ee99">= {"tex1","tex2",..}</font>
}}


'''Spring.RemoveUnitCmdDesc'''
  ( number unitID [, number cmdDescID ] ) -> nil


{{LuaConstant
= Other =
|type = color
'''Spring.SetNoPause'''
|name = Game.waterAbsorb
  ( boolean noPause ) -> nil
|info = <font color="#55ee99">= { number r, number g, number b}</font>
}}


'''Spring.SetUnitToFeature'''
  ( boolean tofeature ) -> nil


{{LuaConstant
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)
|type = color
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]
|name = Game.waterBaseColor
|info =
}}


'''Spring.SetExperienceGrade'''
  ( number expGrade [, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]] ) -> nil


{{LuaConstant
  expGrade defines how often UnitExperience() will be called,
|type = color
  Prior to 104.0 it is based on the following equation:
|name = Game.waterMinColor
    (int) [exp/(exp+1)] / expGrade
|info =
  Post 104.0 it is the raw change.
}}


'''Spring.SpawnExplosion''' {{new|104.0}}
  ( number posX = 0, number posY = 0, number posZ = 0,
    number dirX = 0, number dirY = 0, number dirZ = 0,
    table explosionParams
  ) -> nil


{{LuaConstant
  <span class=note>possible keys of explosionParams are:
|type = color
    weaponDef = number,
|name = Game.waterSurfaceColor
    owner = number,
|info =  
    hitUnit = number,
}}
    hitFeature = number,
    craterAreaOfEffect = number,
    damageAreaOfEffect = number,
    edgeEffectiveness = number,
    explosionSpeed = number,
    gfxMod = number,
    impactOnly = boolean,
    ignoreOwner = boolean,
    damageGround = boolean,
  </span>


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




{{LuaConstant
'''Spring.SpawnCEG'''
|type = color
  ( string "cegname" | number cegID,
|name = Game.waterSpecularColor
    number posX = 0, number posY = 0, number posZ = 0,
|info =  
    number dirX = 0, number dirY = 0, number dirZ = 0,
}}
    number radius = 0, number damage = 0
  ) -> nil | boolean success, cegID
<span class="warning">cegID new in 95.0</span>


'''Spring.SpawnSFX''' {{new|104.0}}
  ( 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
    [, boolean absolute ]
  ) -> nil | boolean success


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.


{{LuaConstant
= Projectiles =
|type = color
'''Spring.SpawnProjectile'''
|name = Game.waterPlaneColor
  ( number weaponDefID, table projectileParams ) -> nil | number projectileID
|info =  
  <span class=note>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,
  </span>


'''Spring.DeleteProjectile''' {{new|101.0}}
  ( number projID ) -> nil
Silently removes projectiles (no explosion).


{{LuaConstant
'''Spring.SetProjectileTarget'''
|type = color
|name = Game.fogColor
|info = {{removed|101.0}} (Use gl.GetAtmosphere("fogColor") instead)
}}


<span class = "warning">Pre 95.0:</span>  ( number projectileID,
    [ number targetID, string targetTypeStr ] | [ number posX, number posY, number posZ ] )
    -> nil | boolean validTarget


{{LuaConstant
<span class = "warning">Post 95.0:</span>  ( number projectileID,
|type = color
    [ number targetID [, number targetType]]  | [number posX, number posY, number posZ])
|name = Game.groundAmbientColor
    --> nil | boolean validTarget
|info = {{removed|101.0}} (Use gl.GetSun("ambient") instead)
  <span class=note>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
  </span>


'''Spring.SetProjectileIgnoreTrackingError''' {{new|101.0}}
  ( number projID, bool ignore ) -> nil
'''Spring.SetProjectileIsIntercepted''' {{new|99.0}}
  ( number projID ) -> nil


{{LuaConstant
'''Spring.SetProjectileMoveControl''' <span class=note>(disables engine movecontrol, so lua can fully control the physics)</span>
|type = color
  ( number projID, boolean enable ) -> nil
|name = Game.groundSpecularColor
'''Spring.SetProjectilePosition'''
|info = {{removed|101.0}} (Use gl.GetSun("specular") instead)
  ( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
}}
'''Spring.SetProjectileVelocity'''
  ( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
  ( number projID ) -> nil
'''Spring.SetProjectileGravity'''
  ( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle''' {{new|95.0}} Deprecated
  ( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed''' {{new|95.0}} Deprecated
  ( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec''' {{new|95.0}} Deprecated
  ( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
  ( number projID, string ceg_name ) -> nil


'''Spring.SetPieceProjectileParams''' {{new|95.0}}
  (number projectileID,
  [ number explosionFlags, [ number spinAngle, [ number spinSpeed,
  [ number spinVector.x, [ number spinVector.y, [ number spinVector.z ]]]]]]) --> nil


{{LuaConstant
'''Spring.SetProjectileAlwaysVisible''' {{new|95.0}}  
|type = color
    (number projectileID, boolean alwaysVisible) --> nil
|name = Game.groundSunColor
|info = {{removed|101.0}} (Use gl.GetSun("diffuse") instead)
}}


'''Spring.SetProjectileDamages''' {{new|101.0}}
  ( number unitID, number weaponNum, table damages ) -> nil
  ( number unitID, number weaponNum, string key, number value ) -> nil
  <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>


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

Revision as of 15:00, 2 March 2021

Development < Lua Scripting < User:Master-athmos


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

No description available


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

No description available


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

No description available

Development < Lua Scripting < User:Master-athmos

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

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

Spring.SetUnitTooltip 

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

Spring.SetUnitHealth 

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

Spring.SetUnitMaxHealth 

 ( number unitID, number maxHealth ) -> nil

Spring.AddUnitDamage 

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

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

Spring.SetUnitStockpile 

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

Spring.SetUnitExperience 

 ( number unitID, number experience ) -> nil

Spring.SetUnitFuel Removed from version 101.0 

 ( number unitID, number fuel ) -> nil

Spring.SetUnitCrashing New in version 83.0 

 ( number unitID, boolean crashing ) -> boolean success

Spring.SetUnitLineage Removed from version 83.0 

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

Spring.SetUnitNeutral 

 ( number unitID, boolean neutral ) -> nil

Spring.SetUnitTarget userTarget & success new in version 95.0, setting nil target new in 99.0, weaponNum new in 102.0 

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

Spring.SetUnitMaxRange 

 ( number unitID, number maxRange ) -> nil

Spring.SetUnitMass New in version 101.0 

 ( number unitID, number mass ) -> nil

Spring.SetUnitBlocking crushable new in version 85.0 

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

Spring.SetUnitBlocking New in version 95.0 changed parameters: 

 number unitID,
 boolean isBlocking,
 boolean isSolidObjectCollidable,
 boolean isProjectileCollidable,
 boolean isRaySegmentCollidable,
 boolean crushable,
 boolean blockEnemyPushing,
 boolean blockHeightChanges

Spring.SetUnitMetalExtraction    "depth" corresponds to metal extraction rate (value range similar to "extractsMetal" unitDef) 

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

Spring.SetUnitBuildSpeed 

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

Spring.SetUnitNanoPieces New in version 92.0 

 ( number builderID, table pieces ) -> nil

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

Spring.UnitAttach New in version 101.0 

 ( number transporterID, number passengerID, number pieceNum ) -> nil

Spring.UnitDetach New in version 101.0 

 ( number passengerID ) -> nil

Spring.UnitDetachFromAir New in version 101.0 

 ( number passengerID ) -> nil

Spring.SetUnitLoadingTransport New in version 101.0 

 ( number passengerID, number transportID ) -> nil

Disables collisions between the two units to allow colvol intersection during the approach.

Spring.SetUnitPieceParent New in version 101.0 

 ( number unitID, number AlteredPiece, number ParentPiece ) -> nil

Changes the pieces hierarchy of a unit, by attaching a piece to a new parent.

Spring.SetUnitPieceMatrix New in version 104.0 

 ( number unitID, number pieceNum, table matrix )

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 armorMultiple new in version 0.83.x 

 ( number unitID, boolean armored [, number armorMultiple] ) -> nil

Spring.SetUnitShieldState 

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

Spring.SetUnitFlanking 

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

Spring.SetUnitWeaponState 

 ( number unitID, number weaponNum, table states ) -> nil
 ( number unitID, number weaponNum, string key, number value ) -> nil
 format of the states table:
   {
     ["reloadState"     = number value,]
     ["reloadFrame"     = number value,] (synonym for reloadState!)
     ["reloadTime"      = number value,]
     ["accuracy"        = number value,]
     ["sprayAngle"      = number value,]
     ["range"           = number value,] (*)
     ["projectileSpeed" = number value,]
     ["burst"           = number value,]
     ["burstRate"       = number value,]
     ["projectiles"     = number value,]
     ["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 New in version 101.0 

 ( number unitID, number weaponNum | "selfDestruct" | "explode", table damages ) -> nil
 ( number unitID, number weaponNum | "selfDestruct" | "explode", string key, number value ) -> nil
 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 offsetX,
   number vType, number tType, number Axis
 ) -> nil
 enum COLVOL_TYPES {
     COLVOL_TYPE_DISABLED = -1,
     COLVOL_TYPE_ELLIPSOID = 0,
     COLVOL_TYPE_CYLINDER,
     COLVOL_TYPE_BOX,
     COLVOL_TYPE_SPHERE,
     COLVOL_NUM_TYPES       // number of non-disabled collision volume types
   };
   enum COLVOL_TESTS {
     COLVOL_TEST_DISC = 0,
     COLVOL_TEST_CONT = 1,
     COLVOL_NUM_TESTS = 2   // number of tests
   };
   enum COLVOL_AXES {
     COLVOL_AXIS_X   = 0,
     COLVOL_AXIS_Y   = 1,
     COLVOL_AXIS_Z   = 2,
     COLVOL_NUM_AXES = 3    // number of collision volume axes
   };

Spring.SetUnitPieceCollisionVolumeData 

 ( number unitID, number pieceIndex, boolean enable, 
   number scaleX, number scaleY, number scaleZ,
   number offsetX, number offsetY, number offsetZ
   [, number volumeType [, number primaryAxis]]
 ) -> nil

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

Spring.SetUnitTravel 

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

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

 (number unitID, number goalx, number goaly, number goalz 
 [, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )

New in version 98.0 moveRaw: allow unit to dumbly move to a coordinate without calculating path.

Spring.SetUnitLandGoal New in version 101.0 

 (number unitID, number goalx, number goaly, number goalz [, number goalRadius ] ) -> nil

Used in conjunction with Spring.UnitAttach et al to re-implement old airbase & fuel system in lua.

Spring.ClearUnitGoal New in version 102.0 

 (number unitID) -> nil

Spring.SetUnitPhysics drag new in version 95.0 

 ( 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,
 ) -> nil

Spring.SetUnitPosition 

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

Spring.SetUnitDirection New in version 90.0 

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

Spring.SetUnitVelocity 

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

Spring.SetUnitRotation 

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

Spring.AddUnitImpulse 

 ( number unitID, number x, number y, number z [, decayRate ] ) -> nil

Spring.AddUnitSeismicPing 

 ( number unitID, number pingSize ) -> nil

Spring.RemoveBuildingDecal 

 ( number unitID ) -> nil

Spring.SetUnitMidAndAimPos New in version 89.0 

 ( number unitID, 
   number mpx, number mpy, number mpz, 
   number apx, number apy, number apz, 
   [, boolean relative] ) -> boolean success

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 or unit coordinates?


Spring.SetUnitRadiusAndHeight New in version 89.0 

 ( number unitID, number radius, number height ) -> boolean success

Spring.UnitWeaponFire 

 ( number unitID, number weaponID ) -> nil

Spring.UnitWeaponHoldFire 

 ( number unitID, number weaponID ) -> nil

Unit LOS

Spring.SetUnitCloak 

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

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

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

Spring.SetUnitSonarStealth 

 ( number unitID, boolean sonarStealth ) -> nil

Spring.SetUnitStealth 

 ( number unitID, boolean stealth ) -> nil

Spring.SetUnitAlwaysVisible 

 ( number unitID, boolean alwaysVisible ) -> nil

Spring.SetUnitLosMask 

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

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

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

or a table of the following form: 

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

Spring.SetUnitLosState 

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

Spring.SetUnitSensorRadius 

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


Spring.SetRadarErrorParams New in version 95.0 

 (number allyTeamID, number allyteamErrorSize 
 [, number baseErrorSize [, number baseErrorMult ]]) -> nil


Spring.SetUnitPosErrorParams New in version 95.0 

 (number unitID, number posErrorVector.x, number posErrorVector.y, number posErrorVector.z,
 number posErrorDelta.x, number posErrorDelta.y, number posErrorDelta.z
 [ , number nextPosErrorUpdate]) --> nil

Unit Resourcing

Spring.SetUnitResourcing 

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


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

Spring.AddUnitResource 

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

Spring.UseUnitResource 

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

Spring.SetUnitHarvestStorage New in version 97.0 

 ( number unitid, number metal )

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 ]]] ) -> number featureID

Spring.DestroyFeature 

 ( number featureID ) -> nil

Spring.TransferFeature 

 ( number featureID, number teamID ) -> nil


Feature Control

Spring.SetFeatureHealth 

 ( number featureID, number health) -> nil

Spring.SetFeatureResources New in version 104.0 

 ( number featureID, number metal, number energy [, number reclaimTime [, number reclaimLeft ]] )

Spring.SetFeatureReclaim 

 ( number featureID, number reclaimLeft) -> nil

Spring.SetFeatureResurrect 

 ( number featureID, number unitDefID | string unitDefName [, number facing | string "facing" [, number progress ]] ) -> nil


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

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.

Spring.SetFeaturePosition 

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

Spring.SetFeatureDirection 

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

Spring.SetFeatureRotation New in version 101.0 

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

Spring.SetFeatureVelocity New in version 95.0

Spring.SetFeaturePhysics New in version 95.0

(like their feature counterparts at Lua_SyncedCtrl#Unit_Control)

Spring.SetFeatureMoveCtrl 

 ( number featureID [, boolean enable [, number* args]]) 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, boolean noSelect ) -> nil

Spring.SetFeatureAlwaysVisible 

 ( number featureID, boolean enable ) -> nil

Spring.SetFeatureCollisionVolumeData 

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

Spring.SetFeaturePieceCollisionVolumeData New in version 101.0 

 ( number featureID, number pieceIndex, boolean enable, 
   number scaleX, number scaleY, number scaleZ,
   number offsetX, number offsetY, number offsetZ
   [, number volumeType [, number primaryAxis]]
 ) -> nil

Spring.SetFeatureMidAndAimPos New in version 89.0 

 ( number unitID, 
   number mpx, number mpy, number mpz, 
   number apx, number apy, number apz, 
   [, boolean relative] ) -> boolean success

 check Spring.SetUnitMidAndAimPos for further explanation of the arguments


Spring.SetFeatureRadiusAndHeight New in version 89.0 

 ( number unitID, number radius, number height ) -> boolean success

Spring.SetFeatureMass New in version 101.0 

 ( number featureID, number mass ) -> nil

Spring.SetFeatureBlocking 

 (number featureID, boolean blocking, boolean collidable) --> boolean

Spring.SetFeatureBlocking New in version 95.0 changed parameters: 

 number featureID,
 boolean isBlocking,
 boolean isSolidObjectCollidable,
 boolean isProjectileCollidable,
 boolean isRaySegmentCollidable,
 boolean crushable,
 boolean blockEnemyPushing,
 boolean blockHeightChanges

Lua to COB

Spring.CallCOBScript 

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

Spring.CallCOBScriptCB
broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement 

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

Spring.GetCOBScriptID 

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


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

Spring.GetUnitCOBValue 

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

Spring.SetUnitCOBValue 

 ( number unitID, number COBValue, number param1 [,number param2] ) -> nil
 you 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"} ) -> nil

Spring.GiveOrderToUnitMap 

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

Spring.GiveOrderToUnitArray 

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

Spring.GiveOrderArrayToUnitMap 

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

Spring.GiveOrderArrayToUnitArray 

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

Ground

Grass

Spring.AddGrass 

 ( number x, number z ) -> nil

Spring.RemoveGrass 

 ( number x, number z ) -> 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 ) -> nil

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

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

Spring.RevertHeightMap 

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



Spring.SetHeightMapFunc 

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

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 can only be called in SetHeightMapFunc() 

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

Spring.SetHeightMap can only be called in SetHeightMapFunc() 

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

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




Spring.LevelSmoothMesh 

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

Spring.AdjustSmoothMesh 

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

Spring.RevertSmoothMesh 

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

Spring.SetSmoothMeshFunc 

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

Spring.AddSmoothMesh can only be called in SetSmoothMeshFunc() 

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

Spring.SetSmoothMesh can only be called in SetSmoothMeshFunc() 

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

TerrainTypes

Spring.SetMapSquareTerrainType 

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

Spring.SetTerrainTypeData 

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

Spring.SetSquareBuildingMask New in version 103.0 

 ( number x, number z, int mask ) -> nil

See also buildingMask unitdef tag.

MetalAmount

Spring.SetMetalAmount New in version 83.0 

 ( number x, number z, number metalAmount)

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 ) -> 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 ) -> nil

Spring.RemoveUnitCmdDesc 

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

Other

Spring.SetNoPause 

 ( boolean noPause ) -> nil

Spring.SetUnitToFeature 

 ( boolean tofeature ) -> 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 ]]] ) -> 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 New in version 104.0 

 ( number posX = 0, number posY = 0, number posZ = 0,
   number dirX = 0, number dirY = 0, number dirZ = 0,
   table explosionParams
 ) -> nil

 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 cegID,
   number posX = 0, number posY = 0, number posZ = 0,
   number dirX = 0, number dirY = 0, number dirZ = 0,
   number radius = 0, number damage = 0
 ) -> nil | boolean success, cegID

cegID new in 95.0

Spring.SpawnSFX New in version 104.0 

 ( 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
   [, boolean absolute ]
 ) -> nil | boolean success

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 ) -> 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 New in version 101.0 

 ( number projID ) -> nil

Silently removes projectiles (no explosion).

Spring.SetProjectileTarget

Pre 95.0: ( number projectileID, 

   [ number targetID, string targetTypeStr ] | [ number posX, number posY, number posZ ] ) 
   -> nil | boolean validTarget

Post 95.0: ( number projectileID, 

   [ number targetID [, number targetType]]  |  [number posX, number posY, number posZ]) 
   --> nil | boolean 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 New in version 101.0 

 ( number projID, bool ignore ) -> nil

Spring.SetProjectileIsIntercepted New in version 99.0 

 ( number projID ) -> nil

Spring.SetProjectileMoveControl (disables engine movecontrol, so lua can fully control the physics) 

 ( number projID, boolean enable ) -> nil

Spring.SetProjectilePosition 

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

Spring.SetProjectileVelocity 

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

Spring.SetProjectileCollision 

 ( number projID ) -> nil

Spring.SetProjectileGravity 

 ( number projID [, number grav = 0] ) -> nil

Spring.SetProjectileSpinAngle New in version 95.0 Deprecated 

 ( number projID [, number spinAngle = 0] ) -> nil

Spring.SetProjectileSpinSpeed New in version 95.0 Deprecated 

 ( number projID [, number speed = 0] ) -> nil

Spring.SetProjectileSpinVec New in version 95.0 Deprecated 

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

Spring.SetProjectileCEG 

 ( number projID, string ceg_name ) -> nil

Spring.SetPieceProjectileParams New in version 95.0 

 (number projectileID,
 [ number explosionFlags, [ number spinAngle, [ number spinSpeed,
 [ number spinVector.x, [ number spinVector.y, [ number spinVector.z ]]]]]]) --> nil

Spring.SetProjectileAlwaysVisible New in version 95.0 

   (number projectileID, boolean alwaysVisible) --> nil

Spring.SetProjectileDamages New in version 101.0 

 ( number unitID, number weaponNum, table damages ) -> nil
 ( number unitID, number weaponNum, string key, number value ) -> nil
 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=User:Master-athmos&oldid=20933"