Spring - User contributions [en]

Gamedev:PublicRepos

2022-03-13T20:44:31Z

Picassoct: /* Known Repos */

==What Is This?==
This is a small collection of publicly known and readable code repositories for established Spring games. The intention being to provide a wealth of examples to all game developers from noob to pro.

Most of these repositories can be downloaded with one of the [[Rapid_Tags]].

== Known Repos ==
[https://github.com/KingRaptor/air-raid-spring Air Raid]

[https://github.com/balanced-annihilation Balanced Annihilation]

[https://github.com/spring-archive/basically-ota BOTA]

[https://github.com/spring-archive/conflictterra Conflict Terra]

[http://www.petro.darkstars.co.uk/damned/ Damned]

[https://github.com/EvolutionRTS/Evolution-RTS Evolution RTS]

[https://github.com/SpringCabal/Gravitas Gravitas]

[https://github.com/imperialwinter/swiw.sdd Imperial Winter]

[https://bitbucket.org/PicassoCT/journeywar Journeywar]

[https://github.com/PicassoCT/MOSAIC MOSAIC]

[https://github.com/jk3064?tab=repositories jK]
* [[Chili]]
* [[LUPS]]
* Custom-Unit-Shader-Framework
* [[Mapdev:Main#Blueprint | Map-Blueprint]]

[https://github.com/David-Becker/mods KDR_11k]
* Cuberors' Finest
* CvC
* Doserz
* Fibre
* GINTA
* Gun Wings Test
* Light Side of Spring
* MicroModules
* Pong

[https://github.com/SpringMCLegacy/SpringMCLegacy MechCommander: Legacy]

[https://github.com/spring1944/spring1944 Spring: 1944]

[https://github.com/spring-archive/springtanks Spring Tanks]

[https://github.com/spring-archive/springtutorialgame.sdd/ Spring Tutorial Game]

[https://github.com/n3wm1nd/TA Tech Annihilation]

[https://github.com/KingRaptor/THIS THIS]

[http://code.google.com/p/xta-springrts/ XTA]

[https://github.com/ZeroK-RTS/Zero-K/ Zero-K]

[[Category:Game Dev]]
[[Category:Download Systems]]

Gamedev:PublicRepos

2022-03-13T20:44:04Z

Picassoct: /* Known Repos */

==What Is This?==
This is a small collection of publicly known and readable code repositories for established Spring games. The intention being to provide a wealth of examples to all game developers from noob to pro.

Most of these repositories can be downloaded with one of the [[Rapid_Tags]].

== Known Repos ==
[https://github.com/KingRaptor/air-raid-spring Air Raid]

[https://github.com/balanced-annihilation Balanced Annihilation]

[https://github.com/spring-archive/basically-ota BOTA]

[https://github.com/spring-archive/conflictterra Conflict Terra]

[http://www.petro.darkstars.co.uk/damned/ Damned]

[https://github.com/EvolutionRTS/Evolution-RTS Evolution RTS]

[https://github.com/SpringCabal/Gravitas Gravitas]

[https://github.com/imperialwinter/swiw.sdd Imperial Winter]

[https://bitbucket.org/PicassoCT/journeywar Journeywar]

[https://github.com/PicassoCT/MOSAIC]

[https://github.com/jk3064?tab=repositories jK]
* [[Chili]]
* [[LUPS]]
* Custom-Unit-Shader-Framework
* [[Mapdev:Main#Blueprint | Map-Blueprint]]

[https://github.com/David-Becker/mods KDR_11k]
* Cuberors' Finest
* CvC
* Doserz
* Fibre
* GINTA
* Gun Wings Test
* Light Side of Spring
* MicroModules
* Pong

[https://github.com/SpringMCLegacy/SpringMCLegacy MechCommander: Legacy]

[https://github.com/spring1944/spring1944 Spring: 1944]

[https://github.com/spring-archive/springtanks Spring Tanks]

[https://github.com/spring-archive/springtutorialgame.sdd/ Spring Tutorial Game]

[https://github.com/n3wm1nd/TA Tech Annihilation]

[https://github.com/KingRaptor/THIS THIS]

[http://code.google.com/p/xta-springrts/ XTA]

[https://github.com/ZeroK-RTS/Zero-K/ Zero-K]

[[Category:Game Dev]]
[[Category:Download Systems]]

Rapid Tags

2022-03-13T20:32:50Z

Picassoct:

Most of these tags are automaticly updated from [[Gamedev:PublicRepos]].

{| class="wikitable sortable" Width="100%"
|-
! Tag !! Name
|-
| ba-tronic:latest || Balanced Annihilation Tronic
|-
| ba:stable || Balanced Annihilation
|-
| ba:test || Balanced Annihilation
|-
| bac:stable || BA Chicken Defense
|-
| bac:test || BA Chicken Defense
|-
| bar:test || Balanced Annihilation Reloaded
|-
| brickcraft:epenis || BrickCraft epenis
|-
| brickcraft:latest || BrickCraft
|-
| btl:latest || BattleTech: Legacy
|-
| ct:stable || Conflict Terra
|-
| ct:test || Conflict Terra
|-
| ea:latest || Eternal Annihilation
|-
| evo:stable || Evolution RTS
|-
| evo:test || Evolution RTS
|-
| ft:test || Frontier
|-
| jw:test || Journeywar
|-
| kp:latest || Kernel Panic
|-
| micromodules:latest || Micro Modules
|-
| mosaic:stable || MOSAIC
|-
| mw:latest || Micronwars
|-
| nota:latest || NOTA
|-
| nota:stable || NOTA
|-
| operationx:latest || Special BA
|-
| pa:latest || Progressive Annihilation
|-
| ra:latest || Research Annihilation Concept
|-
| s44-deployment:test || Spring: 1944
|-
| s44:latest || Spring: 1944
|-
| s44:stable || Spring: 1944
|-
| sa:latest || Supreme Annihilation
|-
| spring-features:stable || Spring Features
|-
| specialba:latest || Special BA
|-
| springtanks:latest || Spring Tanks
|-
| staticfriction:stable || Static Friction
|-
| staticfriction:testing || Static Friction
|-
| ta_factions:latest || TA : Factions
|-
| tc:stable || The Cursed
|-
| tc:test || The Cursed
|-
| void:latest || Void
|-
| xta:fixed || XTA
|-
| xta:latest || XTA
|-
| xta:test || XTA
|-
| xtar:latest || XTAR
|-
| zk:stable || Zero-K
|-
| zk:test || Zero-K
|-
| zkc:latest || Zero-K
|-
| zkdota:stable || Zero-K DOTA
|-
| zkdota:test || Zero-K DOTA
|-
| zkr:alpha || Zero-K Raid
|-
| zkr:latest || Zero-K Raid
|-
| zkr:test || Zero-K Raid
|}

[[Category:Download Systems]]
[[Category:Game Dev]]

Lua SyncedCtrl

2022-02-11T11:30:23Z

Picassoct: /* Unit Control */ https://github.com/spring/spring/blob/a8cf33ad1d2ac775e6008cd04baa7e859d1f23ec/rts/Lua/LuaSyncedCtrl.cpp#L530

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

= Game End =

{{LuaCallout
|prefix = Spring.
|name = KillTeam
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|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.
}}

{{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}} 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.

{{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 = 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.
}}

{{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 = New since 102.0. 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 =

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

{{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: "m" = metal "e" = energy "ms" = metal storage "es" = energy storage 
}}

{{LuaCallout
|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}} 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}} 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}} Changes access to global line of sight for a team and its allies.
}}

= Unit Handling =

{{LuaCallout
|prefix = Spring.
|name = CreateUnit
|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. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 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.
}}

{{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. reclaimed := Don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
}}

{{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 ==

{{LuaCallout
|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 =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "tooltip"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|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 =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxHealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|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.
}}

{{LuaCallout
|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 =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} experience
|arg3 = {{type|number}} buildPercent
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|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}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCrashing
|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. UserTarget & success new in version 95.0, setting nil target new in version 99.0, weaponNum new in version 102.0.
}}

{{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}} 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}} This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end 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}} 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}} 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}} 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 = armorMultiple new in version 0.83.x
}}

{{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 =
}}
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.


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


{{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 =
}}
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
};


{{LuaCallout
|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 = Used by default commands to get in build-, attackrange etc. {{new|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]
}}

{{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}} 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 = Drag new in version 95.0
}}

{{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 = RemoveBuildingDecal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|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}} 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?
}}

{{LuaCallout
|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}}
}}

{{LuaCallout
|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 ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitCloak
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} cloaked {{pipe}} {{type|number}} scriptCloak {{bracket}}
|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: 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.
}}

{{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: 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] }
}}

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

{{LuaCallout
|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: "los", "airLos", "radar", "sonar", "seismic", "radarJammer", "sonarJammer"
}}

{{LuaCallout
|prefix = Spring.
|name = SetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|number }} allyteamErrorSize {{bracket}}
|arg3 = {{type|number}} baseErrorSize {{bracket}}
|arg4 = {{type|number}} baseErrorMult {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPosErrorParams
|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 ==

{{LuaCallout
|prefix = Spring.
|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]" unconditional {{pipe}} conditional use {{pipe}} make 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}} See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

= Feature Handling =

{{LuaCallout
|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 =
}}

{{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 ==

{{LuaCallout
|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 =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} unitDefID {{pipe}} {{type|string}} unitDefName {{bracket}}
|arg3 = {{type|number}} facing {{pipe}} {{type|string}} "facing" {{bracket}}
|arg4 = {{type|number}} progress {{rbracket}}{{rbracket}}
|arg5 =
|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. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 3
}}

{{LuaCallout
|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 =
}}

{{LuaCallout
|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 =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{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}}
}}

{{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: If enable is true: {{bracket}}, velVector(x,y,z) -- initial velocity for feature {{bracket}}, accVector(x,y,z) -- acceleration added every frame{{rbracket}}{{rbracket}} If enable is false: {{bracket}}, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl {{bracket}}, impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl {{bracket}}, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl{{rbracket}}{{rbracket}}{{rbracket}} 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}} 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}} Changed parameters.
}}

= Lua to COB =

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

{{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 =
}}

{{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! You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCOBValue
|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! 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 =

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.

{{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 =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = unitMap = { {{bracket}}{{type|number}} unitID{{rbracket}} = example, 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 =
}}

{{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=
== Grass ==

{{LuaCallout
|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 ==
Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is [[Lua_ConstGame|Game.squareSize]].

{{LuaCallout
|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 =
}}

{{LuaCallout
|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 =
}}

{{LuaCallout
|prefix = Spring.
|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()
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>

{{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: 
If =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished.
}}

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

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

{{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 ==

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTerrainType
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} newType
|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 ==

{{LuaCallout
|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}} 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! 

{{LuaCallout
|prefix = Spring.
|name = EditUnitCmdDesc
|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 ],
[ 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, ... } ]
}</pre>
{{var|queueing}} is {{new|101.0}} and allows custom commands to be non-queueing (handy for state toggles).

{{LuaCallout
|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 =

{{LuaCallout
|prefix = Spring.
|name = SetNoPause
|arg1 = {{type|bool}} noPause
|arg2 =
|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. Prior to 104.0 it is based on the following equation: (int) {{bracket}}exp/(exp+1){{rbracket}} / expGrade 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>

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

{{LuaCallout
|prefix = Spring.
|name = SpawnSFX
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} sfxID
|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 =

{{LuaCallout
|prefix = Spring.
|name = SpawnProjectile
|arg1 = {{type|number}} weaponDefID
|arg2 = {{type|table}} projectileParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} projectileID
|info =
}}
<pre>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</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}} Silently removes projectiles (no explosion).
}}

Pre 95.0:
{{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 =
}}

Post 95.0:
{{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]]

Lua Beginners FAQ

2021-12-12T09:36:00Z

Picassoct: /* Complex Lifecycles */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

This page is an introduction to using Lua in Spring - it only tries to answer general questions, for more specific Questions please ask in the forum.

==Where should I start?==

You can start by reading general Lua tutorials [http://lua-users.org/wiki/LuaTutorial here].

After that, you could look at the example widget [[Lua:Tutorial_GettingStarted|here]], and try to add some functionality of your own!

Once you're a pro, have a look at the game repos [https://springrts.com/wiki/Gamedev:PublicRepos here], especially their /luaui/Widgets and /luarules/gadgets dirs.

==Where can I find help?==

You can find documentation of Springs Lua API on the [[Lua_Scripting|Lua_Scripting]] page. Discussion of lua coding takes place on the [https://springrts.com/wiki/Read_Me_First lobby] in #moddev and #lua, and there is also a [https://springrts.com/phpbb/viewforum.php?f=23 Lua sub-forum].

==How do I open ".lua" files?==

Any text editor is enough. On Windows i.e. use [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++]. There are also IDEs able to work with Lua, such as Eclipse, if you look for them.

==What is a call-in? And a call-out?==

Call-ins are functions defined in your script that Spring calls when a determined event takes place. For example, the widget:Initialize() call-in is run by Spring when the widget is loaded.
Call-outs are functions defined in Spring you can run at whichever moment you desire. For example, when you call Spring.GetUnitTeam(unitID), the engine returns the teamID of the unit identified by "unitID".

==What is the difference between unsynced and synced lua code?==

Synced code is code that runs, identically and at the same time, on every connected client. In practice, this means code which controls the game state. Unsynced code is code that will run differently (or maybe not at all) on each connected client. Typically, this means the user interface.

For example, lua code to make units explode if they fell down a cliff would need to be synced. But, code that warned a player when one of their own units was getting near a cliff edge, would need to be unsynced.

==What is the difference between LuaUI, LuaRules, widgets and gadgets?==

Spring allows various [[Lua:Environments|Lua Environments]], each with differing functionality. Inside each Lua environment, developers can write addons, which are self-contained pieces of code. There are:
* LuaUI: Used for unsynced GUI related code. Addons in here are often called widgets. Clients can (if the game permits it) control which widgets are running. Widgets contain only unsynced code. They can be bundled inside the game, or loaded from the users "Spring/LuaUI/Wigets" directory.
* LuaRules: Addons in here are often called gadgets. Clients cannot choose which gadgets run. Gadgets can include both synced and unsynced code, and must be bundled inside the game.

Intended for mappers, there is also LuaGaia, which behaves like LuaRules but is separated from it. To see which of the lua environoments has access to which data/functionality, see [[Lua:Environments#Interfaces]] and [[Lua:Callins]].

==What can't Lua do in the current version of Spring?==

Springs Lua interface is very powerful. To work out if some idea is possible you need to ask
* When do I need the engine to tell me something has happened? Check against [[Lua:Callins|Callins]].
* What information will I need to know about the game state? Check against [[Lua_SyncedRead]] (synced) and [[Lua_UnsyncedRead]] (unsynced).
* What do I then need to do about it? Check against [[Lua_SyncedCtrl]] (synced) and[[Lua_UnsyncedCtrl]] (unsynced).
Sometimes you need special functionality, like disk access or OpenGL calls, in which case check against [[Lua_Scripting#Interfaces|Interfaces]].

For completeness, some examples of things you (currently) can't do:
*control the ground LOS - but you can set the los status of units!
*add custom parameters to CEG definitions.

==Complex Lifecycles==

Due to the complexity of the simulation, spring scripts are burdened with the curse of complex lifecyles very similar to https://en.wikipedia.org/wiki/Object_lifetime in programing.

This means, you can not rely on any information about the simulation being valid after as little as 1 frame has passed. Units may have been captured, destroyed or created in this time. Terrain may have been altered.

People usually combat this by creating large amounts of protective boiler plate, checking if a unit still exists, is still on the same team, etc. every time a unitscript, gadget or widget wakes up.

==Where can I find/edit examples?==

You can find some easy example widgets [[Lua:Tutorial_GettingStarted|here]]. The best source of more complicated examples is inside games themselves, in the LuaUI/Widgets and Luarules/gadgets directories. See [[Gamedev:PublicRepos]] for a list of repositories.

To make your own widgets, simply place individual .lua files into your Spring/LuaUI/Widgets dir (create the dir if it is not present. Case-sensitive!!!). Game repositories can be checked out into a folder named "SomeAwesomeGame.sdd", placed in your "/Spring/games" dir; this shoudl give a local copy of the game, recognized by Spring, where you can edit files. Make sure to check the licenses before doing this!

==Can I reload a script without restarting Spring?==

Yes, you can type "/luaui reload" to reload widgets, and if you have "cheats" enabled you can also "/luarules reload" to reload gadgets.

==Why does the print function seem to do nothing?==

Its output is displayed in stdout. If you have no easy way to see it, you can Spring.Echo("some text") which prints to the ingame chat and infolog.txt.

[[Category: Lua]]

Lua Beginners FAQ

2021-12-12T09:33:55Z

Picassoct:

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

This page is an introduction to using Lua in Spring - it only tries to answer general questions, for more specific Questions please ask in the forum.

==Where should I start?==

You can start by reading general Lua tutorials [http://lua-users.org/wiki/LuaTutorial here].

After that, you could look at the example widget [[Lua:Tutorial_GettingStarted|here]], and try to add some functionality of your own!

Once you're a pro, have a look at the game repos [https://springrts.com/wiki/Gamedev:PublicRepos here], especially their /luaui/Widgets and /luarules/gadgets dirs.

==Where can I find help?==

You can find documentation of Springs Lua API on the [[Lua_Scripting|Lua_Scripting]] page. Discussion of lua coding takes place on the [https://springrts.com/wiki/Read_Me_First lobby] in #moddev and #lua, and there is also a [https://springrts.com/phpbb/viewforum.php?f=23 Lua sub-forum].

==How do I open ".lua" files?==

Any text editor is enough. On Windows i.e. use [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++]. There are also IDEs able to work with Lua, such as Eclipse, if you look for them.

==What is a call-in? And a call-out?==

Call-ins are functions defined in your script that Spring calls when a determined event takes place. For example, the widget:Initialize() call-in is run by Spring when the widget is loaded.
Call-outs are functions defined in Spring you can run at whichever moment you desire. For example, when you call Spring.GetUnitTeam(unitID), the engine returns the teamID of the unit identified by "unitID".

==What is the difference between unsynced and synced lua code?==

Synced code is code that runs, identically and at the same time, on every connected client. In practice, this means code which controls the game state. Unsynced code is code that will run differently (or maybe not at all) on each connected client. Typically, this means the user interface.

For example, lua code to make units explode if they fell down a cliff would need to be synced. But, code that warned a player when one of their own units was getting near a cliff edge, would need to be unsynced.

==What is the difference between LuaUI, LuaRules, widgets and gadgets?==

Spring allows various [[Lua:Environments|Lua Environments]], each with differing functionality. Inside each Lua environment, developers can write addons, which are self-contained pieces of code. There are:
* LuaUI: Used for unsynced GUI related code. Addons in here are often called widgets. Clients can (if the game permits it) control which widgets are running. Widgets contain only unsynced code. They can be bundled inside the game, or loaded from the users "Spring/LuaUI/Wigets" directory.
* LuaRules: Addons in here are often called gadgets. Clients cannot choose which gadgets run. Gadgets can include both synced and unsynced code, and must be bundled inside the game.

Intended for mappers, there is also LuaGaia, which behaves like LuaRules but is separated from it. To see which of the lua environoments has access to which data/functionality, see [[Lua:Environments#Interfaces]] and [[Lua:Callins]].

==What can't Lua do in the current version of Spring?==

Springs Lua interface is very powerful. To work out if some idea is possible you need to ask
* When do I need the engine to tell me something has happened? Check against [[Lua:Callins|Callins]].
* What information will I need to know about the game state? Check against [[Lua_SyncedRead]] (synced) and [[Lua_UnsyncedRead]] (unsynced).
* What do I then need to do about it? Check against [[Lua_SyncedCtrl]] (synced) and[[Lua_UnsyncedCtrl]] (unsynced).
Sometimes you need special functionality, like disk access or OpenGL calls, in which case check against [[Lua_Scripting#Interfaces|Interfaces]].

For completeness, some examples of things you (currently) can't do:
*control the ground LOS - but you can set the los status of units!
*add custom parameters to CEG definitions.

==Complex Lifecycles==

Due to the complexity of the simulation, spring scripts are burdened with the curse of complex lifecyles very similar to https://en.wikipedia.org/wiki/Object_lifetime in programing.

This means, you can not rely on any stored data being valid after as little as 1 frame has passed. Units may have been captured, destroyed or created in this time.

People usually combat this by creating large amounts of protective boiler plate, checking if a unit still exists, is still on the same team, etc. every time a unitscript, gadget or widget wakes up.

==Where can I find/edit examples?==

You can find some easy example widgets [[Lua:Tutorial_GettingStarted|here]]. The best source of more complicated examples is inside games themselves, in the LuaUI/Widgets and Luarules/gadgets directories. See [[Gamedev:PublicRepos]] for a list of repositories.

To make your own widgets, simply place individual .lua files into your Spring/LuaUI/Widgets dir (create the dir if it is not present. Case-sensitive!!!). Game repositories can be checked out into a folder named "SomeAwesomeGame.sdd", placed in your "/Spring/games" dir; this shoudl give a local copy of the game, recognized by Spring, where you can edit files. Make sure to check the licenses before doing this!

==Can I reload a script without restarting Spring?==

Yes, you can type "/luaui reload" to reload widgets, and if you have "cheats" enabled you can also "/luarules reload" to reload gadgets.

==Why does the print function seem to do nothing?==

Its output is displayed in stdout. If you have no easy way to see it, you can Spring.Echo("some text") which prints to the ingame chat and infolog.txt.

[[Category: Lua]]

Lua UnsyncedRead

2021-11-17T22:08:43Z

Picassoct: /* Screen Trace */ Does not need a third z argument, but can have a optional argument index (optArgIdx)https://github.com/spring/spring/blob/a8cf33ad1d2ac775e6008cd04baa7e859d1f23ec/rts/Lua/LuaUnsyncedRead.cpp#L1547

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}
=Unsynced Read=

== Replay/Spectating ==

{{LuaCallout
|prefix = Spring.
|name = IsReplay
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isReplay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetReplayLength
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} timeInSeconds
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetSpectatingState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} spectating, {{type|bool}} fullView, {{type|bool}} fullSelect
|info =
}}

== Game/Menu Name ==

{{LuaCallout
|prefix = Spring.
|name = GetGameName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}} Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".
}}

{{LuaCallout
|prefix = Spring.
|name = GetMenuName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}}
}}

== ModUI ==

{{LuaCallout
|prefix = Spring.
|name = GetModUICtrl
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} ModUICtrl
|info =
}}

== MyInfo ==

{{LuaCallout
|prefix = Spring.
|name = GetMyAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyTeamID
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = GetMyPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

{{LuaCallout
|prefix = Spring.
|name = GetLocalPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyID
|info =
}}

== Team/Player Info ==

{{LuaCallout
|prefix = Spring.
|name = GetPlayerRoster
|arg1 = {{bracket}}{{type|number}} sortType{{rbracket}} {{pipe}} {{bracket}}{{type|number}} sortType{{rbracket}}, {{bracket}}{{type|bool}} showPathingPlayers{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} playerTable
|info = "playerTable" contains:
}}
<pre>playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

if pingTime == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamOrigColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerTraffic
|arg1 = {{type|number}} playerID {{bracket}}
|arg2 = {{type|number}} packetID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} traffic
|info =
}}

== Sound ==

{{LuaCallout
|prefix = Spring.
|name = GetSoundStreamTime
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playedTime, {{type|number}} totalTime,
|info =
}}

== Camera ==

{{LuaCallout
|prefix = Spring.
|name = GetCameraNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|camName}} = {{type|number}} camNum, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }
|info = See [[Lua_camState]] for details about Spring.GetCameraState output.
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraPosition
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraDirection
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} forward_x, {{type|number}} forward_y, {{type|number}} forward_z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraFOV
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} vFov, {{type|number}} hFov
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraVectors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} vectorTable
|info = vectorTable contains:
}}
<pre>vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}</pre>

=== Inview ===

{{LuaCallout
|prefix = Spring.
|name = GetVisibleUnits
|arg1 = {{bracket}}{{type|number}} teamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{rbracket}}{{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVisibleFeatures
|arg1 = {{bracket}}{{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{bracket}}
|arg4 = {{type|bool}} geos = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAABBInView
|arg1 = {{type|number}} minX, {{type|number}} minY, {{type|number}} minZ
|arg2 = {{type|number}} maxX, {{type|number}} maxY, {{type|number}} maxZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsSphereInView
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} radius {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitIcon
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitIcon
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInView
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitVisible
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|bool}} checkIcons {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isVisible
|info =
}}

=== Screen Trace ===

{{LuaCallout
|prefix = Spring.
|name = WorldToScreenCoords
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TraceScreenRay
|arg1 = {{type|number}} mouseX, {{type|number}} mouseY, {{bracket}}
|arg2 = {{type|bool}} onlyCoords {{bracket}}
|arg3 = {{type|bool}} useMinimap {{bracket}}
|arg4 = {{type|bool}} includeSky {{bracket}}
|arg5 = {{type|bool}} ignoreWater {{bracket}}
|arg6 ={{type|number}} D {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} unit, {{type|number}} unitID {{pipe}} {{type|string}} feature, {{type|number}} featureID {{pipe}} {{type|string}} ground, {{type|table}} coords = { {{bracket|1}} = {{type|number}} x, {{bracket|2}} = {{type|number}} y, {{bracket|3}} = {{type|number}} z }
|info = {{new|101.0}}
}}
<pre>Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")</pre>

{{LuaCallout
|prefix = Spring.
|name = GetPixelDir
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{New|95.0}}
}}

=== Screen & Window Geometry ===

{{LuaCallout
|prefix = Spring.
|name = GetViewGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} viewSizeX, {{type|number}} viewSizeY, {{type|number}} viewPosX, {{type|number}} viewPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWindowGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} winSizeX, {{type|number}} winSizeY, {{type|number}} winPosX, {{type|number}} winPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetScreenGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} screenSizeX, {{type|number}} screenSizeY, {{type|number}} ZERO, {{type|number}} ZERO
|info = Is missing multiscreen support!
}}

== Unit ==

{{LuaCallout
|prefix = Spring.
|name = IsUnitAllied
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitViewPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransformMatrix
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} invert = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} a11, {{type|number}} a12 ..., {{type|number}} a44 (4x4 matrix)
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

=== Selected Units ===

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsSorted
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{bracket}}{{type|number}} unitID{{rbracket}}, etc... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCounts
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCount
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitSelected
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isSelected
|info =
}}

=== Unit Groups ===

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

{{LuaCallout
|prefix = Spring.
|name = GetGroupList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|number}} = {{type|number}} unitCount, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedGroup
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIName
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} aiName
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} aiName, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnits
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsSorted
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCounts
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCount
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

== Feature ==

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetVisibleProjectiles
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|bool}} addSyncedProjectiles = true {{bracket}}
|arg3 = {{type|bool}} addWeaponProjectiles = true {{bracket}}
|arg4 = {{type|bool}} addPieceProjectiles = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} projectileID, ... }
|info =
}}

== UI ==

{{LuaCallout
|prefix = Spring.
|name = GetUICommands
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { command={{type|string}}, description={{type|string}}, synced={{type|bool}}, cheat={{type|bool}}}, ... }
|info = {{new|101.0}} Returns a list of available [[UI commands]].
}}

=== GUI Settings ===

{{LuaCallout
|prefix = Spring.
|name = IsGUIHidden
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isHidden
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveShadows
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShadows
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveAdvShading
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWaterMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|string}} mode
|info =
}}
<pre> mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown</pre>

{{LuaCallout
|prefix = Spring.
|name = GetMapDrawMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "normal" {{pipe}} {{type|string}} "height" {{pipe}} {{type|string}} "metal" {{pipe}} {{type|string}} "pathTraversability" {{pipe}} {{type|string}} "los"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawSelectionInfo
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} drawSelectInfo
|info = Returns whether "Selected units" text is displayed.
}}

=== Unit & Feature GUI States ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitLuaDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} unitDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noMinimap
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLuaDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} featureDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

=== Minimap ===

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} sizeX, {{type|number}} sizeY, {{type|bool}} minimized, {{type|bool}} maximized
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapDualScreen
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} false {{pipe}} {{type|string}} "left" {{pipe}} {{type|string}} "right"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAboveMiniMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAbove
|info =
}}

=== (Build-)Menu ===

{{LuaCallout
|prefix = Spring.
|name = GetActiveCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDefaultCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDescs
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
[1] = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDesc
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetCmdDescIndex
|arg1 = {{type|number}} cmdID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActivePage
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pageNum, {{type|number}} maxPages
|info =
}}

=== Build Facing ===

{{LuaCallout
|prefix = Spring.
|name = GetBuildFacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetBuildSpacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spacing
|info =
}}

=== GatherMode & InvertQueueKey ===

{{LuaCallout
|prefix = Spring.
|name = GetGatherMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gatherMode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetInvertQueueKey
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} queueKey
|info =
}}

=== Mouse States ===

{{LuaCallout
|prefix = Spring.
|name = GetMouseState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|bool}} leftPressed, {{type|bool}} middlePressed, {{type|bool}} rightPressed, {{type|bool}} offscreen
|info = {{new|104.0}} Sixth return value offscreen. X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner. For world coordinates see Spring.TraceScreenRay.
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseCursor
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string }} name, {{type|number}} scale
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseStartPosition
|arg1 = {{type|number}} mouseButton
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pressedX, {{type|number}} pressedY, {{type|number}} camPosX, {{type|number}} camPosY, {{type|number}} camPosZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

=== (Hot-)Keys ===

{{LuaCallout
|prefix = Spring.
|name = GetKeyState
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} keyState
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetModKeyState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} alt, {{type|bool}} ctrl, {{type|bool}} meta, {{type|bool}} shift
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPressedKeys
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} code{{rbracket}} = {{type|bool}}, {{bracket}}{{type|string}} name{{rbracket}} = {{type|bool}}, ... }
|info = {{new|99.0}}: {{type|string}} name
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyCode
|arg1 = {{type|string}} keysym
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} keyCode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeySymbol
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "keysym1", {{type|string}} "keysym2"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyBindings
|arg1 = {{type|string}} keyset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} keyBindings
|info = keyBindings contains:
}}
<pre>keyBindings = {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActionHotKeys
|arg1 = {{type|string}} action
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} hotKey, ... }
|info =
}}

=== Console ===

{{LuaCallout
|prefix = Spring.
|name = GetLastMessagePositions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { {{type|number}} x, {{type|number}} y, {{type|number}} z }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConsoleBuffer
|arg1 = {{bracket}}{{type|number}} maxLines{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { text = {{type|string}}, priority = {{type|number}} }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCurrentTooltip
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} tooltip
|info =
}}

=== LOS Colors ===

{{LuaCallout
|prefix = Spring.
|name = GetLosViewColors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} always = {r,g,b}, {{type|table}} LOS = {r,g,b}, {{type|table}} radar = {r,g,b}, {{type|table}} jam = {r,g,b}, {{type|table}} radar2 = {r,g,b}
|info = {{new|100}}
}}

== Config ==

{{LuaCallout
|prefix = Spring.
|name = GetConfigParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} configParams
|info = Same information as <code>spring --list-config-vars</code> configParams contains:
}}
<pre>configParams = {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetConfigInt
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configInt
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigFloat
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configFloat
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigString
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} configString
|info =
}}

== FPS & GetDrawFrame ==

{{LuaCallout
|prefix = Spring.
|name = GetFPS
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} fps
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} low_16bit, {{type|number}} high_16bit
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVideoCapturingMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} videoCaptureAllowed
|info = {{new|104.0}}
}}

== Time ==

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = {{new|98.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} finishedLoading, {{type|bool}} loadedFromSave, {{type|bool}} locallyPaused, {{type|bool}} laggingWrtExpectedFromSimtime
|info = {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimeOffset
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} offset
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLastUpdateSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lastUpdateSeconds
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHasLag
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasLag
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = {{new|102.0}} Get a timer for the start of the frame, this should give better results for camera interpolations.
}}

{{LuaCallout
|prefix = Spring.
|name = DiffTimers
|arg1 = {{type|timer}} cur
|arg2 = {{type|timer}} ago {{bracket}}
|arg3 = {{type|bool}} inMilliseconds {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info = {{New|95.0}} Optional third argument (boolean) to return dt in milliseconds.
}}

== Rendering ==

{{LuaCallout
|prefix = Spring.
|name = GetMapSquareTexture
|arg1 = {{type|number}} texSqrX, {{type|number}} texSqrY
|arg2 = {{type|number}} texMipLvl
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

== Logging ==

{{LuaCallout
|prefix = Spring.
|name = GetLogSections
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} logSections = { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }
|info =
}}

== Misc ==

{{LuaCallout
|prefix = Spring.
|name = GetClipboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} text
|info = {{new|98.0}}
}}

[[category: Lua]]

Lua ConstGame

2021-10-17T19:09:08Z

Picassoct: /* Engine */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

= Engine =

Word of advice. Do not modify tables provided by the engine - like Game. Many of them are internally implemented as engine calls.

{{LuaConstant
|type = string
|name = Game.version
|info = {{removed|104.0}} Now in [[Lua_ConstEngine]]
}}

{{LuaConstant
|type = string
|name = Game.buildFlags
|info = {{removed|104.0}} Now in [[Lua_ConstEngine]]
}}

{{LuaConstant
|type = number
|name = Game.gameID
|info = Replaced in 89.0 with GameID(string gameID) synced callin
}}

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

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

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

{{LuaConstant
|type = number
|name = Game.squareSize
|info = Divide Game.mapSizeX or Game.mapSizeZ by this to get engine's "mapDims" coordinates
}}

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

= Host =

{{LuaConstant
|type = number
|name = Game.gameMode
|info = Removed from version 83.x
}}

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

{{LuaConstant
|type = bool
|name = Game.commEnds
|info = Removed from version 83.x
}}

{{LuaConstant
|type = bool
|name = Game.limitDGun
|info = Removed from version 83.x
}}

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

= Checksums =

{{LuaConstant
|type = string
|name = Game.mapChecksum
|info =
}}

{{LuaConstant
|type = string
|name = Game.modChecksum
|info =
}}

= Map =

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

{{LuaConstant
|type = string
|name = Game.mapName
|info =
}}

{{LuaConstant
|type = string
|name = Game.mapDescription
|info = = {{type|string}} '''Game.mapHumanName'''
}}

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

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

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

{{LuaConstant
|type = number
|name = Game.mapSizeX
|info = in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates
}}

{{LuaConstant
|type = number
|name = Game.mapSizeZ
|info = in worldspace/opengl coords. Divide by Game.squareSize to get engine's "mapDims" coordinates
}}

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

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

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

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

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

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

{{LuaConstant
|type = table
|name = Game.envDamageTypes
|info = Containing {def}IDs of environmental-damage sources {{new|104.0}}.
}}

= Mod =

{{LuaConstant
|type = string
|name = Game.gameName
|info = {{new|95.0}}
}}

{{LuaConstant
|type = string
|name = Game.gameShortName
|info = {{new|95.0}}
}}

{{LuaConstant
|type = string
|name = Game.gameVersion
|info = {{new|95.0}}
}}

{{LuaConstant
|type = string
|name = Game.gameMutator
|info = {{new|95.0}}
}}

{{LuaConstant
|type = string
|name = Game.gameDesc
|info = {{new|95.0}}
}}

{{LuaConstant
|type = string
|name = Game.modName
|info = deprecated (it is in contrast to gameName appended with gameVersion!)
}}

{{LuaConstant
|type = string
|name = Game.modShortName
|info = deprecated 
}}

{{LuaConstant
|type = string
|name = Game.modVersion
|info = deprecated 
}}

{{LuaConstant
|type = string
|name = Game.modMutator
|info = deprecated 
}}

{{LuaConstant
|type = string
|name = Game.modDesc
|info = deprecated 
}}

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

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

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

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

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

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

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

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

= Constructor =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

= Categories =

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

{{LuaConstant
|type = table
|name = Game.armorTypes
|info = (bidirectional)

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
["antifighter"] = 4, ["antiraider"] = 5, ["atl"] = 6
["blackhydra"] = 7, ["bombers"] = 8, ["commanders"] = 9
["crawlingbombs"]= 10, ...
}
}}

= Water Visuals =
{{removed|104.0}} - No longer constant as are now runtime mutable (Use gl.GetWaterRendering(name) instead).

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

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

{{LuaConstant
|type = string
|name = Game.waterTexture
|info =
}}

{{LuaConstant
|type = string
|name = Game.waterFoamTexture
|info =
}}

{{LuaConstant
|type = string
|name = Game.waterNormalTexture
|info =
}}

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

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

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

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

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

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

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

{{LuaConstant
|type = table
|name = Game.waterCausticTextures
|info = = {"tex1","tex2",..}
}}

{{LuaConstant
|type = color
|name = Game.waterAbsorb
|info = = { number r, number g, number b}
}}

{{LuaConstant
|type = color
|name = Game.waterBaseColor
|info =
}}

{{LuaConstant
|type = color
|name = Game.waterMinColor
|info =
}}

{{LuaConstant
|type = color
|name = Game.waterSurfaceColor
|info =
}}

{{LuaConstant
|type = color
|name = Game.waterSpecularColor
|info =
}}

{{LuaConstant
|type = color
|name = Game.waterPlaneColor
|info =
}}

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

{{LuaConstant
|type = color
|name = Game.groundAmbientColor
|info = {{removed|101.0}} (Use gl.GetSun("ambient") instead)
}}

{{LuaConstant
|type = color
|name = Game.groundSpecularColor
|info = {{removed|101.0}} (Use gl.GetSun("specular") instead)
}}

{{LuaConstant
|type = color
|name = Game.groundSunColor
|info = {{removed|101.0}} (Use gl.GetSun("diffuse") instead)
}}

[[category: Lua]]

Gamedev:UnitDefs

2021-07-09T08:12:59Z

Picassoct: Undo revision 31609 by Picassoct (talk)

[[Gamedev:Main|Development]] < [[Gamedev:Main]] < {{FULLPAGENAME}}

==Location==
UnitDef files are .lua files stored in the <code>Units/</code> directory of a Spring Game.

==Purpose==
UnitDef files have one purpose; to define the properties of units. They are the main description file for what attributes your unit should have and how it should behave.

==Source==
The engine source code which loads the tags from these files is viewable here:

* {{sourcelink|file=rts/Sim/Units/UnitDef.cpp}}

The engine source which reads the [[#sounds]] subtable can be found here:

* {{sourcelink|file=rts/Sim/Units/UnitDefHandler.cpp}}

==Data Types==
{{DataTypes}}

==Details==
There follows a comprehensive (certain deprecated tags are not present) list of the tags available, their data type, default value and a brief description of what they do. Bear in mind that the source code linked above is the ultimate reference when dealing with these tags.

In lua tables keys (i.e. the tags) should be lower case, here they are represented in camelCase for readability. In your files you may use the <code>lowerkeys</code> function on your final table to ensure the keys are properly cased.

It is usual to name the returned UnitDef table the internal <code>unitName</code> desired for the unit.

===General===
{{tag
|name = name
|type = string
|default = ""
|lua = humanName
|description = This is simply the name of the unit as it appears to the player.}}

{{tag
|name = description
|type = string
|default = name
|lua = tooltip
|description = This is the tooltip description of the unit seen by the player. It defaults to the {{taglink|name}} of the unit.}}

{{tag
|name = buildPic
|type = string
|default = ""
|lua = buildPicName
|description = The filename of the image to be used as the build picture, assumes <code>Unitpics/</code> directory (see [[Gamedev:Buildpics]]).}}

{{tag
|name = objectName
|type = string
|default = ""
|lua = modelname
|description = The filename of the 3D model file for this unit, assumes <code>Objects3D/</code> directory.}}

{{tag
|name = script
|type = string
|default = unitName + ".cob"
|lua = scriptName
|description = The filename of the animation script file for this unit, assumes <code>Scripts/</code> directory. Default assumes .cob file but [[Animation-LuaScripting | LUS]] should be preferred.}}

{{tag
|name = maxDamage
|type = float
|default = 0.0
|lua = health
|description = The base 'hitpoints' the unit will have.}}

{{tag
|name = autoHeal
|type = float
|default = 0.0
|description = How much health the unit will regain every second.}}

{{tag
|name = idleAutoHeal
|type = float
|default = 10.0
|description = How much health the unit will regain every second whilst it is idle.}}

{{tag
|name = idleTime
|type = int
|default = 600
|description = The time in [[frames]] taken until a unit is considered to be idle.}}

{{tag
|name = buildCostMetal
|type = float
|default = 1.0
|lua = metalCost
|description = The amount of metal resource the unit costs to build. Cannot be below <code>1.0</code>.}}

{{tag
|name = buildCostEnergy
|type = float
|default = 0.0
|lua = energyCost
|description = The amount of energy resource the unit costs to build.}}

{{tag
|name = buildTime
|type = float
|default = 0.0
|description = The time taken to build the unit, in conjunction with the {{taglink|workerTime}} of the constructor. In [[Gamedev:UnitsOfMeasurement#Time|Resource Frames]], <code>Time to build = (buildTime / workerTime)</code>. Defaults to <code>0.0</code> but cannot actually be below <code>1.0</code>.}}

{{tag
|name = mass
|type = float
|default = buildCostMetal
|description = The mass of the unit, used in weapon impulse calculations. Cannot be less than <code>1.0</code>.}}

{{tag
|name = reclaimable
|type = bool
|default = true
|description = Can the unit be reclaimed by a builder?}}

{{tag
|name = capturable
|type = bool
|default = true
|description = Can a unit be stolen by a builder using the capture command?}}

{{tag
|name = repairable
|type = bool
|default = true
|description = Can the unit be repaired by a builder?}}

{{tag
|name = maxRepairSpeed
|type = float
|default = 1e20
|description = The maximum cumulative speed at which this unit type can repair a single target.}}

{{tag
|name = iconType
|type = string
|default = "default"
|description = The name of the radar icon type this unit should use (see [[Icontypes.lua]]).}}

{{tag
|name = corpse
|type = string
|default = ""
|lua = wreckName
|description = The name of the feature this unit should leave behind as a wreck when it dies (see [[Gamedev:FeatureDefs]]).}}

{{tag
|name = explodeAs
|type = string
|default = ""
|description = The name of the weapon this unit should explode as when it is killed (see [[Gamedev:WeaponDefs]]).}}

{{tag
|name = selfDestructAs
|type = string
|default = ""
|description = The name of the weapon this unit should explode as when it self destructs (see [[Gamedev:WeaponDefs]]). Also used as the {{taglink|kamikaze}} weapon.}}

===Resources===
{{tag
|name = harvestStorage
|type = float
|default = 0.0
|special = {{new|97.0}}
|description = How much of the metal resource a unit can store when used as an engine-assisted resource 'harvester'. See also [[Lua:Callins#API:UnitHarvestStorageFull|UnitHarvestStorageFull callin]] and [[Lua_SyncedRead#Unit_Informations|Spring.GetUnitHarvestStorage]] and [[Lua_SyncedCtrl#Unit_Resourcing|Spring.SetUnitHarvestStorage]] callouts.}}

{{tag
|name = metalStorage
|type = float
|default = 0.0
|description = The amount of the metal resource storage the unit contributes.}}

{{tag
|name = energyStorage
|type = float
|default = 0.0
|description = The amount of the energy resource storage the unit contributes.}}

{{tag
|name = extractsMetal
|type = float
|default = 0.0
|description = The amount of the metal resource the unit extracts from the ground. The amount extracted depends on the metal map defined in the map itself. Works only for structures.}}

{{tag
|name = windGenerator
|type = float
|default = 0.0
|description = The amount of the energy resource the unit generates which is dependant on the map wind. Works only for structures.}}

{{tag
|name = tidalGenerator
|type = float
|default = 0.0
|description = The amount of the energy resource the unit generates which is dependant on the maps tidal power. Clearly, this only works on water structures.}}

{{tag
|name = metalUse
|type = float
|default = 0.0
|lua = metalUpkeep
|description = The amount of the metal resource the unit consumes per game 'tick' when activated.}}

{{tag
|name = energyUse
|type = float
|default = 0.0
|lua = energyUpkeep
|description = The amount of the energy resource the unit consumes per game 'tick' when activated.}}

{{tag
|name = metalMake
|type = float
|default = 0.0
|description = The amount of the metal resource the unit generates unconditionally per game 'tick'.}}

{{tag
|name = energyMake
|type = float
|default = 0.0
|description = The amount of the energy resource the unit generates unconditionally per game 'tick'.}}

{{tag
|name = makesMetal
|type = float
|default = 0.0
|description = The amount of the energy resource the unit turns into the metal resource per game 'tick'.}}

===Sensors===
{{tag
|name = onOffable
|type = bool
|default = false
|description = Does the unit have an on/off button? Currently the activation status tied to this button also turns sensors (other than LOS) on and off.}}

{{tag
|name = activateWhenBuilt
|type = bool
|default = false
|description = Should the unit's activation status be on or off when it is created?}}

{{tag
|name = sightDistance
|type = float
|default = 0.0
|lua = losRadius
|description = The radius of the units sight (LOS is circular in Spring).
}}

{{tag
|name = airSightDistance
|type = float
|default = 1.5 * sightDistance
|lua = airLosRadius
|description = How far away the unit can see aircraft (and some FX).}}

{{tag
|name = losEmitHeight
|type = float
|default = 20.0
|lua = losHeight
|special = {{new|83.0}}
|description = How high up the unit is the point used to calculate it's LOS vs. the terrain?}}

{{tag
|name = radarEmitHeight
|type = float
|default = 20.0
|lua = radarHeight
|special = {{new|83.0}}
|description = How high up the unit is the point used to calculate it's radar vs. the terrain?}}

{{tag
|name = radarDistance
|type = int
|default = 0
|lua = radarRadius
|description = The radius of the units radar.}}

{{tag
|name = sonarDistance
|type = int
|default = 0
|lua = sonarRadius
|description = The radius of the units sonar.}}

{{tag
|name = radarDistanceJam
|type = int
|default = 0
|lua = jammerRadius
|description = The radius of the units radar jamming.}}

{{tag
|name = sonarDistanceJam
|type = int
|default = 0
|lua = sonarJamRadius
|description = The radius of the units sonar jamming.}}

{{tag
|name = stealth
|type = bool
|default = false
|description = Is the unit undetectable by radar?}}

{{tag
|name = sonarStealth
|type = bool
|default = false
|description = Is the unit undetectable by sonar?}}

{{tag
|name = seismicDistance
|type = int
|default = 0
|lua = seismicRadius
|description = The radius of the unit's seismic (movement) sensor.}}

{{tag
|name = seismicSignature
|type = float
|default = 0 for units with {{taglink|floater}}, {{taglink|canHover}} or {{taglink|canFly}}, otherwise sqrt(mass / 100.0)
|description = How fast the seismic ring expands in [[elmo]]s per frame. Each ping always lasts 15 [[frames]], so this also determines the maximum radius of the seismic ring.}}

====Cloaking====
For units with {{taglink|canCloak|true}}:
{{tag
|name = cloakCost
|type = float
|default = 0.0
|description = The energy cost per tick to cloak the unit while it is stationary.}}

{{tag
|name = cloakCostMoving
|type = float
|default = cloakCost
|description = The energy cost per tick to cloak the unit while it is moving.}}

{{tag
|name = initCloaked
|type = bool
|default = false
|lua = startCloaked
|description = Is the unit cloaked as soon as it is created?}}

{{tag
|name = minCloakDistance
|type = float
|default = 0.0
|description = The minimum distance (radius) which the unit must be from any enemy units to remain cloaked.}}

{{tag
|name = decloakSpherical
|type = bool
|default = true
|description = Does {{taglink|minCloakDistance}} apply in 3D or only 2D? i.e. can aircraft flying above the unit decloak it?}}

{{tag
|name = decloakOnFire
|type = bool
|default = true
|description = Does the unit decloak when it fires a weapon?}}

{{tag
|name = cloakTimeout
|type = int
|default = 128
|description = The minimum time, in [[frames]], between a decloak and subsequent re-cloak.}}

===Commands===
{{tag
|name = canMove
|type = bool
|default = false
|description = Can the unit be issued Move orders?
}}

{{tag
|name = canAttack
|type = bool
|default = true
|description = Can the unit be issued Attack orders?
}}

{{tag
|name = canFight
|type = bool
|default = true
|description = Can the unit be issued Fight orders?
}}

{{tag
|name = canPatrol
|type = bool
|default = true
|description = Can the unit be issued Patrol orders?
}}

{{tag
|name = canGuard
|type = bool
|default = true
|description = Can the unit be issued Guard orders?
}}

{{tag
| name = canCloak
| type = bool
| default = false
| description =
Can the unit be issued Cloak orders?
}}

{{tag
|name = canRepeat
|type = bool
|default = true
|description = Can the unit be issued Repeat orders?
}}

{{tag
|name = canSelfDestruct
|type = bool
|default = true
|lua = canSelfD
|description = Can the unit be issued a self destruct order?
}}

{{tag
|name = moveState
|type = int
|default = -1 for mobile units, 1 for structures
|description = The initial movement state for the unit. Can be {{value|-1}} - Inherits from factory, {{value|0}} - Hold Position, {{value|1}} - Manoeuvre or {{value|2}} - Roam.
}}

{{tag
|name = fireState
|type = int
|default = -1 for units with {{taglink|noAutoFire|false}}, 2 otherwise
|description = The initial firing state for the unit. Can be {{value|-1}} - Inherits from factory, {{value|0}} - Hold Fire, {{value|1}} - Return Fire or {{value|2}} - Fire At Will. Since 104.0 there is an additional value {{value|3}} - Fire At Neutral.
}}

{{tag
|name = noAutoFire
|type = bool
|default = false
|lua = canFireControl
|description = Controls whether or not the unit has a fire state button.
}}

{{tag
|name = canManualFire
|type = bool
|default = false
|description = description = Can the unit be issued ManualFire commands? A ManualFire command will fire any weapons with the {{xtaglink|Gamedev:WeaponDefs|commandfire}} tag.
}}

====Builder Commands====
{{tag
|name = canRestore
|type = bool
|default = builder && {{taglink|terraformSpeed}} > 0
|description = Can the unit be issued restore terrain commands? For builders only.
}}

{{tag
|name = canRepair
|type = bool
|default = builder && {{taglink|repairSpeed}} > 0
|description = Can the unit be issued repair commands? For builders only.
}}

{{tag
|name = canReclaim
|type = bool
|default = builder && {{taglink|reclaimSpeed}} > 0
|description = Can the unit be issued reclaim commands? For builders only.
}}

{{tag
|name = canResurrect
|type = bool
|default = builder && {{taglink|resurrectSpeed}} > 0
|description = Can the unit be issued resurrection commands? For builders only.
}}

{{tag
|name = canCapture
|type = bool
|default = builder && {{taglink|captureSpeed}} > 0
|description = Can the unit be issued capture commands? For builders only.
}}

===Builder===
{{tag
|name = builder
|type = bool
|default = false
|lua = isBuilder
|description = Is the unit a builder?}}

{{tag
|name = buildDistance
|type = float
|default = 128.0
|description = How far away from itself the unit can build, measured to the centre of the unit being built. The minimum value is <code>38.0</code>.}}

{{tag
|name = buildRange3D
|type = bool
|default = false
|description = Does the builders {{taglink|buildDistance}} apply in all 3 dimensions or only 2?}}

{{tag
|name = workerTime
|type = float
|default = 0.0
|lua = buildSpeed
|description = How fast the builder builds, used in conjunction with the {{taglink|buildTime}} of the unit being built. Effectively, <code>Time to build = buildTime / workerTime</code>. If this value is <= <code>0.0</code> then {{taglink|builder}} is set to false.}}

{{tag
|name = repairSpeed
|type = float
|default = workerTime
|description = How fast the builder can repair other units.}}

{{tag
|name = reclaimSpeed
|type = float
|default = workerTime
|description = How fast the builder can reclaim other units and features.}}

{{tag
|name = resurrectSpeed
|type = float
|default = workerTime
|description = How fast the builder can resurrect corpse features back into living units.}}

{{tag
|name = captureSpeed
|type = float
|default = workerTime
|description = How fast the builder can capture other units.}}

{{tag
|name = terraformSpeed
|type = float
|default = workerTime
|description = How fast the builder levels and restores terrain.}}

{{tag
|name = canAssist
|type = bool
|default = builder
|description = Can the builder assist other constructions?}}

{{tag
|name = canBeAssisted
|type = bool
|default = true
|description = Can the builder be assisted by other builders?}}

{{tag
|name = canSelfRepair
|type = bool
|default = false
|description = Can the builder repair itself?}}

{{tag
|name = showNanoSpray
|type = bool
|default = true
|description = Does the builder emit OTA-style nanospray whilst constructing?}}

{{tag
|name = nanoColor
|type = float[3]
|default = {0.2, 0.7, 0.2} aka green
|description = The RGB colour of a builders' emitted nano particles if {{taglink|showNanoSpray|true}}. Also controls the RBG colour of a unit's own nanoframe if {{taglink|showNanoFrame|true}}.}}

{{tag
|name = fullHealthFactory
|type = bool
|defaul[[elmo]]s
|description = If <code>true</code>, units are repaired before they are allowed to leave the factory i.e. units from this factory will be healed back to 100% health if they are damaged during construction.}}

{{tag
|name = isAirbase
|type = bool
|default = false
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = Is this unit an airbase? Aircraft may land and repair on units which are airbases.}}

===Movement & Placement===
{{tag
|name = footprintX
|type = int
|default = 1
|description =
How wide the unit is in footprint units, left to right. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Movedefs.lua|footprintX}} of its {{taglink|movementClass}}. Also used for obstacle avoidance.
}}

{{tag
|name = footprintZ
|type = int
|default = 1
|description =
How wide the unit is in footprint units, top to bottom. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Movedefs.lua|footprintZ}} of its {{taglink|movementClass}}. Also used for obstacle avoidance.
}}

{{tag
|name = yardmap
|type = string
|default = ""
|description =
Used to determine a structure from a mobile unit. A string of characters which defines in detail each 'footprint square' of the structure. Each footprint square may be:
:: <code>y</code> - 'Yard' - Always open, unblocking,
:: <code>c</code> - 'Construction' - Open and unblocking only while constructing (for factories, controlled via <code>COB.YARD_OPEN</code> see [[Animation-LuaCallouts#Other]]),
:: <code>i</code> - 'Inversed Construction' - Closed and blocking only while constructing (for factories, controlled via <code>COB.YARD_OPEN</code> see [[Animation-LuaCallouts#Other]]) ({{new|89.0}}),
:: <code>g</code> - 'Geothermal' - Flags that the unit must be placed over a {{xtaglink|Gamedev:FeatureDefs|geoThermal}} feature, does not actually count as a square,
:: <code>h</code> - 'High Resolution' - Indicates that the yardmap will use double resolution with four times as many characters. Must be the '''first''' character, and does not count as a square itself ({{new|93.0}}),
::<code>o</code> - 'Obstacle' - Always closed, blocking, all other chars are treated the same way.
: Tip: 'Draw' out the yardmap over multiple lines. As of 89.0 all whitespace characters are ignored, including newlines.
}}

{{tag
|name = buildingMask
|type = int
|default = 1
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of ground that this structure can be built on. Each digit of binary that is set to one means that a ground square with the corresponding digit set via [[Lua_SyncedCtrl#Ground|Spring.SetSquareBuildingMask]] can be built on.
}}

{{tag
|name = levelGround
|type = bool
|default = false
|description = For structures. Does the constructor have to level the ground underneath the build area before beginning to build the structure?
}}

{{tag
|name = movementClass
|type = string
|default = ""
|lua = moveDef.name
|description = The name of the movement type a mobile, non aircraft, unit should use. See [[Movedefs.lua]].
}}

{{tag
|name = canHover
|type = bool
|default = false
|special = Removed in 95.0
|description = Is the unit a hovercraft? Hovercraft can cross water of any depth without a speed penalty. Hover's must also have <code>HOVER</code> within the name of their {{taglink|movementClass}} (see [[Movedefs.lua]]).
}}

{{tag
|name = floater
|type = bool
|default = false if a {{taglink|moveClass}} is defined, if not true if {{taglink|waterline|true}}, false otherwise
|description = When a mobile unit is crossing water, or a structure is placed on water, does it float on top of the water or crawl / lay on the sea bed?
}}

{{tag
|name = upright
|type = bool
|default = false
|description = Does the unit follow the terrain or always remain upright? Generally used for walkers.
}}

{{tag
|name = maxSlope
|type = float
|default = 0.0
|lua = maxHeightDif
|description = The maximum slope a building can be placed on. Mobile unit's use the {{xtaglink|Movedefs.lua|maxSlope}} set in their {{taglink|movementClass}}. The value is in degrees and is clamped between <code>0.0</code> and <code>89.0</code>. This value is converted to a "maximum allowed height difference" (call it M), which involves a hard-coded constant. When a building gets placed, the height of each of its footprint squares is compared to a reference height (calculated for the build position). If the difference exceeds M for any square, that build position is rejected. The value readable from lua has been changed from that in the unitdef and reflects the internal engine value.
}}

{{tag
|name = minWaterDepth
|type = float
|default = -10e6
|description = The minimum depth of water a building can be placed on. Mobile unit's use the {{xtaglink|Movedefs.lua|minWaterDepth}} set in their {{taglink|movementClass}}.
}}

{{tag
|name = maxWaterDepth
|type = float
|default = 10e6
|description = The maximum depth of water a building can be placed on. Mobile unit's use the {{xtaglink|Movedefs.lua|maxWaterDepth}} set in their {{taglink|movementClass}}.
}}

{{tag
|name = waterline
|type = float
|default = 0.0
|description = How low in the water does a ship sit? Higher values means the ship is lower in the water.
}}

{{tag
|name = minCollisionSpeed
|type = float
|default = 1.0
|description = The minimum net impact speed that will cause a unit to be damaged by collisions with another unit.
}}

{{tag
|name = pushResistant
|type = bool
|default = false
|description = Can the unit be pushed around by other units? Turning it on doesn't remove all pushing but is a marked improvement.
}}

{{tag
|name = maxVelocity
|type = float
|default = 0.0
|lua = speed
|description = The maximum speed attainable by the unit in [[elmo]]s per frame. If the value is -ve, the absolute value is used.
}}

{{tag
|name = maxReverseVelocity
|type = float
|default = 0.0
|lua = rSpeed
|special = {{new|99.0}}
|description = The maximum speed attainable by the unit in reverse in [[elmo]]s per frame. If the value is -ve, the absolute value is used.
}}

{{tag
|name = acceleration
|type = float
|default = 0.5
|lua = maxAcc
|description = The acceleration of the unit, in [[elmo]]s per frame2. If the value is -ve, the absolute value is used.
}}

{{tag
|name = brakeRate
|type = float
|default = acceleration
|lua = maxDec
|description = The deceleration of the unit, in [[elmo]]s per frame2. If the value is -ve, the absolute value is used. For units with {{taglink|canFly|true}} this is multiplied by <code>0.1</code>. Prior to 95.0 this was scaled by 0.1 for aircraft and the default was 3x acceleration.
}}

{{tag
|name = myGravity
|type = float
|default = 0.4
|description = As Spring aircraft are slower than real aircraft this tag allows to lower gravity to compensate. Multiplies against map gravity for aircraft, replaces map gravity for ground vehicles if non-zero.
}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = How fast the unit can turn. <code>degrees per seconds = 0.16 * turnRate</code>.
}}

{{tag
|name = turnInPlace
|type = bool
|default = true
|description = Does the unit turn on the spot (like a person or tank) or must it be moving forwards to turn (like a car).
}}

{{tag
|name = turnInPlaceSpeedLimit
|type = float
|default = A complex formula based on {{taglink|turnRate}} and {{taglink|maxVelocity}}
|description = For units with {{taglink|turnInPlace|false}}, this defines the minimum speed it will slow down to (the speed at which the turn is actually performed can be higher depending on the angular difference and {{taglink|turnRate}}).
}}

{{tag
| name = turnInPlaceAngleLimit
| type = float
| default = 0.0
| special = {{new|86.0}}
| description = For units with {{taglink|turnInPlace|true}}, defines the maximum angle (in degrees) of a turn above which it starts to brake.
}}

{{tag
|name = blocking
|type = bool
|default = true
|description = Does the unit block the movement of other units? (Mines, i.e. non-mobile units with the {{taglink|kamikaze}} tag default to <code>false</code>).
}}

{{tag
|name = crushResistance
|type = float
|default = mass
|special = {{new|85.0}}
|description = How resistant is the unit to being crushed? Any [[Movedefs.lua|'''MoveClass''']] with a {{xtaglink|Movedefs.lua|crushStrength}} greater than this will crush the unit - IFF this has been enabled via [[Lua_SyncedCtrl#Unit_Control|Spring.SetUnitBlocking]] and the collider impulse exceeds that of the colidee.
}}

===Flanking===
{{tag
|name = flankingBonusMode
|type = int
|default = flankingBonus.defaultMode set in [[Modrules.lua]]
|description = The mode of operation of Spring's inbuilt flanking system. Can be <code>0</code> - No flanking bonus. Mode <code>1</code> builds up the ability to move over time, and swings to face attacks, but does not respect the way the unit is facing. Mode <code>2</code> also can swing, but moves with the unit as it turns. Mode <code>3</code> stays with the unit as it turns and otherwise doesn't move, the ideal mode to simulate something such as tank armour.
}}

{{tag
|name = flankingBonusDir
|type = float[3]
|default = {0.0, 0.0, 1.0}
|description = This is the direction vector where the armour is facing; i.e. where the least damage is applied. The default is straight forwards.
}}

{{tag
|name = flankingBonusMax
|type = float
|default = 1.9
|description = The maximum multiplier to the damage dealt, when a unit is hit from the opposite direction to {{taglink|flankingBonusDir}}.
}}

{{tag
|name = flankingBonusMin
|type = float
|default = 0.9
|description = The minimum multiplier to the damage dealt, when a unit is hit from the same direction as {{taglink|flankingBonusDir}}.
}}

{{tag
|name = flankingBonusMobilityAdd
|type = float
|default = 0.01
|description = This defines the ability of {{taglink|flankingBonusDir}} to move over time. Its value is added to the mobility every [[SlowUpdate]]. When the unit is attacked, the build up mobility value is multiplied by a vector facing the attack, which is added to {{taglink|flankingBonusDir}}.
}}

===Aircraft===
{{tag
|name = canFly
|type = bool
|default = false
|description = Can the unit fly, i.e. is it an aircraft?
}}

{{tag
|name = canSubmerge
|type = bool
|default = false
|description = Can the aircraft land underwater?
}}

{{tag
|name = factoryHeadingTakeoff
|type = bool
|default = true
|description = Controls the take-off behaviour of aircraft with {{taglink|hoverAttack|true}}. <code>true</code> means planes start matching their heading right after taking off from the pad, <code>false</code> means they maintain the heading of the pad until reaching {{taglink|cruiseAlt}}.
}}

{{tag
|name = collide
|type = bool
|default = true
|description = Does the unit collide with other aircraft, or can it occupy the same space?
}}

{{tag
|name = hoverAttack
|type = bool
|default = false
|description = Controls whether the aircraft flys and attacks like a fighter/bomber or a helicopter/gunship.
}}

{{tag
|name = airStrafe
|type = bool
|default = true
|description = For aircraft with {{taglink|hoverAttack|true}}, controls if the unit strafes side to side while attacking or remains stationary.
}}

{{tag
|name = cruiseAlt
|type = float
|default = 0.0
|lua = wantedHeight
|description = The altitude in [[elmo]]s which the unit attempts to fly at while cruising.
}}

{{tag
|name = airHoverFactor
|type = float
|default = -1.0
|lua = dlHoverFactor
|description = For aircraft with {{taglink|hoverAttack|true}}, less then <code>0</code> means it can land and >= <code>0</code> indicates how much the unit will move during hovering on the spot.
}}

{{tag
|name = bankingAllowed
|type = bool
|default = true
|description = For aircraft with {{taglink|hoverAttack|true}}, controls whether or not the unit banks when moving turning.
}}

{{tag
|name = useSmoothMesh
|type = bool
|default = true
|description = Does the aircraft follow the real map terrain or the special smoothed out navigation mesh generated by Spring specifically for aircraft?} Can become problematic for construction aircrafts, building in canyons.
}}

{{tag
|name = maxFuel
|type = float
|default = 0.0
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = The maximum flight time in seconds before aircraft must return to an airbase to refuel.
}}

{{tag
|name = refuelTime
|type = float
|default = 5.0
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = The time in seconds required to refuel the aircraft at an airbase.
}}

{{tag
|name = minAirbasePower
|type = float
|default = 0.0
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = The minimum {{taglink|workerTime}} an airbase must have to repair / refuel this aircraft.
}}

{{tag
|name = canLoopbackAttack
|type = bool
|default = false
|description = Can the aircraft perform an [http://en.wikipedia.org/wiki/Immelmann_turn Immelmann turn]?
}}

====Advanced Air Tags====
The following set of tags are not well understood and using non-default values can lead to undesired flight behaviours. 
{{tag
|name = wingDrag
|type = float
|default = 0.07
|description = The drag caused by the aircraft's wing. Clamped between <code>0.0</code> and <code>1.0</code>.
}}

{{tag
|name = wingAngle
|type = float
|default = 0.08
|description = The angle between the front and the wing plane.
}}

{{tag
|name = frontToSpeed
|type = float
|default = 0.1
|description = How far nose can be unaligned to speed vector before accelleration is applied.
}}

{{tag
|name = speedToFront
|type = float
|default = 0.07
|description = Rate for the nose to align to new (true) direction change. Values above 0.1 may lead to cumulative speedup issues.
}}

{{tag
|name = crashDrag
|type = float
|default = 0.005
|description = The drag used when crashing. Clamped between <code>0.0</code> and <code>1.0</code>.
}}

{{tag
|name = maxBank
|type = float
|default = 0.8
|description = The maximum roll (z-axis rotation) the aircraft can achieve.
}}

{{tag
|name = maxPitch
|type = float
|default = 0.45
|description = The maximum pitch (x-axis rotation) the aircraft tries to keep.
}}

{{tag
|name = turnRadius
|type = float
|default = 500.0
|description = Hint to Spring unit AI about the required turning radius.
}}

{{tag
|name = verticalSpeed
|type = float
|default = 3.0
|description = The speed of takeoff and landing, at least for gunships ({{taglink|hoverAttack|true}}).
}}

{{tag
|name = maxAileron
|type = float
|default = 0.015
|description = The maximum turn speed around the roll (z) axis.
}}

{{tag
|name = maxElevator
|type = float
|default = 0.01
|description = The maximum turn speed around the pitch (x) axis.
}}

{{tag
|name = maxRudder
|type = float
|default = 0.004
|description = The maximum turn speed around the yaw (y) axis.
}}

{{tag
|name = maxAcc
|type = float
|default = 0.065
|description = The maximum acceleration or 'engine power' of the aircraft.
}}

{{tag
|name = attackSafetyDistance
|type = float
|default = 0
| special = Exists only in version 99.0
|description = Fighters abort dive toward target if within attackSafetyDistance and try to climb back to normal altitude while still moving toward target. It's disabled by default. Set to half of the minimum weapon range to avoid collisions, enemy fire, AOE damage. If set to greater than the weapon range, the unit will fly over the target like a bomber. This tag was removed in version 100.0 and changed to a [[Lua_MoveCtrl#MoveType-Controlling|Spring.SetMoveTypeData]] key.
}}

====Flares====
The following set of tags are rarely used and are hardcoded to only work vs. missile weapons. The texture is hardcoded to be <code>flareprojectiletexture</code> defined in [[Resources.lua]]. 
{{tag
|name = canDropFlare
|type = bool
|default = false
|description = Can this aircraft drop flares to distract missile weapons?
}}

{{tag
|name = flareReload
|type = float
|default = 5.0
|lua = flareReloadTime
|description = The time in seconds between successive flare drops.
}}

{{tag
|name = flareDelay
|type = float
|default = 0.3
|description = The delay between detecting an incoming missile and launching flares. Multiplied by a random number between 1 and 16.
}}

{{tag
|name = flareEfficiency
|type = float
|default = 0.5
|description = The probability that an incoming missile will target the flare instead of the aircraft.
}}

{{tag
|name = flareDropVector
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The direction vector which flares are emitted in.
}}

{{tag
|name = flareTime
|type = int
|default = 3
|description = The lifetime of a dropped flare in [[frames]].
}}

{{tag
|name = flareSalvoSize
|type = int
|default = 4
|description = How many flares are dropped at once?
}}

{{tag
|name = flareSalvoDelay
|type = int
|default = 0
|description = The delay in [[frames]] between the release of each individual flare in a burst.
}}

===Transports===
{{tag
|name = transportSize
|type = int
|default = 0
|description = The size of units that the transport can pick up, in terms of the passengers {{taglink|footprintX}}.}}

{{tag
|name = minTransportSize
|type = int
|default = 0
|description = The smallest size of unit that the transport can pick up, in terms of the passengers {{taglink|footprintX}}.}}

{{tag
|name = transportCapacity
|type = int
|default = 0
|description = The total number of units that the transport can pick up, with each unit multiplied by it's {{taglink|footprintX}} size. Prior to 101.0 if this tag is not present, then any Script.AttachUnit and Script.DropUnit call in the animation script will be ignored (See [[Animation-LuaCallouts#Other]]), in successive versions all units can use [[Lua_SyncedCtrl#Unit_Control|Spring.UnitAttach]] et al regardless of this tag.}}

{{tag
|name = transportMass
|type = float
|default = 100000.0
|description = The total cumulative {{taglink|mass}} of passengers the transport can carry.}}

{{tag
|name = minTransportMass
|type = float
|default = 0.0
|description = The minimum {{taglink|mass}} passenger the transport can carry.}}

{{tag
|name = loadingRadius
|type = float
|default = 220.0
|description = How far away in [[elmo]]s can the transporter pick up and drop units?}}

{{tag
|name = unloadSpread
|type = float
|default = 5.0
|description = How spread out the passengers are when unloaded. Is multiplied by the passengers radius.}}

{{tag
|name = isFirePlatform
|type = bool
|default = false
|description = Can transported units still aim and shoot while loaded by this transport?}}

{{tag
|name = holdSteady
|type = bool
|default = false
|description = If <code>true</code> - passengers are slaved to orientation of transporter attachment piece, if <code>false</code> - passengers are slaved to orientation of transporter body.}}

{{tag
|name = releaseHeld
|type = bool
|default = false
|description = Does the transporter unload it's passengers when it dies?}}

{{tag
|name = cantBeTransported
|type = bool
|default = false for mobile units, true for structures
|description = Controls if a unit is transportable at all or not. If <code>false</code> it is overridden by [[Modrules.lua]] <code>transportability</code> subtable tags.}}

{{tag
|name = transportByEnemy
|type = bool
|default = true
|description = Controls if a unit can be transported by an enemy transport. i.e. can it be kidnapped.}}

{{tag
|name = transportUnloadMethod
|type = int
|default = 0
|description = For air transports. Can be <code>0</code> - Land to unload individually, <code>1</code> - Flyover drop (i.e. Parachute), or <code>2</code> - Land and flood unload all passengers. Can be used on ground transports with mixed results.}}

{{tag
|name = fallSpeed
|type = float
|default = 0.2
|description = For air transports with {{taglink|transportUnloadMethod|1}}. The speed in [[elmo]]s per second which units will fall at when released from the transport.}}

{{tag
|name = unitFallSpeed
|type = float
|default = 0.0
|description = Allows you to override {{taglink|fallSpeed}} for an individual passenger.}}

===Categories===
{{tag
|name = category
|type = string
|default = ""
|description = The category tag is a string of separate words, each representing a category of units. There is a maximum of 32 categories. The primary purpose of categories is weapon targeting (See [[#weapons]]).}}

{{tag
|name = noChaseCategory
|type = string
|default = ""
|description = The unit will still target enemies with a matching {{taglink|category}}, but will not chase after it if it moves out of weapon range.}}

===Decals===
{{tag
|name = leaveTracks
|type = bool
|default = false
|description = Does the unit leave a track mark decal behind it when it moves? For mobile units.}}

{{tag
|name = trackType
|type = string
|default = "stdTank"
|description = The filename of the image, without extension, assumed to be in <code>Bitmaps/Tracks/</code>, to be used as the track decal. The red channel of the image controls the brightness and the green channel the alpha (how visible it is) of the track. Blue channel is unused.}}

{{tag
|name = trackWidth
|type = float
|default = 32.0
|description = The width of the track decal left on the ground, in [[elmo]]s.}}

{{tag
|name = trackOffset
|type = float
|default = 0.0
|description = How far back in [[elmo]]s the track should be drawn from the centre of the unit.}}

{{tag
|name = trackStrength
|type = float
|default = 32.0
|description = How visible or 'deep' the track mark should be. Also used to determine how long the decal should last.}}

{{tag
|name = trackStretch
|type = float
|default = 1.0
|description = How much the track is stretched in the forward direction compared to the sides (i.e. used to change aspect ratio).}}

{{tag
|name = useBuildingGroundDecal
|type = bool
|default = false
|description = For structures, do they display a ground decal on the terrain under their model?}}

{{tag
|name = buildingGroundDecalType
|type = string
|default = ""
|description = The filename of the image to be used as ground decal. Assumed to be in <code>Unittextures/</code>.}}

{{tag
|name = buildingGroundDecalSizeX
|type = int
|default = 4
|description = How wide the decal is left to right, in footprint units.}}

{{tag
|name = buildingGroundDecalSizeY
|type = int
|default = 4
|description = How wide the decal is top to bottom, in footprint units.}}

{{tag
|name = buildingGroundDecalDecaySpeed
|type = float
|default = 0.1
|description = A measure of how quickly the decal should fade out if the structure dies. Essentially this value is multiplied by the time since death and subtracted from the original alpha until the decal is fully transparent.}}

===Collision Volumes===
For a deeper explanation of these tags, see [[Gamedev:CollisionVolumes]]. Note that all collision checks first do a pre-check with the unit ''radius'' before doing the colvol checks. Ergo the unit ''radius'' must be larger or equal to the colvol!

{{tag
|name = usePieceCollisionVolumes
|type = bool
|default = false
|lua = collisionVolume.defaultToPieceTree
|description = When turned on the model and UnitDef collision volumes are ignored and Spring generates a bounding box volume for each piece of the unit model. These volumes can be manipulated or replaced by [[Lua_SyncedCtrl#Unit_Control | Spring.SetUnitPieceCollisionVolumeData]]. Increases the performance cost of collision calculations.}}

{{tag
|name = useFootPrintCollisionVolume
|type = bool
|default = false
|special = {{new|92.0}}
|lua = .collisionVolume.defaultToFootprint
|description = Replaces any defined collision volume with a box with dimensions equal to the object's footprint (this also overrides any custom scaling and/or offsets).
}}

The following three tags can instead be replaced with a [[#collisionVolume]] subtable:

{{tag
|name = collisionVolumeType
|type = string
|default = "s"
|lua = collisionVolume.type
|description = What shape should the unit's collision volume be? Can be {{value|"box"}}, {{value|"sphere}} or a cylinder aligned to an axis; {{value|"cylX"}}, {{value|"cylY"}}, {{value|"cylZ"}}.}}

{{tag
|name = collisionVolumeScales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = collisionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the collision volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = collisionVolumeOffsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = collisionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the hit volume centre in each axis.}}

The following tags have now been removed from the engine:

{{tag
|name = collisionVolumeTest
|type = int
|default = 0
|special = Removed in 90.0 (Now always continuous)
|description = The type of test used to detect collisions. Can be <code>0</code> (discrete) or <code>1</code> (continuous). Use the latter for catching high speed projectiles which may otherwise 'skip through' small collision volumes, but beware of the increased performance cost.}}

{{tag
|name = modelCenterOffset
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = Removed in 89.0 (Now set via lua)
|description = How far from the model's defined centre should the centre of the unit be?}}

===Selection Volumes===
Introduced in 104.0, units may now have custom selection volumes in exactly the same way as collision volumes were already defined.

{{tag
|name = usePieceSelectionVolumes
|type = bool
|default = false
|special = {{new|104.0}}
|lua = .selectionVolume.defaultToPieceTree
|description = When turned on the model and UnitDef selection volumes are ignored and Spring generates a bounding box volume for each piece of the unit model (the same volumes are used for collision and selection). These volumes can be manipulated or replaced by [[Lua_SyncedCtrl#Unit_Control | Spring.SetUnitPieceColisionVolumeData]]. Increases the performance cost of selection calculations.}}

{{tag
|name = useFootPrintSelectionVolume
|type = bool
|default = false
|special = {{new|104.0}}
|lua = .selectionVolume.defaultToFootprint
|description = Replaces any defined selection volume with a box with dimensions equal to the object's footprint (this also overrides any custom scaling and/or offsets).
}}

The following three tags can instead be replaced with a [[#selectionVolume]] subtable:

{{tag
|name = selectionVolumeType
|type = string
|default = "s"
|special = {{new|104.0}}
|lua = collisionVolume.type
|description = What shape should the unit's selection volume be? Can be {{value|"box"}}, {{value|"sphere}} or a cylinder aligned to an axis; {{value|"cylX"}}, {{value|"cylY"}}, {{value|"cylZ"}}.}}

{{tag
|name = selectionVolumeScales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = {{new|104.0}}
|lua = .selectionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the selection volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = selectionVolumeOffsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = {{new|104.0}}
|lua = .selectionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the selection volume centre in each axis.}}

===Attack Behaviours===
{{tag
|name = highTrajectory
|type = int
|default = 0
|lua = highTrajectoryType
|description = Can the unit fire it's (ballistic) weapons in a high trajectory arc? Can be <code>0</code> - Low trajectory only, <code>1</code> - High trajectory only, or <code>2</code> - Toggle button.}}

{{tag
|name = kamikaze
|type = bool
|default = false
|lua = canKamikaze
|description = Does the unit attack its target by blowing itself up?}}

{{tag
|name = kamikazeDistance
|type = float
|default = 0.0
|lua = kamikazeDist
|description = How close to the target, in [[elmo]]s, the unit must get before detonating. Measured in 3D, not 2D.}}

{{tag
|name = kamikazeUseLOS
|type = bool
|default = false
|description = Does the target unit have to be in LOS when detonating or only within {{taglink|kamikazeDistance}}.}}

{{tag
|name = strafeToAttack
|type = bool
|default = false
|description = Should the unit move sideways when it can't shoot?}}

===Other===
{{tag
|name = decoyFor
|type = string
|default = ""
|description = The UnitDef name (not human {{taglink|name}}) which this unit is a decoy for.}}

{{tag
|name = selfDestructCountdown
|type = int
|default = 5
|lua = selfDCountdown
|description = The length in seconds taken between issuing self destruct order and the unit exploding.}}

{{tag
|name = damageModifier
|type = float
|default = 1.0
|lua = armoredMultiple
|description = The multiplier applied to weapon damage when the units ARMORED status (See [[Lua_ConstCOB]]) is turned on.}}

{{tag
|name = isTargetingUpgrade
|type = bool
|default = false
|lua = targFac
|description = Does the unit upgrade the targeting so that units shoot accurately at enemy units which are in radar but not in LOS.}}

{{tag
|name = isFeature
|type = bool
|default = false
|description = Does the unit immediately die into it's {{taglink|corpse}} feature when built? Used mainly for making walls.}}

{{tag
|name = hideDamage
|type = bool
|default = false
|description = Should the units current health be invisible to enemy players?}}

{{tag
|name = showPlayerName
|type = bool
|default = false
|description = Should the unit display it's controlling player as its name instead of {{taglink|name}}. Generally used for commander or hero units.}}

{{tag
|name = showNanoFrame
|type = bool
|default = true
|description = Does the unit show an OTA-style nanoframe whilst being constructed?}}

{{tag
|name = unitRestricted
|type = int
|default = MAX_UNITS
|lua = maxThisUnit
|description = How many of this unit type may a player control at once? Defaults to being the maximum amount of units controllable. Is overridden by lobby unit restrictions.}}

{{tag
|name = power
|type = float
|default = {{taglink|buildCostMetal}} + ({{taglink|buildCostEnergy}} / 60.0)
|description = The relative power of the unit. Used in weapon targeting priority and experience gain calculations.}}

==Sub Tables==

===collisionVolume===
The <code>collisionVolume</code> subtable of a UnitDef replaces the older individual {{taglink|collisionVolumeType}}, {{taglink|collisionVolumeScales}} and {{taglink|collisionVolumeOffsets}} tags.

{{tag
|name = type
|type = string
|default = "s"
|lua = .collisionVolume.type
|description = What shape should the unit's collision volume be? Can be {{value|"box"}}, {{value|"sphere"}} or a {{value|"cylinder"}}.}}

{{tag
|name = axis
|type = string
|default = "z"
|description = Which axis does the unit's collision volume lie along? Can be {{value|"x"}}, {{value|"y"}} or {{value|"z"}}.}}

{{tag
|name = scales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .collisionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the collision volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = offsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .collisionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the hit volume centre in each axis.}}

===selectionVolume===
The <code>selectionVolume</code> subtable of a UnitDef can replace the individual {{taglink|selectionVolumeType}}, {{taglink|selectionVolumeScales}} and {{taglink|selectionVolumeOffsets}} tags.

{{tag
|name = type
|type = string
|default = "s"
|lua = .selectionVolume.type
|description = What shape should the unit's selection volume be? Can be {{value|"box"}}, {{value|"sphere"}} or a {{value|"cylinder"}}.}}

{{tag
|name = axis
|type = string
|default = "z"
|description = Which axis does the unit's selection volume lie along? Can be {{value|"x"}}, {{value|"y"}} or {{value|"z"}}.}}

{{tag
|name = scales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .selectionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the selection volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = offsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .selectionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the selection volume centre in each axis.}}

===weapons===
The <code>weapons</code> subtable of a UnitDef tells Spring which weapons the unit has. It is a simple array (number indexed table) of <code>weaponName</code>s (not the human readable <code>name</code>!).

The following additional tags are associated with this subtable:

{{tag
|name = name
|type = string
|default = ""
|description = The <code>weaponName</code> of the weapon (See [[Gamedev:WeaponDefs]]). If using the [[weapondefs_post.lua]] provided by [[springcontent.sdz]], you may include the WeaponDef tables within the UnitDef as the <code>weaponDefs</code> subtable, and refer to them with <code>def</code> rather than <code>name</code>. This can be a useful way to organise definitions if units do not generally share weapons.}}

{{tag
|name = badTargetCategory
|type = string
|default = ""
|description = A string of unit {{taglink|category}} entries which this weapon prefers to avoid targeting. i.e. given two units which ''can'' be targeted, any unit whose {{taglink|category}} matches any entry in this tag, will be targeted last. (See [[#Categories]])}}

{{tag
|name = onlyTargetCategory
|type = string
|default = ""
|description = A string of unit {{taglink|category}} entries which this weapon can target. i.e. any unit whose {{taglink|category}} does not match any entry in this tag, cannot be targeted by this weapon. (See [[#Categories]])}}

{{tag
|name = slaveTo
|type = int
|default = 0
|description = The number of the weapon which this weapon is slaved to. A slaved weapon can only target what it's master is targeting. Weapon numbers start at <code>1</code> and correspond to the index of the weapon within the subtable.}}

{{tag
|name = mainDir
|type = float[3]
|default = {0.0, 0.0, 1.0} i.e. forwards
|description = A vector representing the firing direction of this weapon if it has a limited firing arc. Used in conjunction with {{taglink|maxAngleDif}} (See [[Gamedev:WeaponMainDir]]).}}

{{tag
|name = maxAngleDif
|type = float
|default = 360.0
|description = How wide this weapons limited firing arc is in degrees. Symmetrical about {{taglink|mainDir}} i.e. <code>180.0</code> is 90 degree freedom either way (See [[Gamedev:WeaponMainDir]]).}}

{{tag
|name = fuelUsage
|type = float
|default = 0.0
|description = How much fuel in seconds is deducted from the units initial {{taglink|maxFuel}} when this weapon fires.}}

===buildOptions===
The <code>buildOptions</code> subtable of a UnitDef tells Spring which other units the unit can build (in the case of a builder) or produce (in the case of a factory).
It is a simple array (number indexed table) of <code>unitName</code>s (not the human readable {{taglink|name}}!).

There are no additional tags specific to this subtable.

===SFXTypes===
The <code>SFXTypes</code> subtable of a UnitDef tells Spring which [[CEG]] effects are associated with the unit. It consists of two further subtables, with no additional tags specific to them.

====explosionGenerators====

The <code>explosionGenerators</code> subtable of <code>SFXTypes</code> tells Spring which [[CEG]]s the unit's script can call, via the <code>EmitSFX()</code> callout (See [[Animation-LuaCallouts#Effects]]). It is a simple array (number indexed table) of CEG names, prefaced by the string <code>"custom:"</code>.

====pieceExplosionGenerators====
{{new|83.0}}

The <code>pieceExplosionGenerators</code> subtable of <code>SFXTypes</code> tells Spring which [[CEG]]s the unit's script can pick at random to attach to a flying unit piece, created from the <code>Explode()</code> callout (See [[Animation-LuaCallouts#Effects]]). It is a simple array (number indexed table) of CEG names, with no prefix.

Forum thread (with examples): {{forumlink|topic=27554|title=pieceExplosionGenerators}}

===sounds===

The <code>sounds</code> subtable of a UnitDef tells Spring which sound files to play when the unit triggers various events.

Files are assumed to be in the <code>Sounds/</code> directory; accepted formats are .wav and .ogg, the former being assumed if no extension is given.

Sounds can be defined in one of three ways:

# Each event can be used as though it were a <code>string</code> tag referring to the filename.
# Each event can be the name of a subtable, which is a simple array containing the filenames. One sound is picked at random from the list each time the event occurs.
# Each event can be the name of a subtable, which is a simple array containing further tables, which contain the following tags:
{{tag
|name = file
|type = string
|default = ""
|description = The filename of the sound to play.}}

{{tag
|name = volume
|type = float
|default = 1.0
|description = The default volume of the sound.}}

Spring checks any referenced sound filename to see if a SoundItem has been created, which allows greater control over how it is played (See [[Sounds.lua]]).

====sounds Example====

For clarification, here is an example of all three methods:

<code><pre>sounds = {
-- Method 1
ok = 'oksound', -- .wav appended
-- Method 2
arrived = {
'arrived1.wav',
'arrived2.wav',
},
-- Method 3
select = {
{ file = 'selsound1.ogg', volume = 2.0 },
{ file = 'selsound2.ogg', volume = 2.5 },
},
}</pre></code>

====sounds Events====

The events called by the engine are as follows:

{{ItemType
|name = ok
|description = Unit is issued a command.
}}

{{ItemType
|name = select
|description = Unit is selected by the player.
}}

{{ItemType
|name = arrived
|description = Unit has arrived at its destination. Mobile ground units only.
}}

{{ItemType
|name = build
|description = Unit begins building. Called for both factories and mobile construction units.
}}

{{ItemType
|name = activate
|description = Unit is activated, i.e. Is turned on. Also called when a mobile ground unit starts moving.
}}

{{ItemType
|name = deactivate
|description = Unit deactivates, i.e. Is turned off.
}}

{{ItemType
|name = cant
|description = Unit cannot carry out this order. Loaded but not currently called by the engine.
}}

{{ItemType
|name = underattack
|description = Unit gets attacked. Loaded but not currently called by the engine.
}}

===customParams===
The <code>customParams</code> subtable of a UnitDef allows the game designer to give their units custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
MC:L implements OO with inheritance (base classes in [http://sourceforge.net/p/mwspring/code/HEAD/tree/Gamedata/unitdefs_pre.lua#l36 unitdefs_pre.lua])

{{ExampleRepoLinks
|path = units/
|entity = UnitDefs
}}

[[Category: Game Dev]]

Gamedev:UnitDefs

2021-07-09T08:09:07Z

Picassoct: /* Advanced Air Tags */

[[Gamedev:Main|Development]] < [[Gamedev:Main]] < {{FULLPAGENAME}}

==Location==
UnitDef files are .lua files stored in the <code>Units/</code> directory of a Spring Game.

==Purpose==
UnitDef files have one purpose; to define the properties of units. They are the main description file for what attributes your unit should have and how it should behave.

==Source==
The engine source code which loads the tags from these files is viewable here:

* {{sourcelink|file=rts/Sim/Units/UnitDef.cpp}}

The engine source which reads the [[#sounds]] subtable can be found here:

* {{sourcelink|file=rts/Sim/Units/UnitDefHandler.cpp}}

==Data Types==
{{DataTypes}}

==Details==
There follows a comprehensive (certain deprecated tags are not present) list of the tags available, their data type, default value and a brief description of what they do. Bear in mind that the source code linked above is the ultimate reference when dealing with these tags.

In lua tables keys (i.e. the tags) should be lower case, here they are represented in camelCase for readability. In your files you may use the <code>lowerkeys</code> function on your final table to ensure the keys are properly cased.

It is usual to name the returned UnitDef table the internal <code>unitName</code> desired for the unit.

===General===
{{tag
|name = name
|type = string
|default = ""
|lua = humanName
|description = This is simply the name of the unit as it appears to the player.}}

{{tag
|name = description
|type = string
|default = name
|lua = tooltip
|description = This is the tooltip description of the unit seen by the player. It defaults to the {{taglink|name}} of the unit.}}

{{tag
|name = buildPic
|type = string
|default = ""
|lua = buildPicName
|description = The filename of the image to be used as the build picture, assumes <code>Unitpics/</code> directory (see [[Gamedev:Buildpics]]).}}

{{tag
|name = objectName
|type = string
|default = ""
|lua = modelname
|description = The filename of the 3D model file for this unit, assumes <code>Objects3D/</code> directory.}}

{{tag
|name = script
|type = string
|default = unitName + ".cob"
|lua = scriptName
|description = The filename of the animation script file for this unit, assumes <code>Scripts/</code> directory. Default assumes .cob file but [[Animation-LuaScripting | LUS]] should be preferred.}}

{{tag
|name = maxDamage
|type = float
|default = 0.0
|lua = health
|description = The base 'hitpoints' the unit will have.}}

{{tag
|name = autoHeal
|type = float
|default = 0.0
|description = How much health the unit will regain every second.}}

{{tag
|name = idleAutoHeal
|type = float
|default = 10.0
|description = How much health the unit will regain every second whilst it is idle.}}

{{tag
|name = idleTime
|type = int
|default = 600
|description = The time in [[frames]] taken until a unit is considered to be idle.}}

{{tag
|name = buildCostMetal
|type = float
|default = 1.0
|lua = metalCost
|description = The amount of metal resource the unit costs to build. Cannot be below <code>1.0</code>.}}

{{tag
|name = buildCostEnergy
|type = float
|default = 0.0
|lua = energyCost
|description = The amount of energy resource the unit costs to build.}}

{{tag
|name = buildTime
|type = float
|default = 0.0
|description = The time taken to build the unit, in conjunction with the {{taglink|workerTime}} of the constructor. In [[Gamedev:UnitsOfMeasurement#Time|Resource Frames]], <code>Time to build = (buildTime / workerTime)</code>. Defaults to <code>0.0</code> but cannot actually be below <code>1.0</code>.}}

{{tag
|name = mass
|type = float
|default = buildCostMetal
|description = The mass of the unit, used in weapon impulse calculations. Cannot be less than <code>1.0</code>.}}

{{tag
|name = reclaimable
|type = bool
|default = true
|description = Can the unit be reclaimed by a builder?}}

{{tag
|name = capturable
|type = bool
|default = true
|description = Can a unit be stolen by a builder using the capture command?}}

{{tag
|name = repairable
|type = bool
|default = true
|description = Can the unit be repaired by a builder?}}

{{tag
|name = maxRepairSpeed
|type = float
|default = 1e20
|description = The maximum cumulative speed at which this unit type can repair a single target.}}

{{tag
|name = iconType
|type = string
|default = "default"
|description = The name of the radar icon type this unit should use (see [[Icontypes.lua]]).}}

{{tag
|name = corpse
|type = string
|default = ""
|lua = wreckName
|description = The name of the feature this unit should leave behind as a wreck when it dies (see [[Gamedev:FeatureDefs]]).}}

{{tag
|name = explodeAs
|type = string
|default = ""
|description = The name of the weapon this unit should explode as when it is killed (see [[Gamedev:WeaponDefs]]).}}

{{tag
|name = selfDestructAs
|type = string
|default = ""
|description = The name of the weapon this unit should explode as when it self destructs (see [[Gamedev:WeaponDefs]]). Also used as the {{taglink|kamikaze}} weapon.}}

===Resources===
{{tag
|name = harvestStorage
|type = float
|default = 0.0
|special = {{new|97.0}}
|description = How much of the metal resource a unit can store when used as an engine-assisted resource 'harvester'. See also [[Lua:Callins#API:UnitHarvestStorageFull|UnitHarvestStorageFull callin]] and [[Lua_SyncedRead#Unit_Informations|Spring.GetUnitHarvestStorage]] and [[Lua_SyncedCtrl#Unit_Resourcing|Spring.SetUnitHarvestStorage]] callouts.}}

{{tag
|name = metalStorage
|type = float
|default = 0.0
|description = The amount of the metal resource storage the unit contributes.}}

{{tag
|name = energyStorage
|type = float
|default = 0.0
|description = The amount of the energy resource storage the unit contributes.}}

{{tag
|name = extractsMetal
|type = float
|default = 0.0
|description = The amount of the metal resource the unit extracts from the ground. The amount extracted depends on the metal map defined in the map itself. Works only for structures.}}

{{tag
|name = windGenerator
|type = float
|default = 0.0
|description = The amount of the energy resource the unit generates which is dependant on the map wind. Works only for structures.}}

{{tag
|name = tidalGenerator
|type = float
|default = 0.0
|description = The amount of the energy resource the unit generates which is dependant on the maps tidal power. Clearly, this only works on water structures.}}

{{tag
|name = metalUse
|type = float
|default = 0.0
|lua = metalUpkeep
|description = The amount of the metal resource the unit consumes per game 'tick' when activated.}}

{{tag
|name = energyUse
|type = float
|default = 0.0
|lua = energyUpkeep
|description = The amount of the energy resource the unit consumes per game 'tick' when activated.}}

{{tag
|name = metalMake
|type = float
|default = 0.0
|description = The amount of the metal resource the unit generates unconditionally per game 'tick'.}}

{{tag
|name = energyMake
|type = float
|default = 0.0
|description = The amount of the energy resource the unit generates unconditionally per game 'tick'.}}

{{tag
|name = makesMetal
|type = float
|default = 0.0
|description = The amount of the energy resource the unit turns into the metal resource per game 'tick'.}}

===Sensors===
{{tag
|name = onOffable
|type = bool
|default = false
|description = Does the unit have an on/off button? Currently the activation status tied to this button also turns sensors (other than LOS) on and off.}}

{{tag
|name = activateWhenBuilt
|type = bool
|default = false
|description = Should the unit's activation status be on or off when it is created?}}

{{tag
|name = sightDistance
|type = float
|default = 0.0
|lua = losRadius
|description = The radius of the units sight (LOS is circular in Spring).
}}

{{tag
|name = airSightDistance
|type = float
|default = 1.5 * sightDistance
|lua = airLosRadius
|description = How far away the unit can see aircraft (and some FX).}}

{{tag
|name = losEmitHeight
|type = float
|default = 20.0
|lua = losHeight
|special = {{new|83.0}}
|description = How high up the unit is the point used to calculate it's LOS vs. the terrain?}}

{{tag
|name = radarEmitHeight
|type = float
|default = 20.0
|lua = radarHeight
|special = {{new|83.0}}
|description = How high up the unit is the point used to calculate it's radar vs. the terrain?}}

{{tag
|name = radarDistance
|type = int
|default = 0
|lua = radarRadius
|description = The radius of the units radar.}}

{{tag
|name = sonarDistance
|type = int
|default = 0
|lua = sonarRadius
|description = The radius of the units sonar.}}

{{tag
|name = radarDistanceJam
|type = int
|default = 0
|lua = jammerRadius
|description = The radius of the units radar jamming.}}

{{tag
|name = sonarDistanceJam
|type = int
|default = 0
|lua = sonarJamRadius
|description = The radius of the units sonar jamming.}}

{{tag
|name = stealth
|type = bool
|default = false
|description = Is the unit undetectable by radar?}}

{{tag
|name = sonarStealth
|type = bool
|default = false
|description = Is the unit undetectable by sonar?}}

{{tag
|name = seismicDistance
|type = int
|default = 0
|lua = seismicRadius
|description = The radius of the unit's seismic (movement) sensor.}}

{{tag
|name = seismicSignature
|type = float
|default = 0 for units with {{taglink|floater}}, {{taglink|canHover}} or {{taglink|canFly}}, otherwise sqrt(mass / 100.0)
|description = How fast the seismic ring expands in [[elmo]]s per frame. Each ping always lasts 15 [[frames]], so this also determines the maximum radius of the seismic ring.}}

====Cloaking====
For units with {{taglink|canCloak|true}}:
{{tag
|name = cloakCost
|type = float
|default = 0.0
|description = The energy cost per tick to cloak the unit while it is stationary.}}

{{tag
|name = cloakCostMoving
|type = float
|default = cloakCost
|description = The energy cost per tick to cloak the unit while it is moving.}}

{{tag
|name = initCloaked
|type = bool
|default = false
|lua = startCloaked
|description = Is the unit cloaked as soon as it is created?}}

{{tag
|name = minCloakDistance
|type = float
|default = 0.0
|description = The minimum distance (radius) which the unit must be from any enemy units to remain cloaked.}}

{{tag
|name = decloakSpherical
|type = bool
|default = true
|description = Does {{taglink|minCloakDistance}} apply in 3D or only 2D? i.e. can aircraft flying above the unit decloak it?}}

{{tag
|name = decloakOnFire
|type = bool
|default = true
|description = Does the unit decloak when it fires a weapon?}}

{{tag
|name = cloakTimeout
|type = int
|default = 128
|description = The minimum time, in [[frames]], between a decloak and subsequent re-cloak.}}

===Commands===
{{tag
|name = canMove
|type = bool
|default = false
|description = Can the unit be issued Move orders?
}}

{{tag
|name = canAttack
|type = bool
|default = true
|description = Can the unit be issued Attack orders?
}}

{{tag
|name = canFight
|type = bool
|default = true
|description = Can the unit be issued Fight orders?
}}

{{tag
|name = canPatrol
|type = bool
|default = true
|description = Can the unit be issued Patrol orders?
}}

{{tag
|name = canGuard
|type = bool
|default = true
|description = Can the unit be issued Guard orders?
}}

{{tag
| name = canCloak
| type = bool
| default = false
| description =
Can the unit be issued Cloak orders?
}}

{{tag
|name = canRepeat
|type = bool
|default = true
|description = Can the unit be issued Repeat orders?
}}

{{tag
|name = canSelfDestruct
|type = bool
|default = true
|lua = canSelfD
|description = Can the unit be issued a self destruct order?
}}

{{tag
|name = moveState
|type = int
|default = -1 for mobile units, 1 for structures
|description = The initial movement state for the unit. Can be {{value|-1}} - Inherits from factory, {{value|0}} - Hold Position, {{value|1}} - Manoeuvre or {{value|2}} - Roam.
}}

{{tag
|name = fireState
|type = int
|default = -1 for units with {{taglink|noAutoFire|false}}, 2 otherwise
|description = The initial firing state for the unit. Can be {{value|-1}} - Inherits from factory, {{value|0}} - Hold Fire, {{value|1}} - Return Fire or {{value|2}} - Fire At Will. Since 104.0 there is an additional value {{value|3}} - Fire At Neutral.
}}

{{tag
|name = noAutoFire
|type = bool
|default = false
|lua = canFireControl
|description = Controls whether or not the unit has a fire state button.
}}

{{tag
|name = canManualFire
|type = bool
|default = false
|description = description = Can the unit be issued ManualFire commands? A ManualFire command will fire any weapons with the {{xtaglink|Gamedev:WeaponDefs|commandfire}} tag.
}}

====Builder Commands====
{{tag
|name = canRestore
|type = bool
|default = builder && {{taglink|terraformSpeed}} > 0
|description = Can the unit be issued restore terrain commands? For builders only.
}}

{{tag
|name = canRepair
|type = bool
|default = builder && {{taglink|repairSpeed}} > 0
|description = Can the unit be issued repair commands? For builders only.
}}

{{tag
|name = canReclaim
|type = bool
|default = builder && {{taglink|reclaimSpeed}} > 0
|description = Can the unit be issued reclaim commands? For builders only.
}}

{{tag
|name = canResurrect
|type = bool
|default = builder && {{taglink|resurrectSpeed}} > 0
|description = Can the unit be issued resurrection commands? For builders only.
}}

{{tag
|name = canCapture
|type = bool
|default = builder && {{taglink|captureSpeed}} > 0
|description = Can the unit be issued capture commands? For builders only.
}}

===Builder===
{{tag
|name = builder
|type = bool
|default = false
|lua = isBuilder
|description = Is the unit a builder?}}

{{tag
|name = buildDistance
|type = float
|default = 128.0
|description = How far away from itself the unit can build, measured to the centre of the unit being built. The minimum value is <code>38.0</code>.}}

{{tag
|name = buildRange3D
|type = bool
|default = false
|description = Does the builders {{taglink|buildDistance}} apply in all 3 dimensions or only 2?}}

{{tag
|name = workerTime
|type = float
|default = 0.0
|lua = buildSpeed
|description = How fast the builder builds, used in conjunction with the {{taglink|buildTime}} of the unit being built. Effectively, <code>Time to build = buildTime / workerTime</code>. If this value is <= <code>0.0</code> then {{taglink|builder}} is set to false.}}

{{tag
|name = repairSpeed
|type = float
|default = workerTime
|description = How fast the builder can repair other units.}}

{{tag
|name = reclaimSpeed
|type = float
|default = workerTime
|description = How fast the builder can reclaim other units and features.}}

{{tag
|name = resurrectSpeed
|type = float
|default = workerTime
|description = How fast the builder can resurrect corpse features back into living units.}}

{{tag
|name = captureSpeed
|type = float
|default = workerTime
|description = How fast the builder can capture other units.}}

{{tag
|name = terraformSpeed
|type = float
|default = workerTime
|description = How fast the builder levels and restores terrain.}}

{{tag
|name = canAssist
|type = bool
|default = builder
|description = Can the builder assist other constructions?}}

{{tag
|name = canBeAssisted
|type = bool
|default = true
|description = Can the builder be assisted by other builders?}}

{{tag
|name = canSelfRepair
|type = bool
|default = false
|description = Can the builder repair itself?}}

{{tag
|name = showNanoSpray
|type = bool
|default = true
|description = Does the builder emit OTA-style nanospray whilst constructing?}}

{{tag
|name = nanoColor
|type = float[3]
|default = {0.2, 0.7, 0.2} aka green
|description = The RGB colour of a builders' emitted nano particles if {{taglink|showNanoSpray|true}}. Also controls the RBG colour of a unit's own nanoframe if {{taglink|showNanoFrame|true}}.}}

{{tag
|name = fullHealthFactory
|type = bool
|defaul[[elmo]]s
|description = If <code>true</code>, units are repaired before they are allowed to leave the factory i.e. units from this factory will be healed back to 100% health if they are damaged during construction.}}

{{tag
|name = isAirbase
|type = bool
|default = false
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = Is this unit an airbase? Aircraft may land and repair on units which are airbases.}}

===Movement & Placement===
{{tag
|name = footprintX
|type = int
|default = 1
|description =
How wide the unit is in footprint units, left to right. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Movedefs.lua|footprintX}} of its {{taglink|movementClass}}. Also used for obstacle avoidance.
}}

{{tag
|name = footprintZ
|type = int
|default = 1
|description =
How wide the unit is in footprint units, top to bottom. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Movedefs.lua|footprintZ}} of its {{taglink|movementClass}}. Also used for obstacle avoidance.
}}

{{tag
|name = yardmap
|type = string
|default = ""
|description =
Used to determine a structure from a mobile unit. A string of characters which defines in detail each 'footprint square' of the structure. Each footprint square may be:
:: <code>y</code> - 'Yard' - Always open, unblocking,
:: <code>c</code> - 'Construction' - Open and unblocking only while constructing (for factories, controlled via <code>COB.YARD_OPEN</code> see [[Animation-LuaCallouts#Other]]),
:: <code>i</code> - 'Inversed Construction' - Closed and blocking only while constructing (for factories, controlled via <code>COB.YARD_OPEN</code> see [[Animation-LuaCallouts#Other]]) ({{new|89.0}}),
:: <code>g</code> - 'Geothermal' - Flags that the unit must be placed over a {{xtaglink|Gamedev:FeatureDefs|geoThermal}} feature, does not actually count as a square,
:: <code>h</code> - 'High Resolution' - Indicates that the yardmap will use double resolution with four times as many characters. Must be the '''first''' character, and does not count as a square itself ({{new|93.0}}),
::<code>o</code> - 'Obstacle' - Always closed, blocking, all other chars are treated the same way.
: Tip: 'Draw' out the yardmap over multiple lines. As of 89.0 all whitespace characters are ignored, including newlines.
}}

{{tag
|name = buildingMask
|type = int
|default = 1
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of ground that this structure can be built on. Each digit of binary that is set to one means that a ground square with the corresponding digit set via [[Lua_SyncedCtrl#Ground|Spring.SetSquareBuildingMask]] can be built on.
}}

{{tag
|name = levelGround
|type = bool
|default = false
|description = For structures. Does the constructor have to level the ground underneath the build area before beginning to build the structure?
}}

{{tag
|name = movementClass
|type = string
|default = ""
|lua = moveDef.name
|description = The name of the movement type a mobile, non aircraft, unit should use. See [[Movedefs.lua]].
}}

{{tag
|name = canHover
|type = bool
|default = false
|special = Removed in 95.0
|description = Is the unit a hovercraft? Hovercraft can cross water of any depth without a speed penalty. Hover's must also have <code>HOVER</code> within the name of their {{taglink|movementClass}} (see [[Movedefs.lua]]).
}}

{{tag
|name = floater
|type = bool
|default = false if a {{taglink|moveClass}} is defined, if not true if {{taglink|waterline|true}}, false otherwise
|description = When a mobile unit is crossing water, or a structure is placed on water, does it float on top of the water or crawl / lay on the sea bed?
}}

{{tag
|name = upright
|type = bool
|default = false
|description = Does the unit follow the terrain or always remain upright? Generally used for walkers.
}}

{{tag
|name = maxSlope
|type = float
|default = 0.0
|lua = maxHeightDif
|description = The maximum slope a building can be placed on. Mobile unit's use the {{xtaglink|Movedefs.lua|maxSlope}} set in their {{taglink|movementClass}}. The value is in degrees and is clamped between <code>0.0</code> and <code>89.0</code>. This value is converted to a "maximum allowed height difference" (call it M), which involves a hard-coded constant. When a building gets placed, the height of each of its footprint squares is compared to a reference height (calculated for the build position). If the difference exceeds M for any square, that build position is rejected. The value readable from lua has been changed from that in the unitdef and reflects the internal engine value.
}}

{{tag
|name = minWaterDepth
|type = float
|default = -10e6
|description = The minimum depth of water a building can be placed on. Mobile unit's use the {{xtaglink|Movedefs.lua|minWaterDepth}} set in their {{taglink|movementClass}}.
}}

{{tag
|name = maxWaterDepth
|type = float
|default = 10e6
|description = The maximum depth of water a building can be placed on. Mobile unit's use the {{xtaglink|Movedefs.lua|maxWaterDepth}} set in their {{taglink|movementClass}}.
}}

{{tag
|name = waterline
|type = float
|default = 0.0
|description = How low in the water does a ship sit? Higher values means the ship is lower in the water.
}}

{{tag
|name = minCollisionSpeed
|type = float
|default = 1.0
|description = The minimum net impact speed that will cause a unit to be damaged by collisions with another unit.
}}

{{tag
|name = pushResistant
|type = bool
|default = false
|description = Can the unit be pushed around by other units? Turning it on doesn't remove all pushing but is a marked improvement.
}}

{{tag
|name = maxVelocity
|type = float
|default = 0.0
|lua = speed
|description = The maximum speed attainable by the unit in [[elmo]]s per frame. If the value is -ve, the absolute value is used.
}}

{{tag
|name = maxReverseVelocity
|type = float
|default = 0.0
|lua = rSpeed
|special = {{new|99.0}}
|description = The maximum speed attainable by the unit in reverse in [[elmo]]s per frame. If the value is -ve, the absolute value is used.
}}

{{tag
|name = acceleration
|type = float
|default = 0.5
|lua = maxAcc
|description = The acceleration of the unit, in [[elmo]]s per frame2. If the value is -ve, the absolute value is used.
}}

{{tag
|name = brakeRate
|type = float
|default = acceleration
|lua = maxDec
|description = The deceleration of the unit, in [[elmo]]s per frame2. If the value is -ve, the absolute value is used. For units with {{taglink|canFly|true}} this is multiplied by <code>0.1</code>. Prior to 95.0 this was scaled by 0.1 for aircraft and the default was 3x acceleration.
}}

{{tag
|name = myGravity
|type = float
|default = 0.4
|description = As Spring aircraft are slower than real aircraft this tag allows to lower gravity to compensate. Multiplies against map gravity for aircraft, replaces map gravity for ground vehicles if non-zero.
}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = How fast the unit can turn. <code>degrees per seconds = 0.16 * turnRate</code>.
}}

{{tag
|name = turnInPlace
|type = bool
|default = true
|description = Does the unit turn on the spot (like a person or tank) or must it be moving forwards to turn (like a car).
}}

{{tag
|name = turnInPlaceSpeedLimit
|type = float
|default = A complex formula based on {{taglink|turnRate}} and {{taglink|maxVelocity}}
|description = For units with {{taglink|turnInPlace|false}}, this defines the minimum speed it will slow down to (the speed at which the turn is actually performed can be higher depending on the angular difference and {{taglink|turnRate}}).
}}

{{tag
| name = turnInPlaceAngleLimit
| type = float
| default = 0.0
| special = {{new|86.0}}
| description = For units with {{taglink|turnInPlace|true}}, defines the maximum angle (in degrees) of a turn above which it starts to brake.
}}

{{tag
|name = blocking
|type = bool
|default = true
|description = Does the unit block the movement of other units? (Mines, i.e. non-mobile units with the {{taglink|kamikaze}} tag default to <code>false</code>).
}}

{{tag
|name = crushResistance
|type = float
|default = mass
|special = {{new|85.0}}
|description = How resistant is the unit to being crushed? Any [[Movedefs.lua|'''MoveClass''']] with a {{xtaglink|Movedefs.lua|crushStrength}} greater than this will crush the unit - IFF this has been enabled via [[Lua_SyncedCtrl#Unit_Control|Spring.SetUnitBlocking]] and the collider impulse exceeds that of the colidee.
}}

===Flanking===
{{tag
|name = flankingBonusMode
|type = int
|default = flankingBonus.defaultMode set in [[Modrules.lua]]
|description = The mode of operation of Spring's inbuilt flanking system. Can be <code>0</code> - No flanking bonus. Mode <code>1</code> builds up the ability to move over time, and swings to face attacks, but does not respect the way the unit is facing. Mode <code>2</code> also can swing, but moves with the unit as it turns. Mode <code>3</code> stays with the unit as it turns and otherwise doesn't move, the ideal mode to simulate something such as tank armour.
}}

{{tag
|name = flankingBonusDir
|type = float[3]
|default = {0.0, 0.0, 1.0}
|description = This is the direction vector where the armour is facing; i.e. where the least damage is applied. The default is straight forwards.
}}

{{tag
|name = flankingBonusMax
|type = float
|default = 1.9
|description = The maximum multiplier to the damage dealt, when a unit is hit from the opposite direction to {{taglink|flankingBonusDir}}.
}}

{{tag
|name = flankingBonusMin
|type = float
|default = 0.9
|description = The minimum multiplier to the damage dealt, when a unit is hit from the same direction as {{taglink|flankingBonusDir}}.
}}

{{tag
|name = flankingBonusMobilityAdd
|type = float
|default = 0.01
|description = This defines the ability of {{taglink|flankingBonusDir}} to move over time. Its value is added to the mobility every [[SlowUpdate]]. When the unit is attacked, the build up mobility value is multiplied by a vector facing the attack, which is added to {{taglink|flankingBonusDir}}.
}}

===Aircraft===
{{tag
|name = canFly
|type = bool
|default = false
|description = Can the unit fly, i.e. is it an aircraft?
}}

{{tag
|name = canSubmerge
|type = bool
|default = false
|description = Can the aircraft land underwater?
}}

{{tag
|name = factoryHeadingTakeoff
|type = bool
|default = true
|description = Controls the take-off behaviour of aircraft with {{taglink|hoverAttack|true}}. <code>true</code> means planes start matching their heading right after taking off from the pad, <code>false</code> means they maintain the heading of the pad until reaching {{taglink|cruiseAlt}}.
}}

{{tag
|name = collide
|type = bool
|default = true
|description = Does the unit collide with other aircraft, or can it occupy the same space?
}}

{{tag
|name = hoverAttack
|type = bool
|default = false
|description = Controls whether the aircraft flys and attacks like a fighter/bomber or a helicopter/gunship.
}}

{{tag
|name = airStrafe
|type = bool
|default = true
|description = For aircraft with {{taglink|hoverAttack|true}}, controls if the unit strafes side to side while attacking or remains stationary.
}}

{{tag
|name = cruiseAlt
|type = float
|default = 0.0
|lua = wantedHeight
|description = The altitude in [[elmo]]s which the unit attempts to fly at while cruising.
}}

{{tag
|name = airHoverFactor
|type = float
|default = -1.0
|lua = dlHoverFactor
|description = For aircraft with {{taglink|hoverAttack|true}}, less then <code>0</code> means it can land and >= <code>0</code> indicates how much the unit will move during hovering on the spot.
}}

{{tag
|name = bankingAllowed
|type = bool
|default = true
|description = For aircraft with {{taglink|hoverAttack|true}}, controls whether or not the unit banks when moving turning.
}}

{{tag
|name = useSmoothMesh
|type = bool
|default = true
|description = Does the aircraft follow the real map terrain or the special smoothed out navigation mesh generated by Spring specifically for aircraft?} Can become problematic for construction aircrafts, building in canyons.
}}

{{tag
|name = maxFuel
|type = float
|default = 0.0
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = The maximum flight time in seconds before aircraft must return to an airbase to refuel.
}}

{{tag
|name = refuelTime
|type = float
|default = 5.0
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = The time in seconds required to refuel the aircraft at an airbase.
}}

{{tag
|name = minAirbasePower
|type = float
|default = 0.0
|special = Removed in 101.0 in favour of more flexible lua custom commands
|description = The minimum {{taglink|workerTime}} an airbase must have to repair / refuel this aircraft.
}}

{{tag
|name = canLoopbackAttack
|type = bool
|default = false
|description = Can the aircraft perform an [http://en.wikipedia.org/wiki/Immelmann_turn Immelmann turn]?
}}

====Advanced Air Tags====
The following set of tags are not well understood and using non-default values can lead to undesired flight behaviours. 
{{tag
|name = wingDrag
|type = float
|default = 0.07
|description = The drag caused by the aircraft's wing. Clamped between <code>0.0</code> and <code>1.0</code>.
}}

{{tag
|name = wingAngle
|type = float
|default = 0.08
|description = The angle between the front and the wing plane.
}}

{{tag
|name = frontToSpeed
|type = float
|default = 0.1
|description = How far nose can be unaligned to speed vector before accelleration is applied.
}}

{{tag
|name = speedToFront
|type = float
|default = 0.07
|description = Rate for the nose to align to new (true) direction change. Values above 0.1 may lead to cumulative speedup issues.
}}

{{tag
|name = crashDrag
|type = float
|default = 0.005
|description = The drag used when crashing. Clamped between <code>0.0</code> and <code>1.0</code>.
}}

{{tag
|name = maxBank
|type = float
|default = 0.8
|description = The maximum roll (z-axis rotation) the aircraft can achieve.
}}

{{tag
|name = maxPitch
|type = float
|default = 0.45
|description = The maximum pitch (x-axis rotation) the aircraft tries to keep.
}}

{{tag
|name = turnRadius
|type = float
|default = 500.0
|description = Hint to Spring unit AI about the required turning radius.
}}

{{tag
|name = verticalSpeed
|type = float
|default = 3.0
|description = The speed of takeoff and landing, at least for gunships ({{taglink|hoverAttack|true}}).
}}

{{tag
|name = maxAileron
|type = float
|default = 0.015
|description = The maximum turn speed around the roll (z) axis.
}}

{{tag
|name = maxElevator
|type = float
|default = 0.01
|description = The maximum turn speed around the pitch (x) axis.
}}

{{tag
|name = maxRudder
|type = float
|default = 0.004
|description = The maximum turn speed around the yaw (y) axis.
}}

{{tag
|name = maxAcc
|type = float
|default = 0.065
|description = The maximum acceleration or 'engine power' of the aircraft.
}}

{{tag
|name = attackSafetyDistance
|type = float
|default = 0
| special = Exists only in version >= 99.0
|description = Fighters abort dive toward target if within attackSafetyDistance and try to climb back to normal altitude while still moving toward target. It's disabled by default. Set to half of the minimum weapon range to avoid collisions, enemy fire, AOE damage. If set to greater than the weapon range, the unit will fly over the target like a bomber. This tag was removed in version 100.0 and changed to a [[Lua_MoveCtrl#MoveType-Controlling|Spring.SetMoveTypeData]] key.
}}

====Flares====
The following set of tags are rarely used and are hardcoded to only work vs. missile weapons. The texture is hardcoded to be <code>flareprojectiletexture</code> defined in [[Resources.lua]]. 
{{tag
|name = canDropFlare
|type = bool
|default = false
|description = Can this aircraft drop flares to distract missile weapons?
}}

{{tag
|name = flareReload
|type = float
|default = 5.0
|lua = flareReloadTime
|description = The time in seconds between successive flare drops.
}}

{{tag
|name = flareDelay
|type = float
|default = 0.3
|description = The delay between detecting an incoming missile and launching flares. Multiplied by a random number between 1 and 16.
}}

{{tag
|name = flareEfficiency
|type = float
|default = 0.5
|description = The probability that an incoming missile will target the flare instead of the aircraft.
}}

{{tag
|name = flareDropVector
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The direction vector which flares are emitted in.
}}

{{tag
|name = flareTime
|type = int
|default = 3
|description = The lifetime of a dropped flare in [[frames]].
}}

{{tag
|name = flareSalvoSize
|type = int
|default = 4
|description = How many flares are dropped at once?
}}

{{tag
|name = flareSalvoDelay
|type = int
|default = 0
|description = The delay in [[frames]] between the release of each individual flare in a burst.
}}

===Transports===
{{tag
|name = transportSize
|type = int
|default = 0
|description = The size of units that the transport can pick up, in terms of the passengers {{taglink|footprintX}}.}}

{{tag
|name = minTransportSize
|type = int
|default = 0
|description = The smallest size of unit that the transport can pick up, in terms of the passengers {{taglink|footprintX}}.}}

{{tag
|name = transportCapacity
|type = int
|default = 0
|description = The total number of units that the transport can pick up, with each unit multiplied by it's {{taglink|footprintX}} size. Prior to 101.0 if this tag is not present, then any Script.AttachUnit and Script.DropUnit call in the animation script will be ignored (See [[Animation-LuaCallouts#Other]]), in successive versions all units can use [[Lua_SyncedCtrl#Unit_Control|Spring.UnitAttach]] et al regardless of this tag.}}

{{tag
|name = transportMass
|type = float
|default = 100000.0
|description = The total cumulative {{taglink|mass}} of passengers the transport can carry.}}

{{tag
|name = minTransportMass
|type = float
|default = 0.0
|description = The minimum {{taglink|mass}} passenger the transport can carry.}}

{{tag
|name = loadingRadius
|type = float
|default = 220.0
|description = How far away in [[elmo]]s can the transporter pick up and drop units?}}

{{tag
|name = unloadSpread
|type = float
|default = 5.0
|description = How spread out the passengers are when unloaded. Is multiplied by the passengers radius.}}

{{tag
|name = isFirePlatform
|type = bool
|default = false
|description = Can transported units still aim and shoot while loaded by this transport?}}

{{tag
|name = holdSteady
|type = bool
|default = false
|description = If <code>true</code> - passengers are slaved to orientation of transporter attachment piece, if <code>false</code> - passengers are slaved to orientation of transporter body.}}

{{tag
|name = releaseHeld
|type = bool
|default = false
|description = Does the transporter unload it's passengers when it dies?}}

{{tag
|name = cantBeTransported
|type = bool
|default = false for mobile units, true for structures
|description = Controls if a unit is transportable at all or not. If <code>false</code> it is overridden by [[Modrules.lua]] <code>transportability</code> subtable tags.}}

{{tag
|name = transportByEnemy
|type = bool
|default = true
|description = Controls if a unit can be transported by an enemy transport. i.e. can it be kidnapped.}}

{{tag
|name = transportUnloadMethod
|type = int
|default = 0
|description = For air transports. Can be <code>0</code> - Land to unload individually, <code>1</code> - Flyover drop (i.e. Parachute), or <code>2</code> - Land and flood unload all passengers. Can be used on ground transports with mixed results.}}

{{tag
|name = fallSpeed
|type = float
|default = 0.2
|description = For air transports with {{taglink|transportUnloadMethod|1}}. The speed in [[elmo]]s per second which units will fall at when released from the transport.}}

{{tag
|name = unitFallSpeed
|type = float
|default = 0.0
|description = Allows you to override {{taglink|fallSpeed}} for an individual passenger.}}

===Categories===
{{tag
|name = category
|type = string
|default = ""
|description = The category tag is a string of separate words, each representing a category of units. There is a maximum of 32 categories. The primary purpose of categories is weapon targeting (See [[#weapons]]).}}

{{tag
|name = noChaseCategory
|type = string
|default = ""
|description = The unit will still target enemies with a matching {{taglink|category}}, but will not chase after it if it moves out of weapon range.}}

===Decals===
{{tag
|name = leaveTracks
|type = bool
|default = false
|description = Does the unit leave a track mark decal behind it when it moves? For mobile units.}}

{{tag
|name = trackType
|type = string
|default = "stdTank"
|description = The filename of the image, without extension, assumed to be in <code>Bitmaps/Tracks/</code>, to be used as the track decal. The red channel of the image controls the brightness and the green channel the alpha (how visible it is) of the track. Blue channel is unused.}}

{{tag
|name = trackWidth
|type = float
|default = 32.0
|description = The width of the track decal left on the ground, in [[elmo]]s.}}

{{tag
|name = trackOffset
|type = float
|default = 0.0
|description = How far back in [[elmo]]s the track should be drawn from the centre of the unit.}}

{{tag
|name = trackStrength
|type = float
|default = 32.0
|description = How visible or 'deep' the track mark should be. Also used to determine how long the decal should last.}}

{{tag
|name = trackStretch
|type = float
|default = 1.0
|description = How much the track is stretched in the forward direction compared to the sides (i.e. used to change aspect ratio).}}

{{tag
|name = useBuildingGroundDecal
|type = bool
|default = false
|description = For structures, do they display a ground decal on the terrain under their model?}}

{{tag
|name = buildingGroundDecalType
|type = string
|default = ""
|description = The filename of the image to be used as ground decal. Assumed to be in <code>Unittextures/</code>.}}

{{tag
|name = buildingGroundDecalSizeX
|type = int
|default = 4
|description = How wide the decal is left to right, in footprint units.}}

{{tag
|name = buildingGroundDecalSizeY
|type = int
|default = 4
|description = How wide the decal is top to bottom, in footprint units.}}

{{tag
|name = buildingGroundDecalDecaySpeed
|type = float
|default = 0.1
|description = A measure of how quickly the decal should fade out if the structure dies. Essentially this value is multiplied by the time since death and subtracted from the original alpha until the decal is fully transparent.}}

===Collision Volumes===
For a deeper explanation of these tags, see [[Gamedev:CollisionVolumes]]. Note that all collision checks first do a pre-check with the unit ''radius'' before doing the colvol checks. Ergo the unit ''radius'' must be larger or equal to the colvol!

{{tag
|name = usePieceCollisionVolumes
|type = bool
|default = false
|lua = collisionVolume.defaultToPieceTree
|description = When turned on the model and UnitDef collision volumes are ignored and Spring generates a bounding box volume for each piece of the unit model. These volumes can be manipulated or replaced by [[Lua_SyncedCtrl#Unit_Control | Spring.SetUnitPieceCollisionVolumeData]]. Increases the performance cost of collision calculations.}}

{{tag
|name = useFootPrintCollisionVolume
|type = bool
|default = false
|special = {{new|92.0}}
|lua = .collisionVolume.defaultToFootprint
|description = Replaces any defined collision volume with a box with dimensions equal to the object's footprint (this also overrides any custom scaling and/or offsets).
}}

The following three tags can instead be replaced with a [[#collisionVolume]] subtable:

{{tag
|name = collisionVolumeType
|type = string
|default = "s"
|lua = collisionVolume.type
|description = What shape should the unit's collision volume be? Can be {{value|"box"}}, {{value|"sphere}} or a cylinder aligned to an axis; {{value|"cylX"}}, {{value|"cylY"}}, {{value|"cylZ"}}.}}

{{tag
|name = collisionVolumeScales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = collisionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the collision volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = collisionVolumeOffsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = collisionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the hit volume centre in each axis.}}

The following tags have now been removed from the engine:

{{tag
|name = collisionVolumeTest
|type = int
|default = 0
|special = Removed in 90.0 (Now always continuous)
|description = The type of test used to detect collisions. Can be <code>0</code> (discrete) or <code>1</code> (continuous). Use the latter for catching high speed projectiles which may otherwise 'skip through' small collision volumes, but beware of the increased performance cost.}}

{{tag
|name = modelCenterOffset
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = Removed in 89.0 (Now set via lua)
|description = How far from the model's defined centre should the centre of the unit be?}}

===Selection Volumes===
Introduced in 104.0, units may now have custom selection volumes in exactly the same way as collision volumes were already defined.

{{tag
|name = usePieceSelectionVolumes
|type = bool
|default = false
|special = {{new|104.0}}
|lua = .selectionVolume.defaultToPieceTree
|description = When turned on the model and UnitDef selection volumes are ignored and Spring generates a bounding box volume for each piece of the unit model (the same volumes are used for collision and selection). These volumes can be manipulated or replaced by [[Lua_SyncedCtrl#Unit_Control | Spring.SetUnitPieceColisionVolumeData]]. Increases the performance cost of selection calculations.}}

{{tag
|name = useFootPrintSelectionVolume
|type = bool
|default = false
|special = {{new|104.0}}
|lua = .selectionVolume.defaultToFootprint
|description = Replaces any defined selection volume with a box with dimensions equal to the object's footprint (this also overrides any custom scaling and/or offsets).
}}

The following three tags can instead be replaced with a [[#selectionVolume]] subtable:

{{tag
|name = selectionVolumeType
|type = string
|default = "s"
|special = {{new|104.0}}
|lua = collisionVolume.type
|description = What shape should the unit's selection volume be? Can be {{value|"box"}}, {{value|"sphere}} or a cylinder aligned to an axis; {{value|"cylX"}}, {{value|"cylY"}}, {{value|"cylZ"}}.}}

{{tag
|name = selectionVolumeScales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = {{new|104.0}}
|lua = .selectionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the selection volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = selectionVolumeOffsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = {{new|104.0}}
|lua = .selectionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the selection volume centre in each axis.}}

===Attack Behaviours===
{{tag
|name = highTrajectory
|type = int
|default = 0
|lua = highTrajectoryType
|description = Can the unit fire it's (ballistic) weapons in a high trajectory arc? Can be <code>0</code> - Low trajectory only, <code>1</code> - High trajectory only, or <code>2</code> - Toggle button.}}

{{tag
|name = kamikaze
|type = bool
|default = false
|lua = canKamikaze
|description = Does the unit attack its target by blowing itself up?}}

{{tag
|name = kamikazeDistance
|type = float
|default = 0.0
|lua = kamikazeDist
|description = How close to the target, in [[elmo]]s, the unit must get before detonating. Measured in 3D, not 2D.}}

{{tag
|name = kamikazeUseLOS
|type = bool
|default = false
|description = Does the target unit have to be in LOS when detonating or only within {{taglink|kamikazeDistance}}.}}

{{tag
|name = strafeToAttack
|type = bool
|default = false
|description = Should the unit move sideways when it can't shoot?}}

===Other===
{{tag
|name = decoyFor
|type = string
|default = ""
|description = The UnitDef name (not human {{taglink|name}}) which this unit is a decoy for.}}

{{tag
|name = selfDestructCountdown
|type = int
|default = 5
|lua = selfDCountdown
|description = The length in seconds taken between issuing self destruct order and the unit exploding.}}

{{tag
|name = damageModifier
|type = float
|default = 1.0
|lua = armoredMultiple
|description = The multiplier applied to weapon damage when the units ARMORED status (See [[Lua_ConstCOB]]) is turned on.}}

{{tag
|name = isTargetingUpgrade
|type = bool
|default = false
|lua = targFac
|description = Does the unit upgrade the targeting so that units shoot accurately at enemy units which are in radar but not in LOS.}}

{{tag
|name = isFeature
|type = bool
|default = false
|description = Does the unit immediately die into it's {{taglink|corpse}} feature when built? Used mainly for making walls.}}

{{tag
|name = hideDamage
|type = bool
|default = false
|description = Should the units current health be invisible to enemy players?}}

{{tag
|name = showPlayerName
|type = bool
|default = false
|description = Should the unit display it's controlling player as its name instead of {{taglink|name}}. Generally used for commander or hero units.}}

{{tag
|name = showNanoFrame
|type = bool
|default = true
|description = Does the unit show an OTA-style nanoframe whilst being constructed?}}

{{tag
|name = unitRestricted
|type = int
|default = MAX_UNITS
|lua = maxThisUnit
|description = How many of this unit type may a player control at once? Defaults to being the maximum amount of units controllable. Is overridden by lobby unit restrictions.}}

{{tag
|name = power
|type = float
|default = {{taglink|buildCostMetal}} + ({{taglink|buildCostEnergy}} / 60.0)
|description = The relative power of the unit. Used in weapon targeting priority and experience gain calculations.}}

==Sub Tables==

===collisionVolume===
The <code>collisionVolume</code> subtable of a UnitDef replaces the older individual {{taglink|collisionVolumeType}}, {{taglink|collisionVolumeScales}} and {{taglink|collisionVolumeOffsets}} tags.

{{tag
|name = type
|type = string
|default = "s"
|lua = .collisionVolume.type
|description = What shape should the unit's collision volume be? Can be {{value|"box"}}, {{value|"sphere"}} or a {{value|"cylinder"}}.}}

{{tag
|name = axis
|type = string
|default = "z"
|description = Which axis does the unit's collision volume lie along? Can be {{value|"x"}}, {{value|"y"}} or {{value|"z"}}.}}

{{tag
|name = scales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .collisionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the collision volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = offsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .collisionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the hit volume centre in each axis.}}

===selectionVolume===
The <code>selectionVolume</code> subtable of a UnitDef can replace the individual {{taglink|selectionVolumeType}}, {{taglink|selectionVolumeScales}} and {{taglink|selectionVolumeOffsets}} tags.

{{tag
|name = type
|type = string
|default = "s"
|lua = .selectionVolume.type
|description = What shape should the unit's selection volume be? Can be {{value|"box"}}, {{value|"sphere"}} or a {{value|"cylinder"}}.}}

{{tag
|name = axis
|type = string
|default = "z"
|description = Which axis does the unit's selection volume lie along? Can be {{value|"x"}}, {{value|"y"}} or {{value|"z"}}.}}

{{tag
|name = scales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .selectionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the selection volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = offsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .selectionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the selection volume centre in each axis.}}

===weapons===
The <code>weapons</code> subtable of a UnitDef tells Spring which weapons the unit has. It is a simple array (number indexed table) of <code>weaponName</code>s (not the human readable <code>name</code>!).

The following additional tags are associated with this subtable:

{{tag
|name = name
|type = string
|default = ""
|description = The <code>weaponName</code> of the weapon (See [[Gamedev:WeaponDefs]]). If using the [[weapondefs_post.lua]] provided by [[springcontent.sdz]], you may include the WeaponDef tables within the UnitDef as the <code>weaponDefs</code> subtable, and refer to them with <code>def</code> rather than <code>name</code>. This can be a useful way to organise definitions if units do not generally share weapons.}}

{{tag
|name = badTargetCategory
|type = string
|default = ""
|description = A string of unit {{taglink|category}} entries which this weapon prefers to avoid targeting. i.e. given two units which ''can'' be targeted, any unit whose {{taglink|category}} matches any entry in this tag, will be targeted last. (See [[#Categories]])}}

{{tag
|name = onlyTargetCategory
|type = string
|default = ""
|description = A string of unit {{taglink|category}} entries which this weapon can target. i.e. any unit whose {{taglink|category}} does not match any entry in this tag, cannot be targeted by this weapon. (See [[#Categories]])}}

{{tag
|name = slaveTo
|type = int
|default = 0
|description = The number of the weapon which this weapon is slaved to. A slaved weapon can only target what it's master is targeting. Weapon numbers start at <code>1</code> and correspond to the index of the weapon within the subtable.}}

{{tag
|name = mainDir
|type = float[3]
|default = {0.0, 0.0, 1.0} i.e. forwards
|description = A vector representing the firing direction of this weapon if it has a limited firing arc. Used in conjunction with {{taglink|maxAngleDif}} (See [[Gamedev:WeaponMainDir]]).}}

{{tag
|name = maxAngleDif
|type = float
|default = 360.0
|description = How wide this weapons limited firing arc is in degrees. Symmetrical about {{taglink|mainDir}} i.e. <code>180.0</code> is 90 degree freedom either way (See [[Gamedev:WeaponMainDir]]).}}

{{tag
|name = fuelUsage
|type = float
|default = 0.0
|description = How much fuel in seconds is deducted from the units initial {{taglink|maxFuel}} when this weapon fires.}}

===buildOptions===
The <code>buildOptions</code> subtable of a UnitDef tells Spring which other units the unit can build (in the case of a builder) or produce (in the case of a factory).
It is a simple array (number indexed table) of <code>unitName</code>s (not the human readable {{taglink|name}}!).

There are no additional tags specific to this subtable.

===SFXTypes===
The <code>SFXTypes</code> subtable of a UnitDef tells Spring which [[CEG]] effects are associated with the unit. It consists of two further subtables, with no additional tags specific to them.

====explosionGenerators====

The <code>explosionGenerators</code> subtable of <code>SFXTypes</code> tells Spring which [[CEG]]s the unit's script can call, via the <code>EmitSFX()</code> callout (See [[Animation-LuaCallouts#Effects]]). It is a simple array (number indexed table) of CEG names, prefaced by the string <code>"custom:"</code>.

====pieceExplosionGenerators====
{{new|83.0}}

The <code>pieceExplosionGenerators</code> subtable of <code>SFXTypes</code> tells Spring which [[CEG]]s the unit's script can pick at random to attach to a flying unit piece, created from the <code>Explode()</code> callout (See [[Animation-LuaCallouts#Effects]]). It is a simple array (number indexed table) of CEG names, with no prefix.

Forum thread (with examples): {{forumlink|topic=27554|title=pieceExplosionGenerators}}

===sounds===

The <code>sounds</code> subtable of a UnitDef tells Spring which sound files to play when the unit triggers various events.

Files are assumed to be in the <code>Sounds/</code> directory; accepted formats are .wav and .ogg, the former being assumed if no extension is given.

Sounds can be defined in one of three ways:

# Each event can be used as though it were a <code>string</code> tag referring to the filename.
# Each event can be the name of a subtable, which is a simple array containing the filenames. One sound is picked at random from the list each time the event occurs.
# Each event can be the name of a subtable, which is a simple array containing further tables, which contain the following tags:
{{tag
|name = file
|type = string
|default = ""
|description = The filename of the sound to play.}}

{{tag
|name = volume
|type = float
|default = 1.0
|description = The default volume of the sound.}}

Spring checks any referenced sound filename to see if a SoundItem has been created, which allows greater control over how it is played (See [[Sounds.lua]]).

====sounds Example====

For clarification, here is an example of all three methods:

<code><pre>sounds = {
-- Method 1
ok = 'oksound', -- .wav appended
-- Method 2
arrived = {
'arrived1.wav',
'arrived2.wav',
},
-- Method 3
select = {
{ file = 'selsound1.ogg', volume = 2.0 },
{ file = 'selsound2.ogg', volume = 2.5 },
},
}</pre></code>

====sounds Events====

The events called by the engine are as follows:

{{ItemType
|name = ok
|description = Unit is issued a command.
}}

{{ItemType
|name = select
|description = Unit is selected by the player.
}}

{{ItemType
|name = arrived
|description = Unit has arrived at its destination. Mobile ground units only.
}}

{{ItemType
|name = build
|description = Unit begins building. Called for both factories and mobile construction units.
}}

{{ItemType
|name = activate
|description = Unit is activated, i.e. Is turned on. Also called when a mobile ground unit starts moving.
}}

{{ItemType
|name = deactivate
|description = Unit deactivates, i.e. Is turned off.
}}

{{ItemType
|name = cant
|description = Unit cannot carry out this order. Loaded but not currently called by the engine.
}}

{{ItemType
|name = underattack
|description = Unit gets attacked. Loaded but not currently called by the engine.
}}

===customParams===
The <code>customParams</code> subtable of a UnitDef allows the game designer to give their units custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
MC:L implements OO with inheritance (base classes in [http://sourceforge.net/p/mwspring/code/HEAD/tree/Gamedata/unitdefs_pre.lua#l36 unitdefs_pre.lua])

{{ExampleRepoLinks
|path = units/
|entity = UnitDefs
}}

[[Category: Game Dev]]

LuaLifecycle

2020-11-08T20:09:00Z

Picassoct: /* On-Load */

This is work in Progress: Its goal is to collect and present all that missing information in the other articles, that lead to look ups in the source code.

== Pre-Load ==

Spring takes your game either as a folder with the ending .sdd or as a zipped file distributed- either traditionally or via rapid, in a series of small files, stored in the rapid (/home/picasso/.spring/rapid/repos.springrts.com) folder in your spring installation.
Spring will compute a hash over those files and folders. If they are altered in name, value or existence, spring will not sync these games up. You will not go to war today.
You can sync a .sdd folder with zipped games, by adding a springignore.txt which is similar to a .gitignore.

You can not add external widgets to a sdd folder and make it work. (TODO Validate)

The nature of this hash, enforces something else. With all content static, you can not store any values "inside" your game.
You can store values as config values within the spring installation. You can load textfiles from external folders reachable to spring.
But you cant change what makes the game.

== On-Load ==

Spring will load your game and then present the loaded files within the game-code as reachable via the VFS (Virtual File System).
Some files can be altered and reloaded for development purposes. This includes the synced lua (/luarules reload) - which is equivalent to starting a new game, synced script wise.
UI-Files can be altered and reloaded, and already existing files at the start can be re-used. (/luaui reload). You can not add new widgets to the folder.
Depending on wether the game allows userWidgets (ModOptions), all already existing widgets in the external /LuaUI/GAMENAME/folder will be reloaded.
In this folder, settings for the User-LuaUI can be stored persistently.

During engine development some mistakes were made, regarding naming during load.
Meaning, a map can have the same lua-rules and luaui folder, to implement map specific content and this content is loaded into the same namespace,
as regular widgets (/luaui) and and gadgets (/luarules).
This can lead to naming collisions and not working widgets / synced game parts, depending on the map.
The usual way to avoid this, is to rename your luaui and luarules (TODO Check) folder and assume that all gadgets /widgets loaded into the default folder are Map based or other external widgets.

For a example of such a architectural separation look at

https://github.com/beyond-all-reason/Beyond-All-Reason/tree/master/luaui

other games have a exclude map lua function, that refuses to load non-game lua.

== On-LuaIntro ==

== On-LuaUI load ==

Depending on how the widgets are loaded and what framework they use, subtle different lua-sntax rules may apply.
This means that lua functions in those widgets will have to be declared to be used in parsing order.

== On-LuaRules/Synced load ==

== On-Victory ==

== On-GameEnd ==

LuaLifecycle

2020-11-08T20:06:47Z

Picassoct: /* On-LuaUI load */

This is work in Progress: Its goal is to collect and present all that missing information in the other articles, that lead to look ups in the source code.

== Pre-Load ==

Spring takes your game either as a folder with the ending .sdd or as a zipped file distributed- either traditionally or via rapid, in a series of small files, stored in the rapid (/home/picasso/.spring/rapid/repos.springrts.com) folder in your spring installation.
Spring will compute a hash over those files and folders. If they are altered in name, value or existence, spring will not sync these games up. You will not go to war today.
You can sync a .sdd folder with zipped games, by adding a springignore.txt which is similar to a .gitignore.

You can not add external widgets to a sdd folder and make it work. (TODO Validate)

The nature of this hash, enforces something else. With all content static, you can not store any values "inside" your game.
You can store values as config values within the spring installation. You can load textfiles from external folders reachable to spring.
But you cant change what makes the game.

== On-Load ==

Spring will load your game and then present the loaded files within the game-code as reachable via the VFS (Virtual File System).
Some files can be altered and reloaded for development purposes. This includes the synced lua (/luarules reload) - which is equivalent to starting a new game, synced script wise.
UI-Files can be altered and reloaded, and already existing files at the start can be re-used. (/luaui reload). You can not add new widgets to the folder.

During engine development some mistakes were made, regarding naming during load.
Meaning, a map can have the same lua-rules and luaui folder, to implement map specific content and this content is loaded into the same namespace,
as regular widgets (/luaui) and and gadgets (/luarules).
This can lead to naming collisions and not working widgets / synced game parts, depending on the map.
The usual way to avoid this, is to rename your luaui and luarules (TODO Check) folder and assume that all gadgets /widgets loaded into the default folder are Map based or other external widgets.

For a example of such a architectural separation look at

https://github.com/beyond-all-reason/Beyond-All-Reason/tree/master/luaui

other games have a exclude map lua function, that refuses to load non-game lua.

== On-LuaIntro ==

== On-LuaUI load ==

Depending on how the widgets are loaded and what framework they use, subtle different lua-sntax rules may apply.
This means that lua functions in those widgets will have to be declared to be used in parsing order.

== On-LuaRules/Synced load ==

== On-Victory ==

== On-GameEnd ==

LuaLifecycle

2020-11-01T21:36:52Z

Picassoct: /* On-LuaUI load */

This is work in Progress: Its goal is to collect and present all that missing information in the other articles, that lead to look ups in the source code.

== Pre-Load ==

Spring takes your game either as a folder with the ending .sdd or as a zipped file distributed- either traditionally or via rapid, in a series of small files, stored in the rapid (/home/picasso/.spring/rapid/repos.springrts.com) folder in your spring installation.
Spring will compute a hash over those files and folders. If they are altered in name, value or existence, spring will not sync these games up. You will not go to war today.
You can sync a .sdd folder with zipped games, by adding a springignore.txt which is similar to a .gitignore.

You can not add external widgets to a sdd folder and make it work. (TODO Validate)

The nature of this hash, enforces something else. With all content static, you can not store any values "inside" your game.
You can store values as config values within the spring installation. You can load textfiles from external folders reachable to spring.
But you cant change what makes the game.

== On-Load ==

Spring will load your game and then present the loaded files within the game-code as reachable via the VFS (Virtual File System).
Some files can be altered and reloaded for development purposes. This includes the synced lua (/luarules reload) - which is equivalent to starting a new game, synced script wise.
UI-Files can be altered and reloaded, and already existing files at the start can be re-used. (/luaui reload). You can not add new widgets to the folder.

During engine development some mistakes were made, regarding naming during load.
Meaning, a map can have the same lua-rules and luaui folder, to implement map specific content and this content is loaded into the same namespace,
as regular widgets (/luaui) and and gadgets (/luarules).
This can lead to naming collisions and not working widgets / synced game parts, depending on the map.
The usual way to avoid this, is to rename your luaui and luarules (TODO Check) folder and assume that all gadgets /widgets loaded into the default folder are Map based or other external widgets.

For a example of such a architectural separation look at

https://github.com/beyond-all-reason/Beyond-All-Reason/tree/master/luaui

other games have a exclude map lua function, that refuses to load non-game lua.

== On-LuaIntro ==

== On-LuaUI load ==

Depending on how the widgets are loaded and what framework they use, subtle different lua-sntax rules may apply. This means that lua functions in those widgets will have to be declared to be used in parsing order.

== On-LuaRules/Synced load ==

== On-Victory ==

== On-GameEnd ==

LuaLifecycle

2020-11-01T21:34:51Z

Picassoct: /* On-Load */

This is work in Progress: Its goal is to collect and present all that missing information in the other articles, that lead to look ups in the source code.

== Pre-Load ==

Spring takes your game either as a folder with the ending .sdd or as a zipped file distributed- either traditionally or via rapid, in a series of small files, stored in the rapid (/home/picasso/.spring/rapid/repos.springrts.com) folder in your spring installation.
Spring will compute a hash over those files and folders. If they are altered in name, value or existence, spring will not sync these games up. You will not go to war today.
You can sync a .sdd folder with zipped games, by adding a springignore.txt which is similar to a .gitignore.

You can not add external widgets to a sdd folder and make it work. (TODO Validate)

The nature of this hash, enforces something else. With all content static, you can not store any values "inside" your game.
You can store values as config values within the spring installation. You can load textfiles from external folders reachable to spring.
But you cant change what makes the game.

== On-Load ==

Spring will load your game and then present the loaded files within the game-code as reachable via the VFS (Virtual File System).
Some files can be altered and reloaded for development purposes. This includes the synced lua (/luarules reload) - which is equivalent to starting a new game, synced script wise.
UI-Files can be altered and reloaded, and already existing files at the start can be re-used. (/luaui reload). You can not add new widgets to the folder.

During engine development some mistakes were made, regarding naming during load.
Meaning, a map can have the same lua-rules and luaui folder, to implement map specific content and this content is loaded into the same namespace,
as regular widgets (/luaui) and and gadgets (/luarules).
This can lead to naming collisions and not working widgets / synced game parts, depending on the map.
The usual way to avoid this, is to rename your luaui and luarules (TODO Check) folder and assume that all gadgets /widgets loaded into the default folder are Map based or other external widgets.

For a example of such a architectural separation look at

https://github.com/beyond-all-reason/Beyond-All-Reason/tree/master/luaui

other games have a exclude map lua function, that refuses to load non-game lua.

== On-LuaIntro ==

== On-LuaUI load ==

== On-LuaRules/Synced load ==

== On-Victory ==

== On-GameEnd ==

LuaLifecycle

2020-11-01T21:09:09Z

Picassoct: WIP

Lua UnsyncedRead

2020-08-04T19:03:35Z

Picassoct: /* Screen Trace */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}
=Unsynced Read=

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetReplayLength''' {{new|92.0}}
( ) -> nil | number (in seconds)
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== Game/Menu Name ==
'''Spring.GetGameName''' {{new|104.0}}
( ) -> string name

Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".

'''Spring.GetMenuName''' {{new|104.0}}
( ) -> string name

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] | [number sortType], [bool showPathingPlayers] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}
if pingTime is == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z

'''Spring.TraceScreenRay'''

( number mouseX, number mouseY [, boolean onlyCoords
[, boolean useMinimap [, boolean includeSky [, boolean ignoreWater [, number D] ] ] ] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

{{new|101.0}} Exended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

to get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")

'''Spring.GetPixelDir''' {{New|95.0}}
( number x, number y ) -> number dirx, number diry, number dirz

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean midPos = false ] ) -> nil | number x, number y, number z
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)
'''Spring.GetUnitSelectionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== Feature ==
'''Spring.GetFeatureSelectionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

== Projectiles ==
'''Spring.GetVisibleProjectiles''' {{New|95.0}}
([ number allyTeamID = -1
[ , boolean addSyncedProjectiles = true
[ , boolean addWeaponProjectiles = true
[ , boolean addPieceProjectiles = true ]]]]
) --> nil | {[1] = projectileID, ...}

== UI ==
'''Spring.GetUICommands''' {{new|101.0}}
( ) -> nil | {
[1] = {
command=string,
description=string,
synced=bool,
cheat=bool,
}, ...
}
Returns a list of available [[UI commands]].

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "pathTraversability" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit & Feature GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean
'''Spring.GetFeatureLuaDraw'''
( number featureID ) -> nil | boolean
'''Spring.GetFeatureNoDraw'''
( number featureID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> nil | {
[1] = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}, ...
}
'''Spring.GetActiveCmdDesc'''
( number index ) -> nil | {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}
'''Spring.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''

( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed,
boolean offscreen

X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner.

{{new|104.0}} Sixth return value offscreen

For world coordinates see Spring.TraceScreenRay

'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number code] = boolean,
[string name] = boolean, {{new|99.0}}
...
}

'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

=== LOS Colors ===
'''Spring.GetLosViewColors'''

( ) -> always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b} {{new|100}}

== Config ==
'''Spring.GetConfigParams''' same information as <code>spring --list-config-vars</code>
( ) -> table {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}

'''Spring.GetConfigInt'''
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigFloat''' {{new|104.0}}
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigString'''
( string name [, string default ] ) -> nil | string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit
'''Spring.GetVideoCapturingMode''' {{new|104.0}}
( ) -> boolean videoCaptureAllowed

== Time ==
'''Spring.GetGameSpeed''' {{new|98.0}}
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.GetFrameTimer''' {{new|102.0}}
( ) -> timer
Get a timer for the start of the frame, this should give better results for camera interpolations.

'''Spring.DiffTimers'''
( timer cur, timer ago, [boolean inMilliseconds]) -> number seconds
{{New|95.0}} optional third argument (boolean) to return dt in milliseconds

== Rendering ==

'''Spring.GetMapSquareTexture'''
(number texSqrX, number texSqrY, number texMipLvl, string luaTexName) -> boolean success

== Logging ==
'''Spring.GetLogSections'''
( ) -> table { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }

== Misc ==
'''Spring.GetClipboard''' {{new|98.0}}
( ) -> string text

[[category: Lua]]

Lua UnsyncedRead

2020-08-04T17:30:47Z

Picassoct: /* Screen Trace */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}
=Unsynced Read=

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetReplayLength''' {{new|92.0}}
( ) -> nil | number (in seconds)
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== Game/Menu Name ==
'''Spring.GetGameName''' {{new|104.0}}
( ) -> string name

Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".

'''Spring.GetMenuName''' {{new|104.0}}
( ) -> string name

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] | [number sortType], [bool showPathingPlayers] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}
if pingTime is == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z

'''Spring.TraceScreenRay'''

( number mouseX, number mouseY [, boolean onlyCoords
[, boolean useMinimap [, boolean includeSky [, boolean ignoreWater [, number D] ] ] ] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

{{new|101.0}} Exended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported.

to get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")

'''Spring.GetPixelDir''' {{New|95.0}}
( number x, number y ) -> number dirx, number diry, number dirz

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean midPos = false ] ) -> nil | number x, number y, number z
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)
'''Spring.GetUnitSelectionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== Feature ==
'''Spring.GetFeatureSelectionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

== Projectiles ==
'''Spring.GetVisibleProjectiles''' {{New|95.0}}
([ number allyTeamID = -1
[ , boolean addSyncedProjectiles = true
[ , boolean addWeaponProjectiles = true
[ , boolean addPieceProjectiles = true ]]]]
) --> nil | {[1] = projectileID, ...}

== UI ==
'''Spring.GetUICommands''' {{new|101.0}}
( ) -> nil | {
[1] = {
command=string,
description=string,
synced=bool,
cheat=bool,
}, ...
}
Returns a list of available [[UI commands]].

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "pathTraversability" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit & Feature GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean
'''Spring.GetFeatureLuaDraw'''
( number featureID ) -> nil | boolean
'''Spring.GetFeatureNoDraw'''
( number featureID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> nil | {
[1] = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}, ...
}
'''Spring.GetActiveCmdDesc'''
( number index ) -> nil | {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}
'''Spring.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''

( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed,
boolean offscreen

X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner.

{{new|104.0}} Sixth return value offscreen

For world coordinates see Spring.TraceScreenRay

'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number code] = boolean,
[string name] = boolean, {{new|99.0}}
...
}

'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

=== LOS Colors ===
'''Spring.GetLosViewColors'''

( ) -> always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b} {{new|100}}

== Config ==
'''Spring.GetConfigParams''' same information as <code>spring --list-config-vars</code>
( ) -> table {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}

'''Spring.GetConfigInt'''
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigFloat''' {{new|104.0}}
( string name [, number default ] ) -> nil | number

'''Spring.GetConfigString'''
( string name [, string default ] ) -> nil | string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit
'''Spring.GetVideoCapturingMode''' {{new|104.0}}
( ) -> boolean videoCaptureAllowed

== Time ==
'''Spring.GetGameSpeed''' {{new|98.0}}
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.GetFrameTimer''' {{new|102.0}}
( ) -> timer
Get a timer for the start of the frame, this should give better results for camera interpolations.

'''Spring.DiffTimers'''
( timer cur, timer ago, [boolean inMilliseconds]) -> number seconds
{{New|95.0}} optional third argument (boolean) to return dt in milliseconds

== Rendering ==

'''Spring.GetMapSquareTexture'''
(number texSqrX, number texSqrY, number texMipLvl, string luaTexName) -> boolean success

== Logging ==
'''Spring.GetLogSections'''
( ) -> table { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }

== Misc ==
'''Spring.GetClipboard''' {{new|98.0}}
( ) -> string text

[[category: Lua]]

Lua camState

2018-09-18T20:09:03Z

Picassoct: /* The raw info */

== TL;DR ==
'''px''', '''py''' and '''pz''' are camera position in world coords.

=== Free camera ===
'''rx''' and '''ry''' are camera rotation in radians about the X and Y axes respectively, where an rx of 0 is horizontal and an ry of 0 is facing south, positive values running anticlockwise. '''rz''' currently (91.0) does nothing.

'''dx''', '''dy''' and '''dz''' have ''nothing'' to do with camera rotation.

== The raw info ==
<pre>
I wanted to use Spring.SetCameraState( table camState, number camTime) -> nil | boolean

The wiki said: camState has the same format as the output of Spring.GetCameraState().

So I ran Spring.Echo(Spring.GetCameraState())
All I got was:
<table>
TABLE:

So, I ran, for every kind of camera:
for index,value in pairs(Spring.GetCameraState()) do
Spring.Echo(index,value)
end

This is what I got:

Switching to Overhead (TA) style camera
name : "ta"
mode : 1
px,py,pz : Position of the ground point in screen center (not camera position)
dx,dy,dz : Camera direction vector?
zscale: how tilted is the camera, from 10 (near horizontal) to 0.05 (near vertical). We have y/z = 1.0/zscale (with a -1 thrown in if flipped)
height : how much above the ground is the camera, cannot be negative -- '' it's absolute height of the camera, ie the camera positions y value, actually (so no difference if cam is above mountain or valley)~~~~''
flipped : -1 for when south is down, 1 for when north is down

exemple:
px, 2000
py, 70
pz, 1800
flipped, -1
dy, 0
name, ta
zscale, 0.5
height, 500
mode, 1
dx, 0
dz, 0

Switching to Total War style camera
rz, 0
rx, -0.9727737903595
name, tw
ry, 3.1415927410126
px, 477.53298950195
py, 100
pz, 447.54751586914
mode, 2

Switching to Rotatable overhead camera
name : "rot"
mode : 3
px,py,pz : Position of the ground point in screen center (not camera position) -- '' actually it seems to be the camera position to me (I set the height with py, not so sure about the others...) ~~~~''
dx,dy,dz : Camera direction vector?
rx,ry,rz : Camera rotation?
oldHeight : how much above the ground is the camera, cannot be negative, cannot be changed (I guess it's just in for when switching to a view that requires it next)

exemple:
px, 522.32415771484
py, 600
pz, 441.25302124023
rz, 0
dx, -4.9136563262664e-008
dy, -0.82505232095718
name, rot
ry, 3.1415927410126
rx, -0.9727737903595
mode, 3
dz, -0.56205677986145
oldHeight, 500

Switching to Free style camera
avx, 0
px, 522.32415771484
gravity, -500
pz, 873.39385986328
autoTilt, 2.6179938316345
dx, -0.011240424588323
dy, -0.82505232095718
dz, -0.5619443655014
py, 964.28167724609
gndOffset, 16
gndLock, -1
goForward, -1
mode, 4
tiltSpeed, 2.6179938316345
velTime, 1.5
slide, 0.5
avz, 0
rx, -0.9727737903595
invertAlt, -1
rz, 0
ry, 3.1615927219391
avy, 0
scrollSpeed, 100
name, free
fov, 45
vz, 0
avelTime, 1
vx, 0
vy, 0

Switching to Smooth style camera
px, 522.32415771484
py, 109.49719238281
pz, 873.39385986328
flipped, -1
dy, -0.89428168535233
name, sm
zscale, 0.5
height, 500
mode, 5
dx, 0
dz, -0.44714084267616

Switching to Orbit style camera
tx, 522.32415771484
ty, 241.19664001465
name, OrbitController
tz, 644.45776367188
px, 522.32415771484
py, 556.63806152344
pz, 873.39385986328
mode, 6

Switching to FPS style camera
px, 1233.4810791016
py, 554.39453125
pz, 873.39385986328
rz, 0
dx, -0.011240424588323
dy, -0.82505232095718
name, fps
ry, 3.1615927219391
rx, -0.9727737903595
mode, 0
dz, -0.5619443655014
oldHeight, 300

Switching to Overhead (TA) style camera
px, 1324.8835449219
py, 254.39453125
pz, 871.56591796875
flipped, -1
dy, -0.89428168535233
name, ta
zscale, 0.5
height, 713.52716064453
mode, 1
dx, 0
dz, -0.44714084267616

Now someone go comment that.

It appears that mod eis simply a number containing the same information as name, but while name is a string, mode is an integer between 0 and 6.

I guess px,py,pz could be the postion, while dx,dy,dz could be the direction?
px,py,pz is the position.
https://github.com/spring/spring/blob/30862626214bd263b1c4489bb197ef1c3dbc0738/rts/Game/Camera/CameraController.cpp#L75
dx,dy,dz is the directional vector, this determinates where the camera points towards.
fov is the field of view.

These values are part of the inherited base class, thus apply to all camera controllers.
rx,ry,rz - are part of a derived class and thus can not be found in all cameras.
https://github.com/spring/spring/blob/30862626214bd263b1c4489bb197ef1c3dbc0738/rts/Game/Camera.cpp#L383
It denotes the rotation of the camera, found in some camera controllers- theroretically these cameras could tilt and tumble around the viewing direction. In practice, setting the direction - always overrides the rotation.

All the other values are also part of the derived classes. Found here:
https://github.com/spring/spring/blob/30862626214bd263b1c4489bb197ef1c3dbc0738/rts/Game/Camera/FreeController.cpp#L380

But what is height? What is zscale? What is flipped? What is oldHeigh? What are rx,ry,rz? Why has orbit no dx,dy,dz but some tx,ty,tz? What about all the free style camera settings? If you know edit that page please!

From testing, I found out flipped invert north/south depending on whether it's negative or positive.

From testing, I found out zscale is how horizontal/vertical are some camera, 10 for almost horizontal TA overhead, 0.05 for almost vertical TA overhead.
</pre>
[[Category: Lua]]

Camtime is optional, and currently not used

Lua camState

2018-09-18T19:59:50Z

Picassoct: /* The raw info */

LuaCallinReturn

2018-03-25T11:32:05Z

Picassoct: /* Unit-Specific: */ Do not want to be that grumpy guy- but please do not look into gadgets.lua for the content of callin arguments. Look at the source: https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynce

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

==Engine Source==
If you can understand Lua code well and wish to get the most up to date info, you can refer to:
{{sourcelink|file=cont/base/springcontent/LuaGadgets/actions.lua}},
{{sourcelink|file=cont/LuaUI/widgets.lua}} and 
{{sourcelink|file=cont/base/springcontent/LuaGadgets/gadgets.lua}} 
to see how widget/gadget call-ins are distributed, find call-in and widgetHandler function definitions, see how they are processed and what values should be returned from some call ins
(are these the only files?)

==What is a callin anyway?==
Call-ins are calls from the engine, into the gadget or widget script. In other words, these functions are called when a particular ''event'' happens.
Some call-in functions can return values to the engine.
===Blocking events with return values===
The call-in functions named '''''Allow'''''XXX can block their event by returning ''false''. 
For example ''AllowUnitTransfer()'' 
<code>return true</code> = allow transfer 
<code>return false</code> = deny transfer

==Commands, general-purpose:==

Initialize() --> none. 
called when widget/gadget gets (re-)loaded.

Shutdown() --> none.

PlayerChanged --> (playerID).
gadget/widget: Use this to check whether a player has become spectator for instance.

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

CommandNotify() --> "id, params, options", where id = the CommandID

KeyPress() --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

KeyRelease() --> "key"

MouseMove() --> "x, y, dx, dy, button"

MousePress() --> "x, y, button" 
button parameter values: left - 1, middle - 2, right - 3

{{new|>96.0}} buttom param removed {{Sourcelinkhash|4c104344e92256e33d79820e9012c5e1178e212b}}

MouseRelease() --> "x, y, button" 
Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same widget that returns true.

MouseWheel() --> "up, value"

IsAbove() --> "x, y" where x,y = screen coordinates.

GetTooltip() --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

AddConsoleLine() --> "msg, priority"

MapDrawCmd() --> "playerID, cmdType, px, py, pz, labeltext"

AllowCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

CommandFallback() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

CommandsChanged() --> unknown (none?)

AllowUnitCreation() --> "unitDefID, builderID, builderTeam, x, y, z, facing"

AllowUnitTransfer() --> "unitID, unitDefID, oldTeam, newTeam, capture"

AllowUnitBuildStep() --> "builderID, builderTeam, unitID, unitDefID, part"

AllowFeatureCreation() --> "featureDefID, teamID, x, y, z"

AllowFeatureBuildStep() --> unknown, please document.

AllowResourceLevel() --> "teamID, res, level"

AllowResourceTransfer() --> "teamID, res, level"

Update() --> "dt" 
called every screenframe. dt is the time since the last screenframe

DefaultCommand() --> "type,id" 
can return an [[Lua_CMDs|CMD]] to change cursor and command. {{forumlink|topic=26438|title=example usage}}

AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID) -> allowFpsControl 
''return true'' allows fps mode, ''return false'' blocks it.

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, attackerID, attackerDefID, attackerTeam" (prior to 94.0)

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" (as of 94.0)

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" (as of 95.0) 
Can overwrite the taken damage by returning a new number value. 

As of 88.0 for both UnitDamaged and UnitPreDamaged:
weaponDefID -1 --> debris collision
weaponDefID -2 --> ground collision
weaponDefID -3 --> object collision
weaponDefID -4 --> fire damage
weaponDefID -5 --> water damage
weaponDefID -6 --> kill damage
weaponDefID -7 --> crush damage

As of 96.0 {Unit,Feature}{Pre}Damaged events receive the 'attacker' ID when object is crushed

UnitExperience() --> "unitID, unitDefID, unitTeam, experience, oldExperience" 
Spring.SetExperienceGrade must be called first to determine how often it is called

UnitCreated() --> "unitID, unitDefID, teamID, builderID"

UnitFinished() --> "unitID, unitDefID, teamID"

UnitFromFactory() --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

UnitDestroyed() --> "unitID, unitDefID, teamID, attackerID, attackerDefID, attackerTeamID"

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam" 
Unit still belongs to old team

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam" 
Unit now belongs to new team

UnitIdle() --> "unitID, unitDefID, teamID"

UnitCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams, cmdTag" (cmdTag only available from version 95.0)

UnitSeismicPing() --> "x, y, z, strength"

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

UnitLeftLos() --> "unitID, unitDefID, teamID"

UnitLoaded() --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

UnitUnloaded() --> "unitID, unitDefID, teamID, transportID"

UnitCloaked() --> "unitID, unitDefID, teamID"

UnitDecloaked)--> "unitID, unitDefID, teamID"

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"
 Only called for unitDefIDs registered via [[Lua_System#Synced|Script.SetWatchUnit]] since 85.0

StockpileChanged() --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

UnitEnteredWater() --> "unitID, unitDefID, teamID"
(as of 95.0)

UnitEnteredAir() --> "unitID, unitDefID, teamID"
(as of 95.0)

UnitLeftWater() --> "unitID, unitDefID, teamID"
(as of 95.0)

UnitLeftAir() --> "unitID, unitDefID, teamID"
(as of 95.0)

ShieldPreDamaged() --> "proID, shieldEmitterWeaponNum, shieldCarrierUnitID, boolBounceProjectile, beamEmitterWaponNumber, beamCarrierUnitID, startx, starty, startz, hitx, hity, hitz"

UnitUnitCollision(colliderID, collideeID) -- needs SetWatchUnit enabled for both parties

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID) Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0

AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defaultPriority)
--> <code>return "targetAllowed, targetPriority"</code>
defaultPriority new in 89.0 

Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0

DrawShield(number unitID, number weaponID) --> boolean

''true'' (<-?) skips Spring's own drawing of shield <weaponID> owned by unit <unitID>

[https://github.com/spring/spring/commit/7bbfd9464d4f74c12163ea0740c8c60d1ba978f1 maybe new in 86.0+]

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag, cmdParams, cmdOptions" cmdParams and cmdOptions are only available from version 95.0

UnitFeatureCollision(colliderID, collideeID, crushKilled) -- needs SetWatchUnit for first and SetWatchFeature for second party

{{new|95.0}} FeatureDamaged() --> "featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam"

{{new|95.0}} FeaturePreDamaged() --> "featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam"

<code>--> return newDamage, impulseMult (=0)</code>

==Drawing:==
Inside these functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

* DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

* DrawWorldPreUnit() --> none.

Spring draws units, features, some water types, cloaked units, and the sun.

* DrawWorld() --> none.

Spring draws command queues, 'map stuff', and map marks.

Each unit might also have a DrawUnit call, [[Lua_UnitRendering|enabled here.]]

DrawUnit(unitID,DrawMode) 
With enum DrawMode { 
notDrawing = 0, 
normalDraw = 1, 
shadowDraw = 2, 
reflectionDraw = 3, 
refractionDraw = 4 
};

DrawFeature(featureID, DrawMode) 

DrawShield(unitID, weaponID, DrawMode) 

DrawProjectile(projectileID, DrawMode) 

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

DrawLoadScreen() --> none. {{new|95.0}}

Only available to LuaIntro, draws custom load screens.

==Game Events:==

GameID() --> "gameID" {{new|89.0}}

Explosion() --> "weaponID, px, py, pz, ownerID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon
 return true to hide the weapon's CEG

ShockFront() --> "power, dx, dy, dz" Not yet implemented!

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail. Not yet implemented!

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) Not yet implemented!

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() -->
number clampedPos.x, number clampedPos.y, number clampedPos.z,
number playerID,
number readyState,
number rawPickPos.x, number rawPickPos.y, number rawPickPos.z

clampedPos = coordinates clamped into startbox, rawPickPos = where player tried to start

{{New|95.0}} the default 'failed to choose' start-position is now just (0,0,0), not (0,-500,0)

readyState can be any one of:
PLAYER_RDYSTATE_UPDATED = 0 -- player picked a position
PLAYER_RDYSTATE_READIED = 1 -- player clicked ready
PLAYER_RDYSTATE_FORCED = 2 -- game was force-started (player did not click ready)
PLAYER_RDYSTATE_FAILED = 3

GameSetup() --> string "state", boolean "ready", table "playerStates"
 return success, newReady

GamePaused() --> "playerID, paused"

PlayerAdded() --> "playerID"

PlayerRemoved() --> "playerID, reason"

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID, weaponDefID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

ProjectileDestroyed() --> "proID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

AllowWeaponInterceptTarget --> "number interceptorUnitID, number interceptorWeaponID, number targetProjectileID"
returns boolean
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

[[Category:Deprecated]]

Lua:Callins

2018-03-25T11:28:27Z

Picassoct: /* Damage Controllers */

= Lua Callins =
This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the [https://github.com/spring/spring/blob/ebb704e008f6ea645947d07be1cfcc272af0428f/doc/changelog.txt#L71 changelog].

Related Sourcecode :
[https://github.com/spring/spring/blob/d9b3927a528a876b9ab4042771e82b050267572a/rts/Lua/LuaHandle.cpp https://github.com/spring/spring/rts/Lua/LuaHandle.cpp]

For now, to use these addons in a widget, replace addon with widget and, for a gadget, replace addon with gadget. For example,
<code><pre>
function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
...
end
</pre></code>

Some functions may differ between (synced) gadget and widgets; those are in the [[#Synced_-_Unsynced_Shared]] section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.

== Common ==
{{LuaCallin
|name = Initialize
|info = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|info = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|args = type, id
|return = {{type|number}} cmdID
|info = Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either "unit or "feature") and the second is its {{var|unitID}} or {{var|featureID}} respectively.
}}

{{LuaCallin
|name = CommandNotify
|args = cmdID, cmdParams, cmdOptions
|return = {{type|bool}} removeCmd
|info = Called when a command is issued. Returning {{value|true}} deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = CommandsChanged
|args = None
|return = ?
|info = Called when the command descriptions changed, e.g. when selecting or deselecting a unit.
}}

{{LuaCallin
|name = WorldTooltip
|args = ttType, data1, data2, data3
|return = {{type|string}} newTooltip
|info = The parameters can be {{value|"unit"}}, {{var|unitID}}; {{value|"feature"}}, {{var|featureID}}; {{value|"ground"}}, {{var|posX}}, {{var|posY}}, {{var|posZ}} or {{value|"selection"}}.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|args = ???
|info = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|args = serverFrameNum
|info = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
}}

{{LuaCallin
|name = GameSetup
|args = state, ready, playerStates
|return = {{type|bool}} success, {{type|bool}} newReady
|info = ???
}}

{{LuaCallin
|name = SunChanged
|args = ???
|info = ???
}}

{{LuaCallin
|name = AddConsoleLine
|args = msg, priority
|info = Called when text is entered into the console (e.g. Spring.Echo).
}}

{{LuaCallin
|name = RecvSkirmishAIMessage
|args = aiTeam, dataStr
|return = ???
|info = ???
}}

{{LuaCallin
|name = RecvFromSynced
|args = ...
|info = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|args = zip
|info = Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See [[Lua_SaveLoad#Save_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

{{LuaCallin
|name = LoadProgress
|args = message, replaceLastLine
|info = Only available to LuaIntro.
}}

{{LuaCallin
|name = GroupChanged
|args = groupID
|info = Called when a unit is added to or removed from a control group. Currently implemented for widgets only.
}}

{{LuaCallin
|name = ConfigureLayout
|args = ???
|return = ???
|info = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|args = x, y
|return = {{type|bool}} isAbove
|info = Called every Update. Must return {{value|true}} for {{name|Mouse*}} events and {{name|GetToolTip}} to be called.
}}

{{LuaCallin
|name = GetTooltip
|args = x, y
|return = {{type|string}} tooltip
|info = Called when {{name|IsAbove}} returns {{value|true}}.
}}

{{LuaCallin
|name = KeyPress
|args = key, mods, isRepeat
|return = {{type|bool}} becomeOwner
|info = Called repeatedly when a key is pressed down. If you want an action to occur only once check for {{var|1=isRepeat == {{value|false}}}}. The {{var|mods}} parameter is a {{type|table}}, with keys {{value|"alt"}}, {{value|"ctrl"}}, {{value|"meta"}} and {{value|"shift"}} each having a boolean value. Return {{value|true}} if you don't want other callins or the engine to also receive this keypress. A list of key codes can be seen at the [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{LuaCallin
|name = KeyRelease
|args = key
|return = {{type|bool}}
|info = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|args = utf8char
|info = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|args = ???
|info = ???
}}

{{LuaCallin
|name = MousePress
|args = x, y, button
|return = {{type|bool}} becomeMouseOwner
|info = Called when a mouse button is pressed. The {{var|button}} parameter supports up to 7 buttons. Must return {{value|true}} for {{name|MouseRelease}} and other functions to be called.
}}

{{LuaCallin
|name = MouseRelease
|args = x, y, button
|return = bool becomeMouseOwner
|info = Called when a mouse button is released. Please note that in order to have Spring call {{name|MouseRelease}}, you need to have a {{name|MousePress}} call-in in the same addon that returns {{value|true}}.
}}

{{LuaCallin
|name = MouseWheel
|args = up, value
|info = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}

{{LuaCallin
|name = MouseMove
|args = x, y, dx, dy, button
|info = Called when the mouse is moved. The {{var|dx}} and {{var|dy}} parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|args = playerID
|info = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|args = playerID
|info = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|args = playerID, reason
|info = Called whenever a player is removed from the game.
}}

=== Downloads ===

{{LuaCallin
|name = DownloadStarted
|args = id
|info = Called when a [[Pr-downloader]] download is started via [[Lua_VFS#Archives|VFS.DownloadArchive]].
}}

{{LuaCallin
|name = DownloadFinished
|args = id
|info = Called when a [[Pr-downloader]] download finishes successfully.
}}

{{LuaCallin
|name = DownloadFailed
|args = id, errorID
|info = Called when a [[Pr-downloader]] download fails to complete.
}}

{{LuaCallin
|name = DownloadProgress
|args = id, downloaded, total
|info = Called incrementally during a [[Pr-downloader]] download.
}}

=== Drawing ===
{{LuaCallin
|name = ViewResize
|args = viewSizeX, viewSizeY
|info = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|args = dt
|info = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}

Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

{{LuaCallin
|name = DrawGenesis
|info = Doesn't render to screen! Use this callin to update textures, shaders, etc. Also available to LuaMenu.
}}

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

{{LuaCallin
|name = DrawWorldPreUnit
|info = Spring draws units, features, some water types, cloaked units, and the sun.
}}

{{LuaCallin
|name = DrawWorld
|info = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|info = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|info = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|info = ???
}}

{{LuaCallin
|name = DrawGroundPreForward
|info = Runs at the start of the forward pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPreDeferred
|info = Runs at the start of the deferred pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPostDeferred
|info = This runs at the end of its respective deferred pass and allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and [[#API:DrawWorldPreUnit|{{name|DrawWorldPreUnit}}]]) via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]].
}}

{{LuaCallin
|name = DrawUnitsPostDeferred
|info = Runs at the end of the unit deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawFeaturesPostDeferred
|info = Runs at the end of the feature deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawScreen
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

{{LuaCallin
|name = DrawScreenEffects
|args = vsx, vsy
|info = Where {{var|vsx}}, {{var|vsy}} are screen coordinates.
}}

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{LuaCallin
|name = DrawLoadScreen
|info = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls {{var|drawMode}} can be one of the following, {{var|1=notDrawing = {{value|0}}}}, {{var|1=normalDraw = {{value|1}}}}, {{var|1=shadowDraw = {{value|2}}}}, {{var|1=reflectionDraw = {{value|3}}}}, {{var|1=refractionDraw = {{value|4}}}}, and finally {{var|1=gameDeferredDraw = {{value|5}}}} which was added in 102.0.

{{LuaCallin
|name = DrawUnit
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of units, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawFeature
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of features, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawShield
|args = unitID, weaponID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of [[Gamedev:WeaponDefs#Shield_(WeaponType)|shields]].
}}

{{LuaCallin
|name = DrawProjectile
|args = projectileID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of weapon (& other) projectiles.
}}

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|args = msg, player
|info = Called when a player issues a UI command e.g. types {{var|/foo}} or {{var|/luarules foo}}.
}}

=== Game ===

{{LuaCallin
|name = GameID
|args = gameID
|info = Called once to deliver the {{var|gameID}}. As of 101.0+ the string is encoded in hex.
}}

{{LuaCallin
|name = GamePaused
|info = Called when the game is paused.
}}

{{LuaCallin
|name = GameOver
|args = winningAllyTeams
|info = The parameter is a {{type|table}} list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}

{{LuaCallin
|name = GameFrame
|args = frame
|info = Called for every game simulation frame (30 per second). Starts at frame {{value|0}} in 101.0+ and {{value|1}} in previous versions.
}}

{{LuaCallin
|name = GamePreload
|info = Called before the 0 gameframe. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|args = teamID
|info = ???
}}

{{LuaCallin
|name = TeamDied
|args = teamID
|info = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}

=== Units ===
{{LuaCallin
|name = UnitCreated
|args = unitID, unitDefID, unitTeam, builderID
|info = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|args = unitID, unitDefID, unitTeam
|info = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|args = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|info = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitReverseBuilt
|args = unitID, unitDefID, unitTeam
|info = Called when a living unit becomes a nanoframe again.
}}

{{LuaCallin
|name = UnitGiven
|args = unitID, unitDefID, newTeam, oldTeam
|info = Called when a unit is transferred between teams. This is called after {{name|UnitTaken}} and in that moment unit is assigned to the '''newTeam'''.
}}

{{LuaCallin
|name = UnitTaken
|args = unitID, unitDefID, oldTeam, newTeam
|info = Called when a unit is transferred between teams. This is called before {{name|UnitGiven}} and in that moment unit is still assigned to the '''oldTeam'''.
}}

{{LuaCallin
|name = UnitDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is damaged (after {{name|UnitPreDamaged}}).
}}

{{LuaCallin
|name = UnitDestroyed
|args = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is destroyed.
}}

{{LuaCallin
|name = RenderUnitDestroyed
|args = unitID, unitDefID, unitTeam
|info = Called just before a unit is invalid, after it finishes its death animation. {{new|101.0}}
}}

{{LuaCallin
|name = UnitStunned
|args = unitID, unitDefID, unitTeam, stunned
|info = Called when a unit changes its stun status. {{new|99.0}}
}}

{{LuaCallin
|name = UnitUnitCollision
|args = colliderID, collideeID
|info = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}

{{LuaCallin
|name = UnitFeatureCollision
|args = colliderID, collideeID
|info = Called when a unit collides with a feature. The unit must be registered with [[Lua_System#Synced|Script.SetWatchUnit]] and the feature registered with [[Lua_System#Synced|Script.SetWatchFeature]].
}}

{{LuaCallin
|name = UnitCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
}}

{{LuaCallin
|name = UnitCmdDone
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|args = unitID, unitDefID, unitTeam, experience, oldExperience
|info = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{LuaCallin
|name = UnitIdle
|args = unitID, unitDefID, unitTeam
|info = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = StockpileChanged
|args = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|info = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}

{{LuaCallin
|name = UnitEnteredLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitSeismicPing
|args = x, y, z, strength, allyTeam, unitID, unitDefID
|info = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}

=== Features ===
{{LuaCallin
|name = FeatureCreated
|args = featureID, allyTeamID
|info = Called when a feature is created.
}}

{{LuaCallin
|name = FeatureDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a feature is damaged.
}}

{{LuaCallin
|name = FeatureDestroyed
|args = featureID, allyTeamID
|info = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|args = ???
|info = ???
}}

=== Projectiles ===
The following Callins are only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].

{{LuaCallin
|name = ProjectileCreated
|args = proID, proOwnerID, weaponDefID
|info = Called when the projectile is created. Note that {{var|weaponDefID}} is missing if the projectile is spawned as part of a burst, but [[Lua_SyncedRead#Projectiles|Spring.GetProjectileDefID]] and [[Lua_SyncedRead#Projectiles|Spring.GetProjectileName]] still work in callin scope using {{var|proID}}.
}}

{{LuaCallin
|name = ProjectileDestroyed
|args = proID
|info = Called when the projectile is destroyed.
}}

== Synced Only ==
{{LuaCallin
|name = CommandFallback
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = {{type|bool}} used, {{type|bool}} finished
|info = Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns {{var|used}} as {{value|true}} the command is dropped, if an addon returns {{value|true}}, {{value|true}} the command is removed because it's done, with {{value|true}}, {{value|false}} it's kept in the queue and {{name|CommandFallback}} gets called again on the next slowupdate.
}}

{{LuaCallin
|name = AllowCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = {{type|bool}} allow
|info = Called when the command is given, before the unit's queue is altered. The return value is whether it should be let into the queue. The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.
}}

{{LuaCallin
|name = AllowUnitCreation
|args = unitDefID, builderID, builderTeam, x, y, z, facing
|return = {{type|bool}} allow
|info = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|args = unitID, unitDefID, oldTeam, newTeam, capture
|return = {{type|bool}} allow
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowUnitBuildStep
|args = builderID, builderTeam, unitID, unitDefID, part
|return = {{type|bool}} allow
|info = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

{{LuaCallin
|name = AllowFeatureCreation
|args = featureDefID, teamID, x, y, z
|return = {{type|bool}} allow
|info = Called just before feature is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowFeatureBuildStep
|args = builderID, builderTeam, featureID, featureDefID, part
|return = {{type|bool}} allow
|info = Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.
}}

{{LuaCallin
|name = AllowResourceLevel
|args = teamID, res, level
|return = {{type|bool}} allow
|info = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
}}

{{LuaCallin
|name = AllowResourceTransfer
|args = oldTeamID, newTeamID, res, amount
|return = {{type|bool}} allow
|info = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|args = playerID, teamID, readyState, clampedX, clampedY, clampedZ, rawX, rawY, rawZ
|return = {{type|bool}} allow
|info = {{var|clamped{X,Y,Z}}} are the coordinates clamped into start-boxes, {{var|raw}} is where player tried to place their marker. The {{var|readyState}} can be any one of
* {{value|0}} - player picked a position,
* {{value|1}} - player clicked ready,
* {{value|2}} - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* {{value|3}} - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.
NB: The order of the parameters changed with the addition of {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

{{LuaCallin
|name = AllowDirectUnitControl
|args = unitID, unitDefID, unitTeam, playerID
|return = {{type|bool}} allow
|info = Determines if this unit can be controlled directly in FPS view.
}}

{{LuaCallin
|name = AllowWeaponTargetCheck
|args = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = {{type|bool}} allowCheck, {{type|bool}} ignoreCheck
|info = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag. The {{var|ignoreCheck}} return value was added in 99.0 to allow ignoring the callin i.e. running normal engine check for this weapon.
}}

{{LuaCallin
|name = AllowWeaponTarget
|args = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = {{type|bool}} allowed, {{type|number}} newPriority
|info = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value is the new priority for this target (if you don't want to change it, return {{var|defPriority}}). Lower priority targets are targeted first.
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|args = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = {{type|bool}} allowed
|info = Controls blocking of a specific intercept target from being considered during an {{xtaglink|Gamedev:WeaponDefs|interceptor}} weapon's periodic auto-targeting sweep. Only called for {{var|weaponDefIDs}} registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

{{LuaCallin
|name = AllowBuilderHoldFire
|args = unitID, unitDefID, action
|return = {{type|bool}} actionAllowed
|info = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}} Called when a construction unit wants to "use his nano beams". {{var|action}} is one of following:
* {{value|-1}} Build
* {{value|CMD.REPAIR}} Repair
* {{value|CMD.RECLAIM}} Reclaim
* {{value|CMD.RESTORE}} Restore
* {{value|CMD.RESURRECT}} Resurrect
* {{value|CMD.CAPTURE}} Capture
}}

{{LuaCallin
|name = Explosion
|args = weaponDefID, px, py, pz, AttackerID, ProjectileID
|return = {{type|bool}} noGfx
|info = Called when an explosion occurs. If it returns {{value|true}} then no graphical effects are drawn by the engine for this explosion.
}}

{{LuaCallin
|name = TerraformComplete
|args = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = {{type|bool}} stop
|info = Called when pre-building terrain levelling terraforms are completed (c.f. {{xtaglink|Gamedev:UnitDefs|levelGround}}). If the return value is {{value|true}} the current build order is terminated.
}}

{{LuaCallin
|name = MoveCtrlNotify
|args = unitID, unitDefID, unitTeam, data
|return = {{type|bool}} moveCtrlComplete
|info = Enable both [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetCollideStop]] and [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetTrackGround]] to enable this call-in, data was supposed to indicate the type of notification but currently never has a value other than {{value|1}} ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled ({{value|false}}) or return to engine controlled movement ({{value|true}}).
}}

{{LuaCallin
|name = RecvLuaMsg
|args = msg, playerID
|info = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}

{{LuaCallin
|name = Load
|args = zip
|info = Called after {{name|GamePreload}} and before {{name|GameStart}}. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

=== Damage Controllers ===
For the following callins, in addition to being a regular weapon, {{var|weaponDefID}} may be one of the following:
* {{value|-1}} - debris collision, also default of [[Lua_SyncedCtrl#Unit_Control|Spring.AddUnitDamage]]
* {{value|-2}} - ground collision
* {{value|-3}} - object collision
* {{value|-4}} - fire damage
* {{value|-5}} - water damage
* {{value|-6}} - kill damage
* {{value|-7}} - crush damage

{{LuaCallin
|name = UnitPreDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the unit, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

{{LuaCallin
|name = ShieldPreDamaged
|I recommend looking up the CallIns in Sourcecode, because the Lua-Documentation, generated from the lua handle of them is seriously flawed and not regenerated.
|Lua-Handler documented from version
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynced.h#L106
|Actual CallIn:
|args = proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|return = {{type|bool}} handleCollision
|info = Called before any engine shield-vs-projectile logic executes. If the return value is {{value|true}} the gadget handles the collision event and the engine does not remove the projectile. If the weapon is a hitscan type ([[Gamedev:WeaponDefs#Tag:weaponType|BeamLaser]] or [[Gamedev:WeaponDefs#Tag:weaponType|LightningCanon]]) then {{var|proID}} is {{value|nil}} and {{var|beamEmitterWeaponNum}} and {{var|beamEmitterUnitID}} are populated instead. The start and hit position arguments are provided from 104.0 onwards.
}}

{{LuaCallin
|name = FeaturePreDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the feature, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

[[Category: Lua]]

Lua Performance

2017-08-04T15:05:58Z

Picassoct: /* Test 13 */

=Overview=

This page is copied from the [http://trac.caspring.org/wiki/LuaPerformance CA wiki]. The widget used in the performance tests is available from the [http://trac.caspring.org/browser/trunk/mods/ca-sandbox/LuaUI/Widgets/performance.lua CA SVN].

=Other Considerations=

It is a well known axiom in computing that

<blockquote>"We should forget about small efficiencies, say about 97% of the time: '''premature optimization is the root of all evil'''"</blockquote>

- [http://en.wikipedia.org/wiki/Donald_Knuth Donald Knuth]

Lua coders should keep that in mind, and especially when visiting this page. Readability and maintainability are in most cases just as important, and optimizing code for every last ounce of performance can severely impact those qualities. On the other hand, some of the optimizations suggested have little bearing on readability and should generally always be applied, e.g. localization of API functions, or actually make for neater code e.g. the use of <code>or</code> rather than a nil-check. Generally speaking, optimize only once you are sure that there is or will be a performance bottleneck.

=Performance Tests=

==TEST 1: Localize==

'''Code:'''

<code><pre> local min = math.min</pre></code>

'''Results:'''

:Non-local: 0.719 (158%)
:Localized: 0.453 (100%)

'''Conclusion:'''

:Yes, we should localize all standard lua and Spring API functions.

==TEST 2: Localized Class-Methods (with only 3 accesses!)==

'''Code 1:'''

<code><pre> for i=1,1000000 do
local x = class.test()
local y = class.test()
local z = class.test()
end</pre></code>

'''Code 2:'''

<code><pre> for i=1,1000000 do
local test = class.test
local x = test()
local y = test()
local z = test()
end</pre></code>

'''Results:'''

:Normal way: 1.203 (102%)
:Localized: 1.172 (100%)

'''Conclusion:'''

:No, it isn't faster to localize a class method IN the function call.

==TEST 3: Unpack A Table==

'''Code 1:'''
<code><pre> for i=1,1000000 do
local x = min( a[1],a[2],a[3],a[4] )
end</pre></code>

'''Code 2:'''
<code><pre> local unpack = unpack
for i=1,1000000 do
local x = min( unpack(a) )
end</pre></code>

'''Code 3:'''
<code><pre> local function unpack4(a)
return a[1],a[2],a[3],a[4]
end
for i=1,1000000 do
local x = min( unpack4(a) )
end</pre></code>

'''Results:'''

:with [ ]: 0.485 (100%)
:unpack(): 1.093 (225%)
:custom unpack4: 0.641 (131%)

'''Conclusion:'''

:Don't use <code>unpack()</code> in time critical code!

==TEST 4: Determine Maximum And Set It ('>' vs. max)==

'''Code 1:'''
<code><pre> local max = math.max
for i=1,1000000 do
x = max(random(cnt),x)
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
local r = random(cnt)
if (r>x) then x = r end
end</pre></code>

'''Results:'''

:math.max: 0.437 (156%)
:'if > then': 0.282 (100%)

'''Conclusion:'''

:Don't use <code>math.[max|min]()</code> in time critical code!

==TEST 5: Nil Checks ('if' vs. 'or')==

'''Code 1:'''
<code><pre> for i=1,1000000 do
local y,x
if (random()>0.5) then y=1 end
if (y==nil) then x=1 else x=y end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
local y
if (random()>0.5) then y=1 end
local x=y or 1
end</pre></code>

'''Results:'''

:nil-check: 0.297 (106%)
:a=x or y: 0.281 (100%)

'''Conclusion:'''

:The <code>or</code>-operator is faster than a nil-check. Use it!

==TEST 6: 'x^2' vs. 'x*x'==

'''Code 1:'''
<code><pre> for i=1,1000000 do
local y = x^2
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
local y = x*x
end</pre></code>

'''Results:'''

:x^2: 1.422 (110%)
:x*x: 1.297 (100%) 

'''Conclusion:'''

:The second syntax is marginally faster

==TEST 7: Modulus Operators (math.mod vs. %)==

'''Code 1:'''
<code><pre> local fmod = math.fmod
for i=1,1000000 do
if (fmod(i,30)<1) then
local x = 1
end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
if ((i%30)<1) then
local x = 1
end
end</pre></code>

'''Results:'''

:math.mod: 0.281 (355%)
:%: 0.079 (100%) 

'''Conclusion:'''

:Don't use <code>math.fmod()</code> for positive numbers (for negative ones <code>%</code> and <code>fmod()</code> have different results!)

==TEST 8: Functions As Param For Other Functions==

'''Code 1:'''
<code><pre> local func1 = function(a,b,func)
return func(a+b)
end

for i=1,1000000 do
local x = func1(1,2,function(a) return a*2 end)
end</pre></code>

'''Code 2:'''
<code><pre> local func1 = function(a,b,func)
return func(a+b)
end
local func2 = function(a)
return a*2
end

for i=1,1000000 do
local x = func1(1,2,func2)
end</pre></code>

'''Results:'''

:defined in function param: 3.890 (1144%)
:defined as local: 0.344 (100%) 

'''Conclusion:'''

:REALLY, LOCALIZE YOUR FUNCTIONS ALWAYS BEFORE SENDING THEM INTO ANOTHER FUNCTION!!! i.e if you use gl.BeginEnd(), gl.CreateList(), ...!!!

==TEST 9: for-loops==

'''Code 1:'''
<code><pre> for i=1,1000000 do
for j,v in pairs(a) do
x=v
end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
for j,v in ipairs(a) do
x=v
end
end</pre></code>

'''Code 3:'''
<code><pre> for i=1,1000000 do
for i=1,100 do
x=a[i]
end
end</pre></code>

'''Code 4:'''
<code><pre> for i=1,1000000 do
for i=1,#a do
x=a[i]
end
end</pre></code>

'''Code 5:'''
<code><pre> for i=1,1000000 do
local length = #a
for i=1,length do
x=a[i]
end
end</pre></code>

'''Results:'''

:pairs: 3.078 (217%)
:ipairs: 3.344 (236%)
:for i=1,x do: 1.422 (100%)
:for i=1,#atable do 1.422 (100%)
:for i=1,atable_length do: 1.562 (110%)

'''Conclusion:'''

:Don't use <code>pairs()</code> or <code>ipairs()</code> in critical code! Try to save the table-size somewhere and use <code>for i=1,x do</code>!

==TEST 10: Array Access (with [ ]) vs. Object Access (with .method)==

'''Code 1:'''
<code><pre> for i=1,1000000 do
x = a["foo"]
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
x = a.foo
end</pre></code>

'''Results:'''

:atable["foo"]: 1.125 (100%)
:atable.foo: 1.141 (101%)

'''Conclusion:'''

:No difference.

==TEST 11: Buffered Table Item Access==

'''Code 1:'''
<code><pre> for i=1,1000000 do
for n=1,100 do
a[n].x=a[n].x+1
end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
for n=1,100 do
local y = a[n]
y.x=y.x+1
end
end</pre></code>

'''Results:'''

:'a[n].x=a[n].x+1': 1.453 (127%)
:'local y=a[n]; y.x=y.x+1': 1.140 (100%) 

'''Conclusion:'''

:Buffering can speed up table item access.

==TEST 12: Adding Table Items (table.insert vs. [ ])==

'''Code 1:'''
<code><pre> local tinsert = table.insert
for i=1,1000000 do
tinsert(a,i)
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
a[i]=i
end</pre></code>

'''Code 3:'''
<code><pre> for i=1,1000000 do
a[#a+1]=i
end</pre></code>

'''Code 4:'''
<code><pre> local count = 1
for i=1,1000000 do
d[count]=i
count=count+1
end</pre></code>

'''Results:'''

:table.insert: 1.250 (727%)
:a[i]: 0.172 (100%)
:a[#a+1]=x: 0.453 (263%)
:a[count++]=x: 0.203 (118%)

'''Conclusion:'''
:Don't use <code>table.insert</code>!!! Try to save the table-size somewhere and use <code>a[count+1]=x</code>!

==TEST 12: Adding Table Items (mytable ={} vs. mytable={...})==

When you write {true, true, true} , Lua knows beforehand that the table will need three slots in its array part, so Lua creates the table with that size. Similarly, if you write
{x = 1, y = 2, z = 3}, Lua will create a table with four slots in its hash part.

As an example, the next loop runs in 2.0 seconds:

<code>for i = 1, 1000000 do

local a = {}

a[1] = 1; a[2] = 2; a[3] = 3

end
</code>

If we create the tables with the right size, we reduce the run t
ime to 0.7 seconds:

<code>
for i = 1, 1000000 do

local a = {true, true, true}

a[1] = 1; a[2] = 2; a[3] = 3

end
</code>

If you write something like {[1] = true, [2] = true, [3] = true}, however, Lua is not smart enough to detect that the given expressions (literal numbers, in this case) describe array indices, so it creates a table with four slots in its hash part, wasting memory and CPU time

[http://www.lua.org/gems/sample.pdf]

=Test 13=
Table initialisation with local members and static intialisation.
<code><pre>
local x = os.clock()
T={}
print(string.format("start time: %.2f\n", os.clock() - x))
local CachedTable= {"abc","def","ghk"}
for i=1 , 10000000, 1 do
T[i] = CachedTable
end
print(string.format("elapsed time: %.2f\n", os.clock() - x))
</pre></code>
<code><pre>
local x = os.clock()
A={}
print(string.format("start time: %.2f\n", os.clock() - x))
for i=1 , 10000000, 1 do
A[i] = {"abc","def","ghk"}
end
print(string.format("elapsed time: %.2f\n", os.clock() - x))
</pre></code>
Result:
local table initializer = 100 %
static intializer = 500 %

Analysis: Lua sucks at identifying static initializers, do not use them, use local initalizations instead.

=Lua Garbage Collection=
Forum thread about {{forumlink|topic=31049|title= Lua Garbage collection info}}

[[Category: Lua]]

Lua Performance

2017-08-04T15:04:55Z

Picassoct: /* Lua Garbage Collection */

=Overview=

This page is copied from the [http://trac.caspring.org/wiki/LuaPerformance CA wiki]. The widget used in the performance tests is available from the [http://trac.caspring.org/browser/trunk/mods/ca-sandbox/LuaUI/Widgets/performance.lua CA SVN].

=Other Considerations=

It is a well known axiom in computing that

<blockquote>"We should forget about small efficiencies, say about 97% of the time: '''premature optimization is the root of all evil'''"</blockquote>

- [http://en.wikipedia.org/wiki/Donald_Knuth Donald Knuth]

Lua coders should keep that in mind, and especially when visiting this page. Readability and maintainability are in most cases just as important, and optimizing code for every last ounce of performance can severely impact those qualities. On the other hand, some of the optimizations suggested have little bearing on readability and should generally always be applied, e.g. localization of API functions, or actually make for neater code e.g. the use of <code>or</code> rather than a nil-check. Generally speaking, optimize only once you are sure that there is or will be a performance bottleneck.

=Performance Tests=

==TEST 1: Localize==

'''Code:'''

<code><pre> local min = math.min</pre></code>

'''Results:'''

:Non-local: 0.719 (158%)
:Localized: 0.453 (100%)

'''Conclusion:'''

:Yes, we should localize all standard lua and Spring API functions.

==TEST 2: Localized Class-Methods (with only 3 accesses!)==

'''Code 1:'''

<code><pre> for i=1,1000000 do
local x = class.test()
local y = class.test()
local z = class.test()
end</pre></code>

'''Code 2:'''

<code><pre> for i=1,1000000 do
local test = class.test
local x = test()
local y = test()
local z = test()
end</pre></code>

'''Results:'''

:Normal way: 1.203 (102%)
:Localized: 1.172 (100%)

'''Conclusion:'''

:No, it isn't faster to localize a class method IN the function call.

==TEST 3: Unpack A Table==

'''Code 1:'''
<code><pre> for i=1,1000000 do
local x = min( a[1],a[2],a[3],a[4] )
end</pre></code>

'''Code 2:'''
<code><pre> local unpack = unpack
for i=1,1000000 do
local x = min( unpack(a) )
end</pre></code>

'''Code 3:'''
<code><pre> local function unpack4(a)
return a[1],a[2],a[3],a[4]
end
for i=1,1000000 do
local x = min( unpack4(a) )
end</pre></code>

'''Results:'''

:with [ ]: 0.485 (100%)
:unpack(): 1.093 (225%)
:custom unpack4: 0.641 (131%)

'''Conclusion:'''

:Don't use <code>unpack()</code> in time critical code!

==TEST 4: Determine Maximum And Set It ('>' vs. max)==

'''Code 1:'''
<code><pre> local max = math.max
for i=1,1000000 do
x = max(random(cnt),x)
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
local r = random(cnt)
if (r>x) then x = r end
end</pre></code>

'''Results:'''

:math.max: 0.437 (156%)
:'if > then': 0.282 (100%)

'''Conclusion:'''

:Don't use <code>math.[max|min]()</code> in time critical code!

==TEST 5: Nil Checks ('if' vs. 'or')==

'''Code 1:'''
<code><pre> for i=1,1000000 do
local y,x
if (random()>0.5) then y=1 end
if (y==nil) then x=1 else x=y end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
local y
if (random()>0.5) then y=1 end
local x=y or 1
end</pre></code>

'''Results:'''

:nil-check: 0.297 (106%)
:a=x or y: 0.281 (100%)

'''Conclusion:'''

:The <code>or</code>-operator is faster than a nil-check. Use it!

==TEST 6: 'x^2' vs. 'x*x'==

'''Code 1:'''
<code><pre> for i=1,1000000 do
local y = x^2
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
local y = x*x
end</pre></code>

'''Results:'''

:x^2: 1.422 (110%)
:x*x: 1.297 (100%) 

'''Conclusion:'''

:The second syntax is marginally faster

==TEST 7: Modulus Operators (math.mod vs. %)==

'''Code 1:'''
<code><pre> local fmod = math.fmod
for i=1,1000000 do
if (fmod(i,30)<1) then
local x = 1
end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
if ((i%30)<1) then
local x = 1
end
end</pre></code>

'''Results:'''

:math.mod: 0.281 (355%)
:%: 0.079 (100%) 

'''Conclusion:'''

:Don't use <code>math.fmod()</code> for positive numbers (for negative ones <code>%</code> and <code>fmod()</code> have different results!)

==TEST 8: Functions As Param For Other Functions==

'''Code 1:'''
<code><pre> local func1 = function(a,b,func)
return func(a+b)
end

for i=1,1000000 do
local x = func1(1,2,function(a) return a*2 end)
end</pre></code>

'''Code 2:'''
<code><pre> local func1 = function(a,b,func)
return func(a+b)
end
local func2 = function(a)
return a*2
end

for i=1,1000000 do
local x = func1(1,2,func2)
end</pre></code>

'''Results:'''

:defined in function param: 3.890 (1144%)
:defined as local: 0.344 (100%) 

'''Conclusion:'''

:REALLY, LOCALIZE YOUR FUNCTIONS ALWAYS BEFORE SENDING THEM INTO ANOTHER FUNCTION!!! i.e if you use gl.BeginEnd(), gl.CreateList(), ...!!!

==TEST 9: for-loops==

'''Code 1:'''
<code><pre> for i=1,1000000 do
for j,v in pairs(a) do
x=v
end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
for j,v in ipairs(a) do
x=v
end
end</pre></code>

'''Code 3:'''
<code><pre> for i=1,1000000 do
for i=1,100 do
x=a[i]
end
end</pre></code>

'''Code 4:'''
<code><pre> for i=1,1000000 do
for i=1,#a do
x=a[i]
end
end</pre></code>

'''Code 5:'''
<code><pre> for i=1,1000000 do
local length = #a
for i=1,length do
x=a[i]
end
end</pre></code>

'''Results:'''

:pairs: 3.078 (217%)
:ipairs: 3.344 (236%)
:for i=1,x do: 1.422 (100%)
:for i=1,#atable do 1.422 (100%)
:for i=1,atable_length do: 1.562 (110%)

'''Conclusion:'''

:Don't use <code>pairs()</code> or <code>ipairs()</code> in critical code! Try to save the table-size somewhere and use <code>for i=1,x do</code>!

==TEST 10: Array Access (with [ ]) vs. Object Access (with .method)==

'''Code 1:'''
<code><pre> for i=1,1000000 do
x = a["foo"]
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
x = a.foo
end</pre></code>

'''Results:'''

:atable["foo"]: 1.125 (100%)
:atable.foo: 1.141 (101%)

'''Conclusion:'''

:No difference.

==TEST 11: Buffered Table Item Access==

'''Code 1:'''
<code><pre> for i=1,1000000 do
for n=1,100 do
a[n].x=a[n].x+1
end
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
for n=1,100 do
local y = a[n]
y.x=y.x+1
end
end</pre></code>

'''Results:'''

:'a[n].x=a[n].x+1': 1.453 (127%)
:'local y=a[n]; y.x=y.x+1': 1.140 (100%) 

'''Conclusion:'''

:Buffering can speed up table item access.

==TEST 12: Adding Table Items (table.insert vs. [ ])==

'''Code 1:'''
<code><pre> local tinsert = table.insert
for i=1,1000000 do
tinsert(a,i)
end</pre></code>

'''Code 2:'''
<code><pre> for i=1,1000000 do
a[i]=i
end</pre></code>

'''Code 3:'''
<code><pre> for i=1,1000000 do
a[#a+1]=i
end</pre></code>

'''Code 4:'''
<code><pre> local count = 1
for i=1,1000000 do
d[count]=i
count=count+1
end</pre></code>

'''Results:'''

:table.insert: 1.250 (727%)
:a[i]: 0.172 (100%)
:a[#a+1]=x: 0.453 (263%)
:a[count++]=x: 0.203 (118%)

'''Conclusion:'''
:Don't use <code>table.insert</code>!!! Try to save the table-size somewhere and use <code>a[count+1]=x</code>!

==TEST 12: Adding Table Items (mytable ={} vs. mytable={...})==

When you write {true, true, true} , Lua knows beforehand that the table will need three slots in its array part, so Lua creates the table with that size. Similarly, if you write
{x = 1, y = 2, z = 3}, Lua will create a table with four slots in its hash part.

As an example, the next loop runs in 2.0 seconds:

<code>for i = 1, 1000000 do

local a = {}

a[1] = 1; a[2] = 2; a[3] = 3

end
</code>

If we create the tables with the right size, we reduce the run t
ime to 0.7 seconds:

<code>
for i = 1, 1000000 do

local a = {true, true, true}

a[1] = 1; a[2] = 2; a[3] = 3

end
</code>

If you write something like {[1] = true, [2] = true, [3] = true}, however, Lua is not smart enough to detect that the given expressions (literal numbers, in this case) describe array indices, so it creates a table with four slots in its hash part, wasting memory and CPU time

[http://www.lua.org/gems/sample.pdf]

=Test 13=
Table initialisation with local members and static intialisation.
local x = os.clock()
T={}
print(string.format("start time: %.2f\n", os.clock() - x))
local CachedTable= {"abc","def","ghk"}
for i=1 , 10000000, 1 do
T[i] = CachedTable
end
print(string.format("elapsed time: %.2f\n", os.clock() - x))

local x = os.clock()
A={}
print(string.format("start time: %.2f\n", os.clock() - x))
for i=1 , 10000000, 1 do
A[i] = {"abc","def","ghk"}
end
print(string.format("elapsed time: %.2f\n", os.clock() - x))

Result:
local table initializer = 100 %
static intializer = 500 %

Analysis: Lua sucks at identifying static initializers, do not use them, use local initalizations instead.

=Lua Garbage Collection=
Forum thread about {{forumlink|topic=31049|title= Lua Garbage collection info}}

[[Category: Lua]]

Animation-LuaScripting

2017-04-22T23:56:51Z

Picassoct: /* Workflow for animating S3o models in Blender */

== Getting started ==

=== Setup ===

Lua unit animation is implemented partially in the engine, and partially in a Lua gadget which is shipped with Spring in [[springcontent.sdz]]. By default, gadget is not loaded, so a bit of setup is required to enable Lua unit scripts. (In some games, gadget is alredy activated, for example in Zero:k)

To enable Lua unit scripts, create a file ''LuaRules/Gadgets/unit_script.lua'', and paste the following into it:

{|border="0" cellpadding="4"
|style="background: #41545c; border: 1px #aaa solid;"|

-- Enables Lua unit scripts by including the gadget from springcontent.sdz

-- Uncomment to override the directory which is scanned for *.lua unit scripts.
--UNITSCRIPT_DIR = "scripts/"

return include("LuaGadgets/Gadgets/unit_script.lua")

|}

Also, do check whether your [http://github.com/spring/spring/blob/master/installer/builddata/springcontent/LuaGadgets/system.lua ''LuaRules/system.lua''] is up to date, if you copied this verbatim into your game. (Must be from a later date than 5 september 2009)

Now this is done, you can start putting *.lua files in your ''scripts/'' folder.

=== Workflow ===

Lua has the major advantage over BOS/COB that you do not need to compile it, which can reduce the time to develop scripts quite a bit.

To save further time, do not restart Spring for each small change. Simply run Spring in an window so you can easily switch between your editor and Spring, and use ''/cheat'' and ''/luarules reload'' to reload all Lua unit scripts.

To be able to use commands above, unzip your game into directory named "myGame.sdd", then you can directly change lua scripts (animations etc.) and reload.

Additionally, for Lua unit scripts operating on Assimp models (primarily .dae and .blend), it is possible to do most of your animating in Blender using the [https://github.com/Anarchid/blender2lus blender2lus] export addon.

=== Workflow for animating S3o models in Blender ===

Anarchids Blendertools can be used to animate (within limits) S3O models. Here are the steps:

1. Export your model into Blender.

2. Restore the Hierarchy in Blender.

https://blender.stackexchange.com/questions/26108/how-do-i-parent-objects
(Ctrl + P) is your friend .

3. If all Pivots are set correctly, create the Animations, one by one.

4. Export the Animations with Anarchids Skript Export tool.

5. Open the resulting Animationskript for postprocesing.

6. Find Move commands like {['c']='move',['p']=LowerJaw, ['a']=x_axis, ['t']=-0.000000, ['s']=0.012682}, and purge them. Replace them with todos- you will have to insert them manually later, with correct axis and values.

7.In the turn commands - exchange the ['a']=z_axis with ['a']=y_axisz and the old ['a']=y_axis with ['a']=z_axis.
Here is a Regex, to make the text-search easier.

{\['c']='turn',\['p']=([^\s]+), \['a']=z_axis, \['t']=\*

{\['c']='turn',\['p']=([^\s]+), \['a']=y_axis, \['t']=\*

8. Invert (change the sign) of the y_axis values.

9. Start the game and call the Animation you want to debug in a Loop.

10. Congratulations you now have smoothly animated S3o Models.

== Further reading ==
* [http://tvo.github.com/spring/2010/04/19/lus-stumpy.html Stumpy tutorial]
* [http://tvo.github.com/spring/2010/04/26/lus-stumpy-2.html Polishing the stumpy]
* [[Animation-LuaCallins]]
* [[Animation-LuaCallouts]]
* [[Animation-CobLuaDifferences | comparing Lua and COB unit scripts]]
* [[SpringTutorialGame]] contains simple examples unit scripts
* [[SpringRtsTutorialAnimDef]] examples animation scripts

== TODO ==

* Conversion tool
* Performance measurements
* Link to article in piro's magazine
* Coordinate system (axis, direction of rotation, picture)

[[Category:Animation]]

Animation-LuaScripting

2017-04-22T23:48:03Z

Picassoct: /* Workflow for animating S3o models in Blender */

== Getting started ==

=== Setup ===

Lua unit animation is implemented partially in the engine, and partially in a Lua gadget which is shipped with Spring in [[springcontent.sdz]]. By default, gadget is not loaded, so a bit of setup is required to enable Lua unit scripts. (In some games, gadget is alredy activated, for example in Zero:k)

To enable Lua unit scripts, create a file ''LuaRules/Gadgets/unit_script.lua'', and paste the following into it:

{|border="0" cellpadding="4"
|style="background: #41545c; border: 1px #aaa solid;"|

-- Enables Lua unit scripts by including the gadget from springcontent.sdz

-- Uncomment to override the directory which is scanned for *.lua unit scripts.
--UNITSCRIPT_DIR = "scripts/"

return include("LuaGadgets/Gadgets/unit_script.lua")

|}

Also, do check whether your [http://github.com/spring/spring/blob/master/installer/builddata/springcontent/LuaGadgets/system.lua ''LuaRules/system.lua''] is up to date, if you copied this verbatim into your game. (Must be from a later date than 5 september 2009)

Now this is done, you can start putting *.lua files in your ''scripts/'' folder.

=== Workflow ===

Lua has the major advantage over BOS/COB that you do not need to compile it, which can reduce the time to develop scripts quite a bit.

To save further time, do not restart Spring for each small change. Simply run Spring in an window so you can easily switch between your editor and Spring, and use ''/cheat'' and ''/luarules reload'' to reload all Lua unit scripts.

To be able to use commands above, unzip your game into directory named "myGame.sdd", then you can directly change lua scripts (animations etc.) and reload.

Additionally, for Lua unit scripts operating on Assimp models (primarily .dae and .blend), it is possible to do most of your animating in Blender using the [https://github.com/Anarchid/blender2lus blender2lus] export addon.

=== Workflow for animating S3o models in Blender ===

Anarchids Blendertools can be used to animate (within limits) S3O models. Here are the steps:

1. Export your model into Blender.

2. Restore the Hierarchy in Blender.

https://blender.stackexchange.com/questions/26108/how-do-i-parent-objects
(Ctrl + P) is your friend .

3. If all Pivots are set correctly, create the Animations, one by one.

4. Export the Animations with Anarchids Skript Export tool.

5. Open the resulting Animationskript for postprocesing.

6. Find Move commands like {['c']='move',['p']=LowerJaw, ['a']=x_axis, ['t']=-0.000000, ['s']=0.012682}, and purge them. Replace them with todos- you will have to insert them manually later, with correct axis and values.

7.In the turn commands - exchange the z and the y_axis.
Here is a Regex, to make the text-search easier.

{\['c']='turn',\['p']=([^\s]+), \['a']=z_axis, \['t']=\*

{\['c']='turn',\['p']=([^\s]+), \['a']=y_axis, \['t']=\*

8. Invert (change the sign) of the y_axis values.

9. Start the game and call the Animation you want to debug in a Loop.

10. Congratulations you now have smoothly animated S3o Models.

== Further reading ==
* [http://tvo.github.com/spring/2010/04/19/lus-stumpy.html Stumpy tutorial]
* [http://tvo.github.com/spring/2010/04/26/lus-stumpy-2.html Polishing the stumpy]
* [[Animation-LuaCallins]]
* [[Animation-LuaCallouts]]
* [[Animation-CobLuaDifferences | comparing Lua and COB unit scripts]]
* [[SpringTutorialGame]] contains simple examples unit scripts
* [[SpringRtsTutorialAnimDef]] examples animation scripts

== TODO ==

* Conversion tool
* Performance measurements
* Link to article in piro's magazine
* Coordinate system (axis, direction of rotation, picture)

[[Category:Animation]]

Animation-LuaScripting

2017-04-22T23:44:52Z

Picassoct: S3o Animations via Blenderplugin

== Getting started ==

=== Setup ===

Lua unit animation is implemented partially in the engine, and partially in a Lua gadget which is shipped with Spring in [[springcontent.sdz]]. By default, gadget is not loaded, so a bit of setup is required to enable Lua unit scripts. (In some games, gadget is alredy activated, for example in Zero:k)

To enable Lua unit scripts, create a file ''LuaRules/Gadgets/unit_script.lua'', and paste the following into it:

{|border="0" cellpadding="4"
|style="background: #41545c; border: 1px #aaa solid;"|

-- Enables Lua unit scripts by including the gadget from springcontent.sdz

-- Uncomment to override the directory which is scanned for *.lua unit scripts.
--UNITSCRIPT_DIR = "scripts/"

return include("LuaGadgets/Gadgets/unit_script.lua")

|}

Also, do check whether your [http://github.com/spring/spring/blob/master/installer/builddata/springcontent/LuaGadgets/system.lua ''LuaRules/system.lua''] is up to date, if you copied this verbatim into your game. (Must be from a later date than 5 september 2009)

Now this is done, you can start putting *.lua files in your ''scripts/'' folder.

=== Workflow ===

Lua has the major advantage over BOS/COB that you do not need to compile it, which can reduce the time to develop scripts quite a bit.

To save further time, do not restart Spring for each small change. Simply run Spring in an window so you can easily switch between your editor and Spring, and use ''/cheat'' and ''/luarules reload'' to reload all Lua unit scripts.

To be able to use commands above, unzip your game into directory named "myGame.sdd", then you can directly change lua scripts (animations etc.) and reload.

Additionally, for Lua unit scripts operating on Assimp models (primarily .dae and .blend), it is possible to do most of your animating in Blender using the [https://github.com/Anarchid/blender2lus blender2lus] export addon.

=== Workflow for animating S3o models in Blender ===
Anarchids Blendertools can be used to animate (within limits) S3O models. Here are the steps:
1. Export your model into Blender.
2. Restore the Hierarchy in Blender.
https://blender.stackexchange.com/questions/26108/how-do-i-parent-objects
(Ctrl + P) is your friend .
3. If all Pivots are set correctly, create the Animations, one by one.
4. Export the Animations with Anarchids Skript Export tool.
5. Open the resulting Animationskript for postprocesing.
6. Find Move commands like {['c']='move',['p']=LowerJaw, ['a']=x_axis, ['t']=-0.000000, ['s']=0.012682}, and purge them. Replace them with todos- you will have to insert them manually later, with correct axis and values.
7.In the turn commands - exchange the z and the y_axis.
Here is a Regex, to make the text-search easier.
{\['c']='turn',\['p']=([^\s]+), \['a']=z_axis, \['t']=\*
{\['c']='turn',\['p']=([^\s]+), \['a']=y_axis, \['t']=-1\*
8. Invert (change the sign) of the y_axis values.
9. Start the game and call the Animation you want to debug in a Loop.
10. Congratulations you now have smoothly animated S3o Models.

== Further reading ==
* [http://tvo.github.com/spring/2010/04/19/lus-stumpy.html Stumpy tutorial]
* [http://tvo.github.com/spring/2010/04/26/lus-stumpy-2.html Polishing the stumpy]
* [[Animation-LuaCallins]]
* [[Animation-LuaCallouts]]
* [[Animation-CobLuaDifferences | comparing Lua and COB unit scripts]]
* [[SpringTutorialGame]] contains simple examples unit scripts
* [[SpringRtsTutorialAnimDef]] examples animation scripts

== TODO ==

* Conversion tool
* Performance measurements
* Link to article in piro's magazine
* Coordinate system (axis, direction of rotation, picture)

[[Category:Animation]]

Map, Game, And Unit Development Programs

2017-04-22T23:16:59Z

Picassoct:

[[Engine_Development|Development]] < {{FULLPAGENAME}}

A Comprehensive list of tools to make Spring content.

*Those that are Open Source are marked with a *
*Those that are Free are marked with a *
*Those that Cost are marked with a *'''

=== Image Editing ===
# '''[http://krita.org/ Krita]'''** digital painting application, cross platform, with 16bit image support.
# '''[http://www.gimp.org Gimp]'''**
# '''[http://www.adobe.com/products/photoshop/main.html Adobe Photoshop]'''* -> The most widely used image editing program ever.
# '''[http://www.getpaint.net Paint.NET]'''* -> Basically an expanded version of Paint. Contains many functions such as layers, and is much easier to use then The Gimp.

=== 3d Modeling ===

# '''[http://blender.org Blender]'''** FREE-> The most used open-source modeller that has its own way of doing things.
Now features animation export for dae and s3o.
# '''[http://www.wings3d.com/ Wings 3D]'''** FREE-> Probably the most popular modeller for Spring. -> Easy to learn modelling and UV mapping environments. -> Excellent introduction to using it can be found [http://www.wings3d.com/doghouse.php here]. -> For help on how to UV map with it just ask around.low poly
# '''[http://www.anim8or.com/main/index.html Anim8or]'''*'''
# '''[http://www.autodesk.com/products/autodesk-3ds-max/overview 3DS MAX]'''* -> The most widely used and acclaimed modelling program ever. Used in creation of many games and movies (The Matrix). One of the three major modelling programs used by professionals. -> The s3o plugin for 3DS MAX can be found here. NOTE: This is not backwards compatible with versions prior to 7. Also this only exports: '''[http://taspring.clan-sy.com/temp/s3oexport.dle broken link fix if possible]'''
# '''[https://www.lightwave3d.com Lightwave]'''* -> A popular modelling program that's been around a long time. One of the three major modelling programs used by professionals.
# '''[http://www.rhino3d.com/ Rhinoceros]'''* -> Uses a lot of nurbs surfaces.
# '''[http://www.turbosquid.com/gmax GMAX]'''* -> Great for learning as it is 3DS MAX v4 without rendering and has game packs for a fair amount of games. It is locked in exporting however there are a few workarounds.
# '''[http://www.autodesk.com/products/autodesk-maya/overview MAYA]'''* -> The other most widely used and acclaimed modeling program. Used in creation of many games and movies. One of the three major model programs used by professionals.

===3d Model converters/Assemblers===

# '''[[upspring|UpSpring]]'''** -> Help, information, manual and tips can be found here: '''[http://taspring.clan-sy.com/phpbb/viewtopic.php?t=2839&start=0 Forum] -> This is the only other way to get files into the [[About_s3o|s3o]] file format for Spring other then the [[About_s3o|s3o]] plugin for 3DS MAX.
# '''[http://springrts.com/phpbb/viewtopic.php?f=9&t=28156 S3O <-> OBJ Converter]'''

===Sound/Audio Editors and Recorders===

# '''[http://audacity.sourceforge.net/ Audacity]'''** -> Audacity is a free, easy-to-use audio editor and recorder for Windows, Mac OS X, GNU/Linux, and other operating systems.
# '''[http://www.goldwave.com/ GoldWave]'''* -> GoldWave is a commercial digital audio editing software developed by GoldWave Inc for Windows. It was first released to public in April 1993, and is similar to applications like the open source Audacity.
# '''[http://www.sonycreativesoftware.com/products/soundforgefamily.asp Sound Forge]'''* -> The Sound Forge is an digital audio production suite includes everything you need to quickly get from raw audio to finished master. Use this suite to create and edit stereo and multichannel audio files with speed and precision. Efficiently analyze, record and edit audio, digitize and restore old recordings, model acoustic environments, design sound for multimedia, and master replication-ready CDs.
# '''[http://www.speech.kth.se/wavesurfer/ WaveSurfer]'''* -> Wavesurfer is an audio editor widely used for studies of acoustic phonetics. Wavesurfer provides basic audio editing operations, such as excision, copying, pasting, zero-crossing adjustment, and effects such as fading, normalization, echo, inversion, reversal, replacement with silence, and DC-removal, but, in view of its scientific orientation, does not offer effects of interest to musicians such as flange.

=== Scripting And Unit Stats files ===
# '''[http://springfiles.com/spring/tools/scriptor-v1 Scriptor]'''** -> The by far best compiler for your handmade .bos scripts into endless lines of letters and numbers that the TA engine reads. The program is large, easy to operate and with broad error tracing (well, better than the other two alternatives). While other versions of this program sometimes refuse to compile on-off functions, this download is guaranteed to work in every condition.
# '''[http://springfiles.com/spring/tools/cobbler-v4 Cobbler]'''* -> This is a very simple script compiler that converts your newly written .bos files understood by humans into a hexadecimal .cob gibberish used by the TA engine. Beware, however, that this program may fail to compile some perfectly valid scripts and it doesn't always tell where the alleged error lies either. Parts of the program are in French.
# '''[http://springrts.com/phpbb/viewtopic.php?f=9&t=24702&p=460639 Servo]'''* -> Rhad's awesome but somewhat buggy animation scripting program. It features keyframed animation script generation from a 3D positioner.
# '''[https://github.com/Anarchid/blender2lus blender2lus]'''** -> A Blender addon that allows Spring lua unitscripts (for assimp models only) to be authored in Blender, with (almost) all the goodies involved therein.
# '''[http://springrts.com/phpbb/viewtopic.php?f=14&t=25104 Spring Poser by knorke]''' A not-yet-so-usefull gadget-widget-unitscript brewage that allows you to "pose" units by moving & rotating their pieces. It can then save the posed position as a list of Move & Turn commands.
# '''[http://springrts.com/phpbb/viewtopic.php?f=23&t=24499 CEG Browser/Spawn by CarRepairer]''' Spawn particle effects from a menu, ie if you want to reuse effects from another game.
# '''[http://springrts.com/phpbb/viewtopic.php?f=23&t=25847 piece tree widget]''' Print an ascii view of a units piece hierachy. Might be usefull to create notes for scripting.
# '''[http://springrts.com/phpbb/viewtopic.php?f=67&t=23391 bos2lua converter page by CarRepairer]''' Converts .bos scripts to .lua scripts.
# '''[[ToolBox]]''' A game-mutator with some tools for modding. Contains newest version of some of the above scripts plus others.

=== Map Creation ===

# '''[[Maps:SpringMapEdit|SpringMapEdit]]'''** -> Our very own complete map making solution, created by Frostregen.
# '''[http://www.springfiles.com/show_file.php?id=2441 Beherith's mapconv]'''** -> The latest map compiler, supports all features of maps while still retaining backwards compatibility with previous scripts.
# '''[http://taspring.clan-sy.com/phpbb/viewtopic.php?t=2420 SMD Creator]'''** -> Maelstroms SMD creator
# '''[http://www.bundysoft.com/L3DT/ L3DT Large 3D Terrain Generator]'''** -> Commercial Map Maker, standard version is free, but pro version requires payment but includes all the tools required to make an SD7 Spring map from scratch.
# '''[http://code.google.com/p/conflictterra/wiki/MapsAndRocks#Coordinate_Helper_Widget Coordinate helper widget]''' Need to find lots of coordinates, for example to position units? Log the coordinates into a file just by placing markers, no more pen&paper!
# '''[http://www.world-machine.com/ World Machine]''' Commercial terrain generation software, can output height and diffuse textures.
# '''[http://en.wikipedia.org/wiki/Bryce_(software) Bryce3D]''' Shareware terrain generation software.
# '''[http://en.wikipedia.org/wiki/Carrara_(software) Carrara]''' Shareware 3D software.

[[Category:Development]]

Lua UnsyncedCtrl

2016-11-26T16:29:41Z

Picassoct: /* Sun */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

<div class="note">
NOTE: Prior to 102.0, entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users [[springrc]], if you want to use them in unsynced LuaRules/LuaGaia. It is enabled by default in previous versions and removed in 102.0 so you generally don't need to care.</div>

= UI =
'''Spring.SetLastMessagePosition'''
( number x, number y, number z ) -> nil

= Ingame Console =
'''Spring.Echo'''
( arg1 [, arg2 [, ... ] ] ) -> nil

Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.

'''Spring.Log'''
( string section, int logLevel | string logLevel,
arg2 [, arg3 [, ... ] ] ) -> nil

Possible values for logLevel are:
"debug" | LOG.DEBUG
"info" | LOG.INFO
"notice" | LOG.NOTICE (engine default) {{new|97}}
"warning" | LOG.WARNING
"error" | LOG.ERROR
"fatal" | LOG.FATAL

'''Spring.SendCommands''' (needs ModUICtrl)
( string command1 [, string command2 [ ... ] ] ) -> nil
( {string command1, string command2, ...} ) -> nil

== GUI ==
'''Spring.SetActiveCommand''' (needs ModUICtrl)
( string action [, string actionExtra ] ) -> nil | boolean
( number cmdIndex [, number button = 1
[, boolean leftClick, boolean rightClick,
boolean alt, boolean ctrl, boolean meta, boolean shift]] ) -> nil | boolean
'''Spring.LoadCmdColorsConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.LoadCtrlPanelConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.ForceLayoutUpdate''' (needs ModUICtrl)
( ) -> nil
'''Spring.SetDrawSelectionInfo''' disables the "Selected Units x" box in the GUI (needs ModUICtrl)
( boolean enable ) -> nil

== Mouse ==
'''Spring.SetMouseCursor''' (needs ModUICtrl)
( string cursorName [, number scale ] ) -> nil
'''Spring.WarpMouse''' (needs ModUICtrl)
( number x, number y ) -> nil

== LOS Colors ==
'''Spring.SetLosViewColors''' (needs ModUICtrl)

New arguments since 100.0 (radar2 is the inside of radar edge):
( always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b}) -> nil

Arguments for 99.0 and before:
( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil

== SendMessage ==
'''Spring.SendMessage'''
( string "message" ) -> nil
'''Spring.SendMessageToPlayer'''
( number playerID, string "message" ) -> nil
'''Spring.SendMessageToTeam'''
( number teamID, string "message" ) -> nil
'''Spring.SendMessageToAllyTeam'''
( number allyID, string "message" ) -> nil
'''Spring.SendMessageToSpectators'''
( string "message" ) -> nil
Funfact:
<PLAYER#> (with # being a playerid) inside the string will be replaced with the players name.
ie
Spring.SendMessage ("<PLAYER1> did something")
might display as "ProRusher did something"

== Markers ==
'''Spring.MarkerAddPoint''' (needs ModUICtrl)
( number x, number y, number z [, string text = "" [, bool localOnly] ] ) -> nil
'''Spring.MarkerAddLine''' (needs ModUICtrl)
( number x1, number y1, number z1, number x2, number y2, number z2 ) -> nil
'''Spring.MarkerErasePosition''' (needs ModUICtrl)
( number x, number y, number z ) -> nil

= Sounds =
'''Spring.LoadSoundDef'''
( string "soundfile" ) -> nil | boolean success
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.

'''Spring.PlaySoundFile''' Plays WAV or OGG sounds.
( string "soundfile" [, number volume = 1.0
[, number posx, number posy, number posz
[, number speedx, number speedy, number speedz ] ] ], [string/number channel ] ) -> nil | boolean
`channel` is new in Spring0.83, and can be one of those:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3


'''Spring.PlaySoundStream'''
( string "oggfile" [, number volume = 1.0
[, bool enqueue ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream currently running.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

'''Spring.SendLuaUIMsg''' (needs ModUICtrl)
( string message, string mode ) -> nil
possible modes are: "s"/"specs" & "a"/"allies"
'''Spring.SendLuaGaiaMsg''' (needs ModUICtrl)
( string message ) -> nil
'''Spring.SendLuaRulesMsg''' (needs ModUICtrl)
( string message ) -> nil

= AI =
'''Spring.SendSkirmishAIMessage''' {{new|83.0}}
( number aiTeam, string message )
-> nil | boolean ai_processed, { [1] = string response1, etc... }
Note there is nothing in this table due to "limitations" of the AI interface.

= Units =
'''Spring.SetUnitLeaveTracks''' {{new|83.0}}
( number unitID, boolean leavetracks ) -> nil

== Unit Selection ==
'''Spring.SelectUnitMap'''
( { [unitID] = anything, ...} [,boolean append] ) -> nil
'''Spring.SelectUnitArray'''
( { [1] = unitID1 , [2] = unitID2 , ...} [,boolean append] ) -> nil

'''Spring.SetDrawSelectionInfo'''
( boolean drawSelectionInfo ) -> nil

== Unit Group ==
'''Spring.SetUnitGroup''' (needs ModUICtrl)
( number unitID, number groupID ) -> nil

== Give Order ==
'''Spring.GiveOrder''' gives order to all selected units (needs ModUICtrl)
( number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnit''' (needs ModUICtrl)
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitMap''' (needs ModUICtrl)
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitMap''' (needs ModUICtrl)
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
},
[boolean pairwise]
) -> nil | boolean true

pairwise param ({{new|89.0}}) is used to send multiple units a single individual command

'''Spring.SetBuildFacing'''
( int Facing ) -> nil

'''Spring.SetBuildSpacing'''
( int Spacing ) -> nil

== Unit NoDraw,NoSelect,NoMinimap ==
'''Spring.SetUnitNoDraw''' LuaGadgets only!
( number unitID, boolean noDraw ) -> nil
'''Spring.SetUnitNoSelect''' LuaGadgets only!
( number unitID, boolean noSelect ) -> nil
'''Spring.SetUnitNoMinimap''' LuaGadgets only!
( number unitID, boolean noMinimap ) -> nil

= Features =
'''Spring.SetFeatureFade''' {{new|101.0}}
( int featureID, bool allow ) -> nil
Control whether a feature will fade or not when zoomed out.

'''Spring.SetFeatureNoDraw''' LuaGadgets only!
( number featureID, boolean noDraw ) -> nil

= Developers =
'''Spring.SetDrawSky'''
( boolean drawSky ) -> nil
'''Spring.SetDrawWater'''
( boolean drawWater ) -> nil
'''Spring.SetDrawGround'''
( boolean drawGround ) -> nil

'''Spring.SetWaterParams''' needs cheating enabled!
( table params ) -> nil
Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your [[springrc]] to 1, then you don't even need to restart BumpWater via `/water 4`. 
`params` table may contain:
params = {
absorb = {number r, number g, number b},
baseColor = {number r, number g, number b},
minColor = {number r, number g, number b},
surfaceColor = {number r, number g, number b},
diffuseColor = {number r, number g, number b},
specularColor = {number r, number g, number b},
planeColor = {number r, number g, number b},
texture = string file,
foamTexture = string file,
normalTexture = string file,
damage = number value,
repeatX = number value,
repeatY = number value,
surfaceAlpha = number value,
ambientFactor = number value,
diffuseFactor = number value,
specularFactor = number value,
specularPower = number value,
fresnelMin = number value,
fresnelMax = number value,
fresnelPower = number value,
reflectionDistortion = number value,
blurBase = number value,
blurExponent = number value,
perlinStartFreq = number value,
perlinLacunarity = number value,
perlinAmplitude = number value,
numTiles = number value,
shoreWaves = boolean value,
forceRendering = boolean value,
hasWaterPlane = boolean value,
}

'''Spring.SetLogSectionFilterLevel''' {{New|95.0}}
(string sectionName, string|number logLevel)
see [[infolog.txt]] for possible log sections (?)

'''Spring.SetDrawGroundDeferred''' {{New|95.0}}
( boolean drawGroundDeferred [, boolean drawGroundForward] ) -> nil
{{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass

'''Spring.SetDrawModelsDeferred''' {{New|95.0}}
( boolean drawUnitsDeferred,
boolean drawFeaturesDeferred
[, boolean drawUnitsForward
[, boolean drawFeaturesForward ]]
) -> nil

{{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes

= GUI =
'''Spring.DrawUnitCommands'''
( number unitID ) -> nil
( { [1] = unitID, ... } [, false ] ) -> nil
( { [unitID] = anything, ... }, true ) -> nil

'''Spring.SetTeamColor'''
( number teamID, number r, number g, number b ) -> nil

'''Spring.AssignMouseCursor''' changes/creates the cursor of a single CursorCmd
( string "cmdName", string "iconFileName"
[, boolean overwrite = true [, boolean hotSpotTopLeft = false] ] ) -> nil | boolean
Note, that iconFileName is not the full filename instead it is like this: 
wanted filename: Anims/cursorattack_0.bmp 
=> iconFileName: cursorattack


'''Spring.ReplaceMouseCursor''' mass replace all occurrence of the cursor in all CursorCmds
( string "oldFileName", string "newFileName" [, boolean hotSpotTopLeft = false] ) -> nil | boolean

'''Spring.SetCustomCommandDrawData''' register your custom cmd so it gets visible in the unit's cmd queue
( number cmdID,
number cmdID_cloneIcon | string iconname,
{ number r, number g, number b, number a } [, boolean showArea ] ) -> nil
( number cmdID, nil) -> nil

= Sharing =
'''Spring.SetShareLevel''' note: shareLevel is 0<= x <= 1 (needs ModUICtrl)
( string "metal" | "energy", number shareLevel ) -> nil
'''Spring.ShareResources''' (needs ModUICtrl)
( number teamID, string "units" ) -> nil
( number teamID, string "metal" | "energy", number amount ) -> nil

= UnitDef RadarIcons & BuildPics =
'''Spring.AddUnitIcon'''
( string iconName, string texFile [, number size [, number dist [, boolean radAdjust ]]] )
-> nil | boolean
'''Spring.FreeUnitIcon'''
( string iconName ) -> nil | boolean
'''Spring.SetUnitDefIcon''' (RadarIcon) (needs ModUICtrl)
( number unitDefID, string iconName ) -> nil
'''Spring.SetUnitDefImage''' (BuildPic) (needs ModUICtrl)
( number unitDefID, luaTexture | string texFile ) -> nil

= Camera =
'''Spring.SetCameraState'''
( table camState, number camTime) -> nil | boolean
camState has the same format as the output of Spring.GetCameraState(). See [[Lua_camState]] for details about camState.

The camState's mode/name must fit the rest of the state. Getting a state, changing its mode/name and then passing it to SetCameraState will have undesired results. [https://springrts.com/mantis/view.php?id=5028#c15491 Also see #5028]

'''Spring.SetCameraTarget'''
( number x, number y, number z [,number transTime] ) -> nil
For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

'''Spring.SetCameraOffset''' (needs ModUICtrl)
( [number px = 0 [, number py = 0 [, number pz = 0
[, number tx = 0 [, number ty = 0 [, number tz = 0]]]]]] ) -> nil

= (Virtual-)FileSystem =
'''Spring.ExtractModArchiveFile'''
( string modfile ) -> boolean
'''Spring.CreateDir''' (needs ModUICtrl)
( number path ) -> nil | boolean

The full VFS API is available at [[Lua_VFS|link]].

= Engine Config =
The following functions read the engine configs saved in [[springrc]], a version-ed instance of these or a custom file supplied on the command line.
If ''*Overlay'' is ''true'', the value will only be set in memory, and not be restored for the next game

'''Spring.GetConfigInt''' (needs ModUICtrl)
( string name [, number default [, boolean setInOverlay = false]] ) -> nil | number
'''Spring.SetConfigInt''' (needs ModUICtrl)
( string name, number value [, boolean useOverlay = false] ) -> nil
'''Spring.GetConfigString''' (needs ModUICtrl)
( string name [, string default [, boolean setInOverlay = false]] ) -> nil | string
'''Spring.SetConfigString''' (needs ModUICtrl)
( string name, string value [, boolean useOverlay = false] ) -> nil

= World Primitives =
outdated! use opengl api instead!

'''Spring.AddWorldIcon'''
( number cmdID, number x, number y, number z ) -> nil
'''Spring.AddWorldText'''
( string "text", number x, number y, number z ) -> nil
'''Spring.AddWorldUnit'''
( number unitDefID,
number x, number y, number z,
number team, number facing) -> nil

= Sun =
The dynamic Sun must be invoked via /dynamicsun.

'''Spring.SetSunManualControl'''
( boolean setManualControl ) - > nil

'''Spring.SetSunParameters'''
( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

'''Spring.SetSunDirection'''
( number dirX, number dirY, number dirZ ) -> nil

'''Spring.SetSunLighting''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following sun lighting parameters:
{ground,unit}{Ambient,Diffuse,Specular}Color and specularExponent
All Colourvalues have to in the Range from 0.0 to 255.0 for all colors and the alpha
Example usage: Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })


'''Spring.SetAtmosphere''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following atmosphere parameters:
fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})


= Misc =

'''Spring.Reload''' {{new|99.0}}
( string startscript )
start-script is the CONTENT of the [[script.txt]] spring should use to start.

'''Spring.Restart''' {{new|0.79}}
( string commandline_args, string startscript )
-> if this call returns, something went wrong
''commandline_args'' are commandline arguments passed to spring executable

start-script is the CONTENT of the [[script.txt]] spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to ''commandline_args''

'''Spring.SetWMIcon''' {{new|83.0}}
( string iconFileName ) -> nil
Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo). 
Note: has to be 24bit or 32bit 
Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) 
Note: ''*.bmp'' images have to be in BGR format (default for m$ ones). 
Note: ''*.ico'' images are not supported.

'''Spring.SetWMCaption''' {{new|83.0}}
( string title [, string titleShort = title ] ) -> nil

Sets the window ''title'' for the process (default: "Spring <version>").

The ''shortTitle'' is displayed in the OS task-bar (default: "Spring <version>").

'''NOTE:''' ''shortTitle'' is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. See [http://www.gpwiki.org/index.php/SDL:Tutorials:Initializing_SDL_Libraries#About_the_icon_.28.22Icon_Title.22.29_parameter_on_different_window-managers this site] for more details.

'''Spring.ClearWatchdogTimer''' {{new|83.0}}
( [ string threadName = main ] ) -> nil

'''Spring.SetClipboard''' {{new|98.0}}
( string text) -> nil

= Rendering =
== Preload ==
Allow the engine to load the unit's model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.

'''Spring.PreloadUnitDefModel''' {{new|101.0}}
( number unitDefID ) -> nil

'''Spring.PreloadFetureDefModel''' {{new|101.0}}
( number featureDefID ) -> nil

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

'''Spring.AddMapLight''' (requires MaxDynamicMapLights > 0)
(table lightParams) -> number lightHandle
'''Spring.AddModelLight''' (requires MaxDynamicModelLights > 0)
(table lightParams) -> number lightHandle

'''Spring.UpdateMapLight'''
(number lightHandle, table lightParams) -> boolean success
'''Spring.UpdateModelLight'''
(number lightHandle, table lightParams) -> boolean success

'''Spring.SetMapLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success
'''Spring.SetModelLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success

'''lightParams''' is a table that should contain at least one of the following recognized key/value pairs:

lightParams = {
position = {px, py, pz},
direction = {dx, dy, dz},
ambientColor = {red, green, blue},
diffuseColor = {red, green, blue},
specularColor = {red, green, blue},
intensityWeight = {ambientWeight, diffuseWeight, specularWeight},

-- per-frame decay of ambientColor (spread over TTL frames)
ambientDecayRate = {ambientRedDecay, ambientGreenDecay, ambientBlueDecay},
-- per-frame decay of diffuseColor (spread over TTL frames)
diffuseDecayRate = {diffuseRedDecay, diffuseGreenDecay, diffuseBlueDecay},
-- per-frame decay of specularColor (spread over TTL frames)
specularDecayRate = {specularRedDecay, specularGreenDecay, specularBlueDecay},
-- *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
decayFunctionType = {ambientDecayType, diffuseDecayType, specularDecayType},

radius = number elmos,
fov = number degrees,
ttl = number frames,
priority = number,
ignoreLOS = boolean,
}

= Map =
'''Spring.SetSkyBoxTexture''' {{new|101.0}}
( string texName ) -> nil

'''Spring.SetMapShadingTexture''' {{new|101.0}}
( string texType, string texName ) -> boolean success

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

'''Spring.SetMapSquareTexture'''
( number texSqrX, number texSqrY, string luaTexName ) -> boolean success

'''Spring.SetMapShader''' {{101.0}}
( number standardShaderID, number deferredShaderID ) -> nil

<div class="note">The ID's must refer to valid programs returned by gl.CreateShader. Passing in a value of 0 will cause the respective shader to revert back to its engine default. Custom map shaders that declare a uniform ivec2 named "texSquare" can sample from the default diffuse texture(s), which are always bound to TU 0.</div>

[[category: Lua]]

Lua UnsyncedCtrl

2016-11-26T12:34:11Z

Picassoct: /* Sun */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

<div class="note">
NOTE: Prior to 102.0, entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users [[springrc]], if you want to use them in unsynced LuaRules/LuaGaia. It is enabled by default in previous versions and removed in 102.0 so you generally don't need to care.</div>

= UI =
'''Spring.SetLastMessagePosition'''
( number x, number y, number z ) -> nil

= Ingame Console =
'''Spring.Echo'''
( arg1 [, arg2 [, ... ] ] ) -> nil

Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.

'''Spring.Log'''
( string section, int logLevel | string logLevel,
arg2 [, arg3 [, ... ] ] ) -> nil

Possible values for logLevel are:
"debug" | LOG.DEBUG
"info" | LOG.INFO
"notice" | LOG.NOTICE (engine default) {{new|97}}
"warning" | LOG.WARNING
"error" | LOG.ERROR
"fatal" | LOG.FATAL

'''Spring.SendCommands''' (needs ModUICtrl)
( string command1 [, string command2 [ ... ] ] ) -> nil
( {string command1, string command2, ...} ) -> nil

== GUI ==
'''Spring.SetActiveCommand''' (needs ModUICtrl)
( string action [, string actionExtra ] ) -> nil | boolean
( number cmdIndex [, number button = 1
[, boolean leftClick, boolean rightClick,
boolean alt, boolean ctrl, boolean meta, boolean shift]] ) -> nil | boolean
'''Spring.LoadCmdColorsConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.LoadCtrlPanelConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.ForceLayoutUpdate''' (needs ModUICtrl)
( ) -> nil
'''Spring.SetDrawSelectionInfo''' disables the "Selected Units x" box in the GUI (needs ModUICtrl)
( boolean enable ) -> nil

== Mouse ==
'''Spring.SetMouseCursor''' (needs ModUICtrl)
( string cursorName [, number scale ] ) -> nil
'''Spring.WarpMouse''' (needs ModUICtrl)
( number x, number y ) -> nil

== LOS Colors ==
'''Spring.SetLosViewColors''' (needs ModUICtrl)

New arguments since 100.0 (radar2 is the inside of radar edge):
( always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b}) -> nil

Arguments for 99.0 and before:
( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil

== SendMessage ==
'''Spring.SendMessage'''
( string "message" ) -> nil
'''Spring.SendMessageToPlayer'''
( number playerID, string "message" ) -> nil
'''Spring.SendMessageToTeam'''
( number teamID, string "message" ) -> nil
'''Spring.SendMessageToAllyTeam'''
( number allyID, string "message" ) -> nil
'''Spring.SendMessageToSpectators'''
( string "message" ) -> nil
Funfact:
<PLAYER#> (with # being a playerid) inside the string will be replaced with the players name.
ie
Spring.SendMessage ("<PLAYER1> did something")
might display as "ProRusher did something"

== Markers ==
'''Spring.MarkerAddPoint''' (needs ModUICtrl)
( number x, number y, number z [, string text = "" [, bool localOnly] ] ) -> nil
'''Spring.MarkerAddLine''' (needs ModUICtrl)
( number x1, number y1, number z1, number x2, number y2, number z2 ) -> nil
'''Spring.MarkerErasePosition''' (needs ModUICtrl)
( number x, number y, number z ) -> nil

= Sounds =
'''Spring.LoadSoundDef'''
( string "soundfile" ) -> nil | boolean success
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.

'''Spring.PlaySoundFile''' Plays WAV or OGG sounds.
( string "soundfile" [, number volume = 1.0
[, number posx, number posy, number posz
[, number speedx, number speedy, number speedz ] ] ], [string/number channel ] ) -> nil | boolean
`channel` is new in Spring0.83, and can be one of those:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3


'''Spring.PlaySoundStream'''
( string "oggfile" [, number volume = 1.0
[, bool enqueue ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream currently running.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

'''Spring.SendLuaUIMsg''' (needs ModUICtrl)
( string message, string mode ) -> nil
possible modes are: "s"/"specs" & "a"/"allies"
'''Spring.SendLuaGaiaMsg''' (needs ModUICtrl)
( string message ) -> nil
'''Spring.SendLuaRulesMsg''' (needs ModUICtrl)
( string message ) -> nil

= AI =
'''Spring.SendSkirmishAIMessage''' {{new|83.0}}
( number aiTeam, string message )
-> nil | boolean ai_processed, { [1] = string response1, etc... }
Note there is nothing in this table due to "limitations" of the AI interface.

= Units =
'''Spring.SetUnitLeaveTracks''' {{new|83.0}}
( number unitID, boolean leavetracks ) -> nil

== Unit Selection ==
'''Spring.SelectUnitMap'''
( { [unitID] = anything, ...} [,boolean append] ) -> nil
'''Spring.SelectUnitArray'''
( { [1] = unitID1 , [2] = unitID2 , ...} [,boolean append] ) -> nil

'''Spring.SetDrawSelectionInfo'''
( boolean drawSelectionInfo ) -> nil

== Unit Group ==
'''Spring.SetUnitGroup''' (needs ModUICtrl)
( number unitID, number groupID ) -> nil

== Give Order ==
'''Spring.GiveOrder''' gives order to all selected units (needs ModUICtrl)
( number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnit''' (needs ModUICtrl)
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitMap''' (needs ModUICtrl)
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitMap''' (needs ModUICtrl)
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
},
[boolean pairwise]
) -> nil | boolean true

pairwise param ({{new|89.0}}) is used to send multiple units a single individual command

'''Spring.SetBuildFacing'''
( int Facing ) -> nil

'''Spring.SetBuildSpacing'''
( int Spacing ) -> nil

== Unit NoDraw,NoSelect,NoMinimap ==
'''Spring.SetUnitNoDraw''' LuaGadgets only!
( number unitID, boolean noDraw ) -> nil
'''Spring.SetUnitNoSelect''' LuaGadgets only!
( number unitID, boolean noSelect ) -> nil
'''Spring.SetUnitNoMinimap''' LuaGadgets only!
( number unitID, boolean noMinimap ) -> nil

= Features =
'''Spring.SetFeatureFade''' {{new|101.0}}
( int featureID, bool allow ) -> nil
Control whether a feature will fade or not when zoomed out.

'''Spring.SetFeatureNoDraw''' LuaGadgets only!
( number featureID, boolean noDraw ) -> nil

= Developers =
'''Spring.SetDrawSky'''
( boolean drawSky ) -> nil
'''Spring.SetDrawWater'''
( boolean drawWater ) -> nil
'''Spring.SetDrawGround'''
( boolean drawGround ) -> nil

'''Spring.SetWaterParams''' needs cheating enabled!
( table params ) -> nil
Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your [[springrc]] to 1, then you don't even need to restart BumpWater via `/water 4`. 
`params` table may contain:
params = {
absorb = {number r, number g, number b},
baseColor = {number r, number g, number b},
minColor = {number r, number g, number b},
surfaceColor = {number r, number g, number b},
diffuseColor = {number r, number g, number b},
specularColor = {number r, number g, number b},
planeColor = {number r, number g, number b},
texture = string file,
foamTexture = string file,
normalTexture = string file,
damage = number value,
repeatX = number value,
repeatY = number value,
surfaceAlpha = number value,
ambientFactor = number value,
diffuseFactor = number value,
specularFactor = number value,
specularPower = number value,
fresnelMin = number value,
fresnelMax = number value,
fresnelPower = number value,
reflectionDistortion = number value,
blurBase = number value,
blurExponent = number value,
perlinStartFreq = number value,
perlinLacunarity = number value,
perlinAmplitude = number value,
numTiles = number value,
shoreWaves = boolean value,
forceRendering = boolean value,
hasWaterPlane = boolean value,
}

'''Spring.SetLogSectionFilterLevel''' {{New|95.0}}
(string sectionName, string|number logLevel)
see [[infolog.txt]] for possible log sections (?)

'''Spring.SetDrawGroundDeferred''' {{New|95.0}}
( boolean drawGroundDeferred [, boolean drawGroundForward] ) -> nil
{{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass

'''Spring.SetDrawModelsDeferred''' {{New|95.0}}
( boolean drawUnitsDeferred,
boolean drawFeaturesDeferred
[, boolean drawUnitsForward
[, boolean drawFeaturesForward ]]
) -> nil

{{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes

= GUI =
'''Spring.DrawUnitCommands'''
( number unitID ) -> nil
( { [1] = unitID, ... } [, false ] ) -> nil
( { [unitID] = anything, ... }, true ) -> nil

'''Spring.SetTeamColor'''
( number teamID, number r, number g, number b ) -> nil

'''Spring.AssignMouseCursor''' changes/creates the cursor of a single CursorCmd
( string "cmdName", string "iconFileName"
[, boolean overwrite = true [, boolean hotSpotTopLeft = false] ] ) -> nil | boolean
Note, that iconFileName is not the full filename instead it is like this: 
wanted filename: Anims/cursorattack_0.bmp 
=> iconFileName: cursorattack


'''Spring.ReplaceMouseCursor''' mass replace all occurrence of the cursor in all CursorCmds
( string "oldFileName", string "newFileName" [, boolean hotSpotTopLeft = false] ) -> nil | boolean

'''Spring.SetCustomCommandDrawData''' register your custom cmd so it gets visible in the unit's cmd queue
( number cmdID,
number cmdID_cloneIcon | string iconname,
{ number r, number g, number b, number a } [, boolean showArea ] ) -> nil
( number cmdID, nil) -> nil

= Sharing =
'''Spring.SetShareLevel''' note: shareLevel is 0<= x <= 1 (needs ModUICtrl)
( string "metal" | "energy", number shareLevel ) -> nil
'''Spring.ShareResources''' (needs ModUICtrl)
( number teamID, string "units" ) -> nil
( number teamID, string "metal" | "energy", number amount ) -> nil

= UnitDef RadarIcons & BuildPics =
'''Spring.AddUnitIcon'''
( string iconName, string texFile [, number size [, number dist [, boolean radAdjust ]]] )
-> nil | boolean
'''Spring.FreeUnitIcon'''
( string iconName ) -> nil | boolean
'''Spring.SetUnitDefIcon''' (RadarIcon) (needs ModUICtrl)
( number unitDefID, string iconName ) -> nil
'''Spring.SetUnitDefImage''' (BuildPic) (needs ModUICtrl)
( number unitDefID, luaTexture | string texFile ) -> nil

= Camera =
'''Spring.SetCameraState'''
( table camState, number camTime) -> nil | boolean
camState has the same format as the output of Spring.GetCameraState(). See [[Lua_camState]] for details about camState.

The camState's mode/name must fit the rest of the state. Getting a state, changing its mode/name and then passing it to SetCameraState will have undesired results. [https://springrts.com/mantis/view.php?id=5028#c15491 Also see #5028]

'''Spring.SetCameraTarget'''
( number x, number y, number z [,number transTime] ) -> nil
For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

'''Spring.SetCameraOffset''' (needs ModUICtrl)
( [number px = 0 [, number py = 0 [, number pz = 0
[, number tx = 0 [, number ty = 0 [, number tz = 0]]]]]] ) -> nil

= (Virtual-)FileSystem =
'''Spring.ExtractModArchiveFile'''
( string modfile ) -> boolean
'''Spring.CreateDir''' (needs ModUICtrl)
( number path ) -> nil | boolean

The full VFS API is available at [[Lua_VFS|link]].

= Engine Config =
The following functions read the engine configs saved in [[springrc]], a version-ed instance of these or a custom file supplied on the command line.
If ''*Overlay'' is ''true'', the value will only be set in memory, and not be restored for the next game

'''Spring.GetConfigInt''' (needs ModUICtrl)
( string name [, number default [, boolean setInOverlay = false]] ) -> nil | number
'''Spring.SetConfigInt''' (needs ModUICtrl)
( string name, number value [, boolean useOverlay = false] ) -> nil
'''Spring.GetConfigString''' (needs ModUICtrl)
( string name [, string default [, boolean setInOverlay = false]] ) -> nil | string
'''Spring.SetConfigString''' (needs ModUICtrl)
( string name, string value [, boolean useOverlay = false] ) -> nil

= World Primitives =
outdated! use opengl api instead!

'''Spring.AddWorldIcon'''
( number cmdID, number x, number y, number z ) -> nil
'''Spring.AddWorldText'''
( string "text", number x, number y, number z ) -> nil
'''Spring.AddWorldUnit'''
( number unitDefID,
number x, number y, number z,
number team, number facing) -> nil

= Sun =
The dynamic Sun must be invoked via /dynamicsun.

'''Spring.SetSunManualControl'''
( boolean setManualControl ) - > nil

'''Spring.SetSunParameters'''
( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

'''Spring.SetSunDirection'''
( number dirX, number dirY, number dirZ ) -> nil

'''Spring.SetSunLighting''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following sun lighting parameters:
{ground,unit}{Ambient,Diffuse,Specular}Color and specularExponent
All Colourvalues have to in the Range from 0.0 to 1.0
Example usage: Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })


'''Spring.SetAtmosphere''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following atmosphere parameters:
fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})


= Misc =

'''Spring.Reload''' {{new|99.0}}
( string startscript )
start-script is the CONTENT of the [[script.txt]] spring should use to start.

'''Spring.Restart''' {{new|0.79}}
( string commandline_args, string startscript )
-> if this call returns, something went wrong
''commandline_args'' are commandline arguments passed to spring executable

start-script is the CONTENT of the [[script.txt]] spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to ''commandline_args''

'''Spring.SetWMIcon''' {{new|83.0}}
( string iconFileName ) -> nil
Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo). 
Note: has to be 24bit or 32bit 
Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) 
Note: ''*.bmp'' images have to be in BGR format (default for m$ ones). 
Note: ''*.ico'' images are not supported.

'''Spring.SetWMCaption''' {{new|83.0}}
( string title [, string titleShort = title ] ) -> nil

Sets the window ''title'' for the process (default: "Spring <version>").

The ''shortTitle'' is displayed in the OS task-bar (default: "Spring <version>").

'''NOTE:''' ''shortTitle'' is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. See [http://www.gpwiki.org/index.php/SDL:Tutorials:Initializing_SDL_Libraries#About_the_icon_.28.22Icon_Title.22.29_parameter_on_different_window-managers this site] for more details.

'''Spring.ClearWatchdogTimer''' {{new|83.0}}
( [ string threadName = main ] ) -> nil

'''Spring.SetClipboard''' {{new|98.0}}
( string text) -> nil

= Rendering =
== Preload ==
Allow the engine to load the unit's model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.

'''Spring.PreloadUnitDefModel''' {{new|101.0}}
( number unitDefID ) -> nil

'''Spring.PreloadFetureDefModel''' {{new|101.0}}
( number featureDefID ) -> nil

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

'''Spring.AddMapLight''' (requires MaxDynamicMapLights > 0)
(table lightParams) -> number lightHandle
'''Spring.AddModelLight''' (requires MaxDynamicModelLights > 0)
(table lightParams) -> number lightHandle

'''Spring.UpdateMapLight'''
(number lightHandle, table lightParams) -> boolean success
'''Spring.UpdateModelLight'''
(number lightHandle, table lightParams) -> boolean success

'''Spring.SetMapLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success
'''Spring.SetModelLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success

'''lightParams''' is a table that should contain at least one of the following recognized key/value pairs:

lightParams = {
position = {px, py, pz},
direction = {dx, dy, dz},
ambientColor = {red, green, blue},
diffuseColor = {red, green, blue},
specularColor = {red, green, blue},
intensityWeight = {ambientWeight, diffuseWeight, specularWeight},

-- per-frame decay of ambientColor (spread over TTL frames)
ambientDecayRate = {ambientRedDecay, ambientGreenDecay, ambientBlueDecay},
-- per-frame decay of diffuseColor (spread over TTL frames)
diffuseDecayRate = {diffuseRedDecay, diffuseGreenDecay, diffuseBlueDecay},
-- per-frame decay of specularColor (spread over TTL frames)
specularDecayRate = {specularRedDecay, specularGreenDecay, specularBlueDecay},
-- *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
decayFunctionType = {ambientDecayType, diffuseDecayType, specularDecayType},

radius = number elmos,
fov = number degrees,
ttl = number frames,
priority = number,
ignoreLOS = boolean,
}

= Map =
'''Spring.SetSkyBoxTexture''' {{new|101.0}}
( string texName ) -> nil

'''Spring.SetMapShadingTexture''' {{new|101.0}}
( string texType, string texName ) -> boolean success

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

'''Spring.SetMapSquareTexture'''
( number texSqrX, number texSqrY, string luaTexName ) -> boolean success

'''Spring.SetMapShader''' {{101.0}}
( number standardShaderID, number deferredShaderID ) -> nil

<div class="note">The ID's must refer to valid programs returned by gl.CreateShader. Passing in a value of 0 will cause the respective shader to revert back to its engine default. Custom map shaders that declare a uniform ivec2 named "texSquare" can sample from the default diffuse texture(s), which are always bound to TU 0.</div>

[[category: Lua]]

Lua UnsyncedCtrl

2016-11-25T23:13:29Z

Picassoct: /* Sun */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

<div class="note">
NOTE: Prior to 102.0, entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users [[springrc]], if you want to use them in unsynced LuaRules/LuaGaia. It is enabled by default in previous versions and removed in 102.0 so you generally don't need to care.</div>

= UI =
'''Spring.SetLastMessagePosition'''
( number x, number y, number z ) -> nil

= Ingame Console =
'''Spring.Echo'''
( arg1 [, arg2 [, ... ] ] ) -> nil

Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.

'''Spring.Log'''
( string section, int logLevel | string logLevel,
arg2 [, arg3 [, ... ] ] ) -> nil

Possible values for logLevel are:
"debug" | LOG.DEBUG
"info" | LOG.INFO
"notice" | LOG.NOTICE (engine default) {{new|97}}
"warning" | LOG.WARNING
"error" | LOG.ERROR
"fatal" | LOG.FATAL

'''Spring.SendCommands''' (needs ModUICtrl)
( string command1 [, string command2 [ ... ] ] ) -> nil
( {string command1, string command2, ...} ) -> nil

== GUI ==
'''Spring.SetActiveCommand''' (needs ModUICtrl)
( string action [, string actionExtra ] ) -> nil | boolean
( number cmdIndex [, number button = 1
[, boolean leftClick, boolean rightClick,
boolean alt, boolean ctrl, boolean meta, boolean shift]] ) -> nil | boolean
'''Spring.LoadCmdColorsConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.LoadCtrlPanelConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.ForceLayoutUpdate''' (needs ModUICtrl)
( ) -> nil
'''Spring.SetDrawSelectionInfo''' disables the "Selected Units x" box in the GUI (needs ModUICtrl)
( boolean enable ) -> nil

== Mouse ==
'''Spring.SetMouseCursor''' (needs ModUICtrl)
( string cursorName [, number scale ] ) -> nil
'''Spring.WarpMouse''' (needs ModUICtrl)
( number x, number y ) -> nil

== LOS Colors ==
'''Spring.SetLosViewColors''' (needs ModUICtrl)

New arguments since 100.0 (radar2 is the inside of radar edge):
( always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b}) -> nil

Arguments for 99.0 and before:
( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil

== SendMessage ==
'''Spring.SendMessage'''
( string "message" ) -> nil
'''Spring.SendMessageToPlayer'''
( number playerID, string "message" ) -> nil
'''Spring.SendMessageToTeam'''
( number teamID, string "message" ) -> nil
'''Spring.SendMessageToAllyTeam'''
( number allyID, string "message" ) -> nil
'''Spring.SendMessageToSpectators'''
( string "message" ) -> nil
Funfact:
<PLAYER#> (with # being a playerid) inside the string will be replaced with the players name.
ie
Spring.SendMessage ("<PLAYER1> did something")
might display as "ProRusher did something"

== Markers ==
'''Spring.MarkerAddPoint''' (needs ModUICtrl)
( number x, number y, number z [, string text = "" [, bool localOnly] ] ) -> nil
'''Spring.MarkerAddLine''' (needs ModUICtrl)
( number x1, number y1, number z1, number x2, number y2, number z2 ) -> nil
'''Spring.MarkerErasePosition''' (needs ModUICtrl)
( number x, number y, number z ) -> nil

= Sounds =
'''Spring.LoadSoundDef'''
( string "soundfile" ) -> nil | boolean success
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.

'''Spring.PlaySoundFile''' Plays WAV or OGG sounds.
( string "soundfile" [, number volume = 1.0
[, number posx, number posy, number posz
[, number speedx, number speedy, number speedz ] ] ], [string/number channel ] ) -> nil | boolean
`channel` is new in Spring0.83, and can be one of those:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3


'''Spring.PlaySoundStream'''
( string "oggfile" [, number volume = 1.0
[, bool enqueue ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream currently running.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

'''Spring.SendLuaUIMsg''' (needs ModUICtrl)
( string message, string mode ) -> nil
possible modes are: "s"/"specs" & "a"/"allies"
'''Spring.SendLuaGaiaMsg''' (needs ModUICtrl)
( string message ) -> nil
'''Spring.SendLuaRulesMsg''' (needs ModUICtrl)
( string message ) -> nil

= AI =
'''Spring.SendSkirmishAIMessage''' {{new|83.0}}
( number aiTeam, string message )
-> nil | boolean ai_processed, { [1] = string response1, etc... }
Note there is nothing in this table due to "limitations" of the AI interface.

= Units =
'''Spring.SetUnitLeaveTracks''' {{new|83.0}}
( number unitID, boolean leavetracks ) -> nil

== Unit Selection ==
'''Spring.SelectUnitMap'''
( { [unitID] = anything, ...} [,boolean append] ) -> nil
'''Spring.SelectUnitArray'''
( { [1] = unitID1 , [2] = unitID2 , ...} [,boolean append] ) -> nil

'''Spring.SetDrawSelectionInfo'''
( boolean drawSelectionInfo ) -> nil

== Unit Group ==
'''Spring.SetUnitGroup''' (needs ModUICtrl)
( number unitID, number groupID ) -> nil

== Give Order ==
'''Spring.GiveOrder''' gives order to all selected units (needs ModUICtrl)
( number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnit''' (needs ModUICtrl)
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitMap''' (needs ModUICtrl)
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitMap''' (needs ModUICtrl)
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
},
[boolean pairwise]
) -> nil | boolean true

pairwise param ({{new|89.0}}) is used to send multiple units a single individual command

'''Spring.SetBuildFacing'''
( int Facing ) -> nil

'''Spring.SetBuildSpacing'''
( int Spacing ) -> nil

== Unit NoDraw,NoSelect,NoMinimap ==
'''Spring.SetUnitNoDraw''' LuaGadgets only!
( number unitID, boolean noDraw ) -> nil
'''Spring.SetUnitNoSelect''' LuaGadgets only!
( number unitID, boolean noSelect ) -> nil
'''Spring.SetUnitNoMinimap''' LuaGadgets only!
( number unitID, boolean noMinimap ) -> nil

= Features =
'''Spring.SetFeatureFade''' {{new|101.0}}
( int featureID, bool allow ) -> nil
Control whether a feature will fade or not when zoomed out.

'''Spring.SetFeatureNoDraw''' LuaGadgets only!
( number featureID, boolean noDraw ) -> nil

= Developers =
'''Spring.SetDrawSky'''
( boolean drawSky ) -> nil
'''Spring.SetDrawWater'''
( boolean drawWater ) -> nil
'''Spring.SetDrawGround'''
( boolean drawGround ) -> nil

'''Spring.SetWaterParams''' needs cheating enabled!
( table params ) -> nil
Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your [[springrc]] to 1, then you don't even need to restart BumpWater via `/water 4`. 
`params` table may contain:
params = {
absorb = {number r, number g, number b},
baseColor = {number r, number g, number b},
minColor = {number r, number g, number b},
surfaceColor = {number r, number g, number b},
diffuseColor = {number r, number g, number b},
specularColor = {number r, number g, number b},
planeColor = {number r, number g, number b},
texture = string file,
foamTexture = string file,
normalTexture = string file,
damage = number value,
repeatX = number value,
repeatY = number value,
surfaceAlpha = number value,
ambientFactor = number value,
diffuseFactor = number value,
specularFactor = number value,
specularPower = number value,
fresnelMin = number value,
fresnelMax = number value,
fresnelPower = number value,
reflectionDistortion = number value,
blurBase = number value,
blurExponent = number value,
perlinStartFreq = number value,
perlinLacunarity = number value,
perlinAmplitude = number value,
numTiles = number value,
shoreWaves = boolean value,
forceRendering = boolean value,
hasWaterPlane = boolean value,
}

'''Spring.SetLogSectionFilterLevel''' {{New|95.0}}
(string sectionName, string|number logLevel)
see [[infolog.txt]] for possible log sections (?)

'''Spring.SetDrawGroundDeferred''' {{New|95.0}}
( boolean drawGroundDeferred [, boolean drawGroundForward] ) -> nil
{{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass

'''Spring.SetDrawModelsDeferred''' {{New|95.0}}
( boolean drawUnitsDeferred,
boolean drawFeaturesDeferred
[, boolean drawUnitsForward
[, boolean drawFeaturesForward ]]
) -> nil

{{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes

= GUI =
'''Spring.DrawUnitCommands'''
( number unitID ) -> nil
( { [1] = unitID, ... } [, false ] ) -> nil
( { [unitID] = anything, ... }, true ) -> nil

'''Spring.SetTeamColor'''
( number teamID, number r, number g, number b ) -> nil

'''Spring.AssignMouseCursor''' changes/creates the cursor of a single CursorCmd
( string "cmdName", string "iconFileName"
[, boolean overwrite = true [, boolean hotSpotTopLeft = false] ] ) -> nil | boolean
Note, that iconFileName is not the full filename instead it is like this: 
wanted filename: Anims/cursorattack_0.bmp 
=> iconFileName: cursorattack


'''Spring.ReplaceMouseCursor''' mass replace all occurrence of the cursor in all CursorCmds
( string "oldFileName", string "newFileName" [, boolean hotSpotTopLeft = false] ) -> nil | boolean

'''Spring.SetCustomCommandDrawData''' register your custom cmd so it gets visible in the unit's cmd queue
( number cmdID,
number cmdID_cloneIcon | string iconname,
{ number r, number g, number b, number a } [, boolean showArea ] ) -> nil
( number cmdID, nil) -> nil

= Sharing =
'''Spring.SetShareLevel''' note: shareLevel is 0<= x <= 1 (needs ModUICtrl)
( string "metal" | "energy", number shareLevel ) -> nil
'''Spring.ShareResources''' (needs ModUICtrl)
( number teamID, string "units" ) -> nil
( number teamID, string "metal" | "energy", number amount ) -> nil

= UnitDef RadarIcons & BuildPics =
'''Spring.AddUnitIcon'''
( string iconName, string texFile [, number size [, number dist [, boolean radAdjust ]]] )
-> nil | boolean
'''Spring.FreeUnitIcon'''
( string iconName ) -> nil | boolean
'''Spring.SetUnitDefIcon''' (RadarIcon) (needs ModUICtrl)
( number unitDefID, string iconName ) -> nil
'''Spring.SetUnitDefImage''' (BuildPic) (needs ModUICtrl)
( number unitDefID, luaTexture | string texFile ) -> nil

= Camera =
'''Spring.SetCameraState'''
( table camState, number camTime) -> nil | boolean
camState has the same format as the output of Spring.GetCameraState(). See [[Lua_camState]] for details about camState.

The camState's mode/name must fit the rest of the state. Getting a state, changing its mode/name and then passing it to SetCameraState will have undesired results. [https://springrts.com/mantis/view.php?id=5028#c15491 Also see #5028]

'''Spring.SetCameraTarget'''
( number x, number y, number z [,number transTime] ) -> nil
For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

'''Spring.SetCameraOffset''' (needs ModUICtrl)
( [number px = 0 [, number py = 0 [, number pz = 0
[, number tx = 0 [, number ty = 0 [, number tz = 0]]]]]] ) -> nil

= (Virtual-)FileSystem =
'''Spring.ExtractModArchiveFile'''
( string modfile ) -> boolean
'''Spring.CreateDir''' (needs ModUICtrl)
( number path ) -> nil | boolean

The full VFS API is available at [[Lua_VFS|link]].

= Engine Config =
The following functions read the engine configs saved in [[springrc]], a version-ed instance of these or a custom file supplied on the command line.
If ''*Overlay'' is ''true'', the value will only be set in memory, and not be restored for the next game

'''Spring.GetConfigInt''' (needs ModUICtrl)
( string name [, number default [, boolean setInOverlay = false]] ) -> nil | number
'''Spring.SetConfigInt''' (needs ModUICtrl)
( string name, number value [, boolean useOverlay = false] ) -> nil
'''Spring.GetConfigString''' (needs ModUICtrl)
( string name [, string default [, boolean setInOverlay = false]] ) -> nil | string
'''Spring.SetConfigString''' (needs ModUICtrl)
( string name, string value [, boolean useOverlay = false] ) -> nil

= World Primitives =
outdated! use opengl api instead!

'''Spring.AddWorldIcon'''
( number cmdID, number x, number y, number z ) -> nil
'''Spring.AddWorldText'''
( string "text", number x, number y, number z ) -> nil
'''Spring.AddWorldUnit'''
( number unitDefID,
number x, number y, number z,
number team, number facing) -> nil

= Sun =
The dynamic Sun must be invoked via /dynamicsun.

'''Spring.SetSunManualControl'''
( boolean setManualControl ) - > nil

'''Spring.SetSunParameters'''
( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

'''Spring.SetSunDirection'''
( number dirX, number dirY, number dirZ ) -> nil

'''Spring.SetSunLighting''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following sun lighting parameters:
{ground,unit}{Ambient,Diffuse,Specular}Color and specularExponent
Example usage: Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })


'''Spring.SetAtmosphere''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following atmosphere parameters:
fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})


= Misc =

'''Spring.Reload''' {{new|99.0}}
( string startscript )
start-script is the CONTENT of the [[script.txt]] spring should use to start.

'''Spring.Restart''' {{new|0.79}}
( string commandline_args, string startscript )
-> if this call returns, something went wrong
''commandline_args'' are commandline arguments passed to spring executable

start-script is the CONTENT of the [[script.txt]] spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to ''commandline_args''

'''Spring.SetWMIcon''' {{new|83.0}}
( string iconFileName ) -> nil
Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo). 
Note: has to be 24bit or 32bit 
Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) 
Note: ''*.bmp'' images have to be in BGR format (default for m$ ones). 
Note: ''*.ico'' images are not supported.

'''Spring.SetWMCaption''' {{new|83.0}}
( string title [, string titleShort = title ] ) -> nil

Sets the window ''title'' for the process (default: "Spring <version>").

The ''shortTitle'' is displayed in the OS task-bar (default: "Spring <version>").

'''NOTE:''' ''shortTitle'' is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. See [http://www.gpwiki.org/index.php/SDL:Tutorials:Initializing_SDL_Libraries#About_the_icon_.28.22Icon_Title.22.29_parameter_on_different_window-managers this site] for more details.

'''Spring.ClearWatchdogTimer''' {{new|83.0}}
( [ string threadName = main ] ) -> nil

'''Spring.SetClipboard''' {{new|98.0}}
( string text) -> nil

= Rendering =
== Preload ==
Allow the engine to load the unit's model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.

'''Spring.PreloadUnitDefModel''' {{new|101.0}}
( number unitDefID ) -> nil

'''Spring.PreloadFetureDefModel''' {{new|101.0}}
( number featureDefID ) -> nil

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

'''Spring.AddMapLight''' (requires MaxDynamicMapLights > 0)
(table lightParams) -> number lightHandle
'''Spring.AddModelLight''' (requires MaxDynamicModelLights > 0)
(table lightParams) -> number lightHandle

'''Spring.UpdateMapLight'''
(number lightHandle, table lightParams) -> boolean success
'''Spring.UpdateModelLight'''
(number lightHandle, table lightParams) -> boolean success

'''Spring.SetMapLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success
'''Spring.SetModelLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success

'''lightParams''' is a table that should contain at least one of the following recognized key/value pairs:

lightParams = {
position = {px, py, pz},
direction = {dx, dy, dz},
ambientColor = {red, green, blue},
diffuseColor = {red, green, blue},
specularColor = {red, green, blue},
intensityWeight = {ambientWeight, diffuseWeight, specularWeight},

-- per-frame decay of ambientColor (spread over TTL frames)
ambientDecayRate = {ambientRedDecay, ambientGreenDecay, ambientBlueDecay},
-- per-frame decay of diffuseColor (spread over TTL frames)
diffuseDecayRate = {diffuseRedDecay, diffuseGreenDecay, diffuseBlueDecay},
-- per-frame decay of specularColor (spread over TTL frames)
specularDecayRate = {specularRedDecay, specularGreenDecay, specularBlueDecay},
-- *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
decayFunctionType = {ambientDecayType, diffuseDecayType, specularDecayType},

radius = number elmos,
fov = number degrees,
ttl = number frames,
priority = number,
ignoreLOS = boolean,
}

= Map =
'''Spring.SetSkyBoxTexture''' {{new|101.0}}
( string texName ) -> nil

'''Spring.SetMapShadingTexture''' {{new|101.0}}
( string texType, string texName ) -> boolean success

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

'''Spring.SetMapSquareTexture'''
( number texSqrX, number texSqrY, string luaTexName ) -> boolean success

'''Spring.SetMapShader''' {{101.0}}
( number standardShaderID, number deferredShaderID ) -> nil

<div class="note">The ID's must refer to valid programs returned by gl.CreateShader. Passing in a value of 0 will cause the respective shader to revert back to its engine default. Custom map shaders that declare a uniform ivec2 named "texSquare" can sample from the default diffuse texture(s), which are always bound to TU 0.</div>

[[category: Lua]]

Lua:Callins

2016-09-07T16:09:15Z

Picassoct: /* Lua Callins */

= Lua Callins =
This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the [https://github.com/spring/spring/blob/ebb704e008f6ea645947d07be1cfcc272af0428f/doc/changelog.txt#L71 changelog].

Related Sourcecode :
[https://github.com/spring/spring/blob/d9b3927a528a876b9ab4042771e82b050267572a/rts/Lua/LuaHandle.cpp https://github.com/spring/spring/rts/Lua/LuaHandle.cpp]

For now, to use these addons in a widget, replace addon with widget and, for a gadget, replace addon with gadget. For example,
<code><pre>
function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
...
end
</pre></code>

Some functions may differ between (synced) gadget and widgets; those are in the [[#Synced_-_Unsynced_Shared]] section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.

== Common ==
{{LuaCallin
|name = Initialize
|info = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|info = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|args = type, id
|return = {{type|number}} cmdID
|info = Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either "unit or "feature") and the second is its {{var|unitID}} or {{var|featureID}} respectively.
}}

{{LuaCallin
|name = CommandNotify
|args = cmdID, cmdParams, cmdOptions
|return = {{type|bool}} removeCmd
|info = Called when a command is issued. Returning {{value|true}} deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = CommandsChanged
|args = None
|return = ?
|info = Called when the command descriptions changed, e.g. when selecting or deselecting a unit.
}}

{{LuaCallin
|name = WorldTooltip
|args = ttType, data1, data2, data3
|return = {{type|string}} newTooltip
|info = The parameters can be {{value|"unit"}}, {{var|unitID}}; {{value|"feature"}}, {{var|featureID}}; {{value|"ground"}}, {{var|posX}}, {{var|posY}}, {{var|posZ}} or {{value|"selection"}}.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|args = ???
|info = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|args = serverFrameNum
|info = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
}}

{{LuaCallin
|name = GameSetup
|args = state, ready, playerStates
|return = {{type|bool}} success, {{type|bool}} newReady
|info = ???
}}

{{LuaCallin
|name = SunChanged
|args = ???
|info = ???
}}

{{LuaCallin
|name = AddConsoleLine
|args = msg, priority
|info = Called when text is entered into the console (e.g. Spring.Echo).
}}

{{LuaCallin
|name = RecvSkirmishAIMessage
|args = aiTeam, dataStr
|return = ???
|info = ???
}}

{{LuaCallin
|name = RecvFromSynced
|args = ...
|info = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|args = zip
|info = Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See [[Lua_SaveLoad#Save_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

{{LuaCallin
|name = LoadProgress
|args = message, replaceLastLine
|info = Only available to LuaIntro.
}}

{{LuaCallin
|name = GroupChanged
|args = groupID
|info = Called when a unit is added to or removed from a control group. Currently implemented for widgets only.
}}

{{LuaCallin
|name = ConfigureLayout
|args = ???
|return = ???
|info = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|args = x, y
|return = {{type|bool}} isAbove
|info = Called every Update. Must return {{value|true}} for {{name|Mouse*}} events and {{name|GetToolTip}} to be called.
}}

{{LuaCallin
|name = GetTooltip
|args = x, y
|return = {{type|string}} tooltip
|info = Called when {{name|IsAbove}} returns {{value|true}}.
}}

{{LuaCallin
|name = KeyPress
|args = key, mods, isRepeat
|return = {{type|bool}} becomeOwner
|info = Called repeatedly when a key is pressed down. If you want an action to occur only once check for {{var|1=isRepeat == {{value|false}}}}. The {{var|mods}} parameter is a {{type|table}}, with keys {{value|"alt"}}, {{value|"ctrl"}}, {{value|"meta"}} and {{value|"shift"}} each having a boolean value. Return {{value|true}} if you don't want other callins or the engine to also receive this keypress.
}}

{{LuaCallin
|name = KeyRelease
|args = key
|return = {{type|bool}}
|info = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|args = utf8char
|info = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|args = ???
|info = ???
}}

{{LuaCallin
|name = MousePress
|args = x, y, button
|return = {{type|bool}} becomeMouseOwner
|info = Called when a mouse button is pressed. The {{var|button}} parameter supports up to 7 buttons. Must return {{value|true}} for {{name|MouseRelease}} and other functions to be called.
}}

{{LuaCallin
|name = MouseRelease
|args = x, y, button
|return = bool becomeMouseOwner
|info = Called when a mouse button is released. Please note that in order to have Spring call {{name|MouseRelease}}, you need to have a {{name|MousePress}} call-in in the same addon that returns {{value|true}}.
}}

{{LuaCallin
|name = MouseWheel
|args = up, value
|info = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}

{{LuaCallin
|name = MouseMove
|args = x, y, dx, dy, button
|info = Called when the mouse is moved. The {{var|dx}} and {{var|dy}} parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|args = playerID
|info = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|args = playerID
|info = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|args = playerID, reason
|info = Called whenever a player is removed from the game.
}}

=== Downloads ===

{{LuaCallin
|name = DownloadStarted
|args = id
|info = Called when a [[Pr-downloader]] download is started via [[Lua_VFS#Archives|VFS.DownloadArchive]].
}}

{{LuaCallin
|name = DownloadFinished
|args = id
|info = Called when a [[Pr-downloader]] download finishes successfully(?).
}}

{{LuaCallin
|name = DownloadFailed
|args = id, errorID
|info = Called when a [[Pr-downloader]] download fails to complete.
}}

{{LuaCallin
|name = DownloadProgress
|args = id, downloaded, total
|info = Called incrementally during a [[Pr-downloader]] download.
}}

=== Drawing ===
{{LuaCallin
|name = ViewResize
|args = viewSizeX, viewSizeY
|info = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|args = dt
|info = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}

Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

{{LuaCallin
|name = DrawGenesis
|info = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

{{LuaCallin
|name = DrawWorldPreUnit
|info = Spring draws units, features, some water types, cloaked units, and the sun.
}}

{{LuaCallin
|name = DrawWorld
|info = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|info = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|info = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|info = ???
}}

{{LuaCallin
|name = DrawGroundPreForward
|info = Runs at the start of the forward pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPreDeferred
|info = Runs at the start of the deferred pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPostDeferred
|info = This runs at the end of its respective deferred pass and allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and [[#API:DrawWorldPreUnit|{{name|DrawWorldPreUnit}}]]) via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]].
}}

{{LuaCallin
|name = DrawUnitsPostDeferred
|info = Runs at the end of the unit deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawFeaturesPostDeferred
|info = Runs at the end of the feature deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawScreen
|info = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|args = vsx, vsy
|info = Where {{var|vsx}}, {{var|vsy}} are screen coordinates.
}}

{{LuaCallin
|name = DrawLoadScreen
|info = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls {{var|drawMode}} can be one of the following, {{var|1=notDrawing = {{value|0}}}}, {{var|1=normalDraw = {{value|1}}}}, {{var|1=shadowDraw = {{value|2}}}}, {{var|1=reflectionDraw = {{value|3}}}}, {{var|1=refractionDraw = {{value|4}}}}, and finally {{var|1=gameDeferredDraw = {{value|5}}}} which was added in 102.0.

{{LuaCallin
|name = DrawUnit
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of units, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawFeature
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of features, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawShield
|args = unitID, weaponID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of [[Gamedev:WeaponDefs#Shield_(WeaponType)|shields]].
}}

{{LuaCallin
|name = DrawProjectile
|args = projectileID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of weapon (& other) projectiles.
}}

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|args = msg, player
|info = Called when a player issues a UI command e.g. types {{var|/foo}} or {{var|/luarules foo}}.
}}

=== Game ===

{{LuaCallin
|name = GameID
|args = gameID
|info = Called once to deliver the {{var|gameID}}. As of 101.0+ the string is encoded in hex.
}}

{{LuaCallin
|name = GamePaused
|info = Called when the game is paused.
}}

{{LuaCallin
|name = GameOver
|args = winningAllyTeams
|info = The parameter is a {{type|table}} list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}

{{LuaCallin
|name = GameFrame
|args = frame
|info = Called for every game simulation frame (30 per second). Starts at frame {{value|0}} in 101.0+ and {{value|1}} in previous versions.
}}

{{LuaCallin
|name = GamePreload
|info = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|args = teamID
|info = ???
}}

{{LuaCallin
|name = TeamDied
|args = teamID
|info = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}

=== Units ===
{{LuaCallin
|name = UnitCreated
|args = unitID, unitDefID, unitTeam, builderID
|info = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|args = unitID, unitDefID, unitTeam
|info = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|args = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|info = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitReverseBuilt
|args = unitID, unitDefID, unitTeam
|info = Called when a living unit becomes a nanoframe again.
}}

{{LuaCallin
|name = UnitGiven
|args = unitID, unitDefID, newTeam, oldTeam
|info = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|args = unitID, unitDefID, oldTeam, newTeam
|info = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is damaged (after {{name|UnitPreDamaged}}).
}}

{{LuaCallin
|name = UnitDestroyed
|args = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is destroyed.
}}

{{LuaCallin
|name = RenderUnitDestroyed
|args = unitID, unitDefID, unitTeam
|info = Called just before a unit is invalid, after it finishes its death animation. {{new|101.0}}
}}

{{LuaCallin
|name = UnitStunned
|args = unitID, unitDefID, unitTeam, stunned
|info = Called when a unit changes its stun status. {{new|99.0}}
}}

{{LuaCallin
|name = UnitUnitCollision
|args = colliderID, collideeID
|info = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}

{{LuaCallin
|name = UnitFeatureCollision
|args = colliderID, collideeID
|info = Called when a unit collides with a feature. The unit must be registered with [[Lua_System#Synced|Script.SetWatchUnit]] and the feature registered with [[Lua_System#Synced|Script.SetWatchFeature]].
}}

{{LuaCallin
|name = UnitCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
}}

{{LuaCallin
|name = UnitCmdDone
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|args = unitID, unitDefID, unitTeam, experience, oldExperience
|info = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|args = unitID, unitDefID, unitTeam
|info = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = StockpileChanged
|args = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|info = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}

{{LuaCallin
|name = UnitEnteredLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitSeismicPing
|args = x, y, z, strength, allyTeam, unitID, unitDefID
|info = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}

=== Features ===
{{LuaCallin
|name = FeatureCreated
|args = featureID, allyTeamID
|info = Called when a feature is created.
}}

{{LuaCallin
|name = FeatureDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a feature is damaged.
}}

{{LuaCallin
|name = FeatureDestroyed
|args = featureID, allyTeamID
|info = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|args = ???
|info = ???
}}

=== Projectiles ===
The following Callins are only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].

{{LuaCallin
|name = ProjectileCreated
|args = proID, proOwnerID, weaponDefID
|info = Called when the projectile is created. Note that {{var|weaponDefID}} is missing if the projectile is spawned as part of a burst, but [[Lua_SyncedRead#Projectiles|Spring.GetProjectileDefID]] and [[Lua_SyncedRead#Projectiles|Spring.GetProjectileName]] still work in callin scope using {{var|proID}}.
}}

{{LuaCallin
|name = ProjectileDestroyed
|args = proID
|info = Called when the projectile is destroyed.
}}

== Synced Only ==
{{LuaCallin
|name = CommandFallback
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = {{type|bool}} used, {{type|bool}} finished
|info = Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns {{var|used}} as {{value|true}} the command is dropped, if an addon returns {{value|true}}, {{value|true}} the command is removed because it's done, with {{value|true}}, {{value|false}} it's kept in the queue and {{name|CommandFallback}} gets called again on the next slowupdate.
}}

{{LuaCallin
|name = AllowCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = {{type|bool}} allow
|info = Called when the command is given, before the unit's queue is altered. The return value is whether it should be let into the queue. The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.
}}

{{LuaCallin
|name = AllowUnitCreation
|args = unitDefID, builderID, builderTeam, x, y, z, facing
|return = {{type|bool}} allow
|info = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|args = unitID, unitDefID, oldTeam, newTeam, capture
|return = {{type|bool}} allow
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowUnitBuildStep
|args = builderID, builderTeam, unitID, unitDefID, part
|return = {{type|bool}} allow
|info = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

{{LuaCallin
|name = AllowFeatureCreation
|args = featureDefID, teamID, x, y, z
|return = {{type|bool}} allow
|info = Called just before feature is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowFeatureBuildStep
|args = builderID, builderTeam, featureID, featureDefID, part
|return = {{type|bool}} allow
|info = Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.
}}

{{LuaCallin
|name = AllowResourceLevel
|args = teamID, res, level
|return = {{type|bool}} allow
|info = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
}}

{{LuaCallin
|name = AllowResourceTransfer
|args = oldTeamID, newTeamID, res, amount
|return = {{type|bool}} allow
|info = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|args = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = {{type|bool}} allow
|info = {{var|clamped{X,Y,Z}}} are the coordinates clamped into start-boxes, {{var|raw}} is where player tried to place their marker. The {{var|readyState}} can be any one of
* {{value|0}} - player picked a position,
* {{value|1}} - player clicked ready,
* {{value|2}} - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* {{value|3}} - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.
}}

{{LuaCallin
|name = AllowDirectUnitControl
|args = unitID, unitDefID, unitTeam, playerID
|return = {{type|bool}} allow
|info = Determines if this unit can be controlled directly in FPS view.
}}

{{LuaCallin
|name = AllowWeaponTargetCheck
|args = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = {{type|bool}} allowCheck, {{type|bool}} ignoreCheck
|info = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag. The {{var|ignoreCheck}} return value was added in 99.0 to allow ignoring the callin i.e. running normal engine check for this weapon.
}}

{{LuaCallin
|name = AllowWeaponTarget
|args = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = {{type|bool}} allowed, {{type|number}} newPriority
|info = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value is the new priority for this target (if you don't want to change it, return {{var|defPriority}}). Lower priority targets are targeted first.
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|args = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = {{type|bool}} allowed
|info = Controls blocking of a specific intercept target from being considered during an {{xtaglink|Gamedev:WeaponDefs|interceptor}} weapon's periodic auto-targeting sweep. Only called for {{var|weaponDefIDs}} registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

{{LuaCallin
|name = AllowBuilderHoldFire
|args = unitID, unitDefID, action
|return = {{type|bool}} actionAllowed
|info = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}} Called when a construction unit wants to "use his nano beams". {{var|action}} is one of following:
* {{value|-1}} Build
* {{value|CMD.REPAIR}} Repair
* {{value|CMD.RECLAIM}} Reclaim
* {{value|CMD.RESTORE}} Restore
* {{value|CMD.RESURRECT}} Resurrect
* {{value|CMD.CAPTURE}} Capture
}}

{{LuaCallin
|name = Explosion
|args = weaponDefID, px, py, pz, AttackerID
|return = {{type|bool}} noGfx
|info = Called when an explosion occurs. If it returns {{value|true}} then no graphical effects are drawn by the engine for this explosion.
}}

{{LuaCallin
|name = TerraformComplete
|args = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = {{type|bool}} stop
|info = Called when pre-building terrain levelling terraforms are completed (c.f. {{xtaglink|Gamedev:UnitDefs|levelGround}}). If the return value is {{value|true}} the current build order is terminated.
}}

{{LuaCallin
|name = MoveCtrlNotify
|args = unitID, unitDefID, unitTeam, data
|return = {{type|bool}} moveCtrlComplete
|info = Enable both [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetCollideStop]] and [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetTrackGround]] to enable this call-in, data was supposed to indicate the type of notification but currently never has a value other than {{value|1}} ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled ({{value|false}}) or return to engine controlled movement ({{value|true}}).
}}

{{LuaCallin
|name = RecvLuaMsg
|args = msg, playerID
|info = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}

{{LuaCallin
|name = Load
|args = zip
|info = Called after {{name|GamePreload}} and before {{name|GameStart}}. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

=== Damage Controllers ===
For the following callins, in addition to being a regular weapon, {{var|weaponDefID}} may be one of the following:
* {{value|-1}} - debris collision, also default of [[Lua_SyncedCtrl#Unit_Control|Spring.AddUnitDamage]]
* {{value|-2}} - ground collision
* {{value|-3}} - object collision
* {{value|-4}} - fire damage
* {{value|-5}} - water damage
* {{value|-6}} - kill damage
* {{value|-7}} - crush damage

{{LuaCallin
|name = UnitPreDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the unit, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

{{LuaCallin
|name = ShieldPreDamaged
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID
|return = {{type|bool}} handleCollision
|info = Called before any engine shield-vs-projectile logic executes. If the return value is {{value|true}} the gadget handles the collision event and the engine does not remove the projectile. If the weapon is a hitscan type ([[Gamedev:WeaponDefs#Tag:weaponType|BeamLaser]] or [[Gamedev:WeaponDefs#Tag:weaponType|LightningCanon]]) then {{var|proID}} is {{value|nil}} and {{var|beamEmitterWeaponNum}} and {{var|beamEmitterUnitID}} are populated instead.
}}

{{LuaCallin
|name = FeaturePreDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the feature, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

[[Category: Lua]]

Lua:Callins

2016-09-07T16:08:24Z

Picassoct: /* Lua Callins */ Added the sources pages at the top.

= Lua Callins =
This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the [https://github.com/spring/spring/blob/ebb704e008f6ea645947d07be1cfcc272af0428f/doc/changelog.txt#L71 changelog].

Related Sourcecode :
[https://github.com/spring/spring/rts/Lua/LuaHandle.cpp https://github.com/spring/spring/rts/Lua/LuaHandle.cpp]

For now, to use these addons in a widget, replace addon with widget and, for a gadget, replace addon with gadget. For example,
<code><pre>
function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
...
end
</pre></code>

Some functions may differ between (synced) gadget and widgets; those are in the [[#Synced_-_Unsynced_Shared]] section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.

== Common ==
{{LuaCallin
|name = Initialize
|info = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|info = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|args = type, id
|return = {{type|number}} cmdID
|info = Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either "unit or "feature") and the second is its {{var|unitID}} or {{var|featureID}} respectively.
}}

{{LuaCallin
|name = CommandNotify
|args = cmdID, cmdParams, cmdOptions
|return = {{type|bool}} removeCmd
|info = Called when a command is issued. Returning {{value|true}} deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = CommandsChanged
|args = None
|return = ?
|info = Called when the command descriptions changed, e.g. when selecting or deselecting a unit.
}}

{{LuaCallin
|name = WorldTooltip
|args = ttType, data1, data2, data3
|return = {{type|string}} newTooltip
|info = The parameters can be {{value|"unit"}}, {{var|unitID}}; {{value|"feature"}}, {{var|featureID}}; {{value|"ground"}}, {{var|posX}}, {{var|posY}}, {{var|posZ}} or {{value|"selection"}}.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|args = ???
|info = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|args = serverFrameNum
|info = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
}}

{{LuaCallin
|name = GameSetup
|args = state, ready, playerStates
|return = {{type|bool}} success, {{type|bool}} newReady
|info = ???
}}

{{LuaCallin
|name = SunChanged
|args = ???
|info = ???
}}

{{LuaCallin
|name = AddConsoleLine
|args = msg, priority
|info = Called when text is entered into the console (e.g. Spring.Echo).
}}

{{LuaCallin
|name = RecvSkirmishAIMessage
|args = aiTeam, dataStr
|return = ???
|info = ???
}}

{{LuaCallin
|name = RecvFromSynced
|args = ...
|info = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|args = zip
|info = Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See [[Lua_SaveLoad#Save_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

{{LuaCallin
|name = LoadProgress
|args = message, replaceLastLine
|info = Only available to LuaIntro.
}}

{{LuaCallin
|name = GroupChanged
|args = groupID
|info = Called when a unit is added to or removed from a control group. Currently implemented for widgets only.
}}

{{LuaCallin
|name = ConfigureLayout
|args = ???
|return = ???
|info = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|args = x, y
|return = {{type|bool}} isAbove
|info = Called every Update. Must return {{value|true}} for {{name|Mouse*}} events and {{name|GetToolTip}} to be called.
}}

{{LuaCallin
|name = GetTooltip
|args = x, y
|return = {{type|string}} tooltip
|info = Called when {{name|IsAbove}} returns {{value|true}}.
}}

{{LuaCallin
|name = KeyPress
|args = key, mods, isRepeat
|return = {{type|bool}} becomeOwner
|info = Called repeatedly when a key is pressed down. If you want an action to occur only once check for {{var|1=isRepeat == {{value|false}}}}. The {{var|mods}} parameter is a {{type|table}}, with keys {{value|"alt"}}, {{value|"ctrl"}}, {{value|"meta"}} and {{value|"shift"}} each having a boolean value. Return {{value|true}} if you don't want other callins or the engine to also receive this keypress.
}}

{{LuaCallin
|name = KeyRelease
|args = key
|return = {{type|bool}}
|info = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|args = utf8char
|info = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|args = ???
|info = ???
}}

{{LuaCallin
|name = MousePress
|args = x, y, button
|return = {{type|bool}} becomeMouseOwner
|info = Called when a mouse button is pressed. The {{var|button}} parameter supports up to 7 buttons. Must return {{value|true}} for {{name|MouseRelease}} and other functions to be called.
}}

{{LuaCallin
|name = MouseRelease
|args = x, y, button
|return = bool becomeMouseOwner
|info = Called when a mouse button is released. Please note that in order to have Spring call {{name|MouseRelease}}, you need to have a {{name|MousePress}} call-in in the same addon that returns {{value|true}}.
}}

{{LuaCallin
|name = MouseWheel
|args = up, value
|info = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}

{{LuaCallin
|name = MouseMove
|args = x, y, dx, dy, button
|info = Called when the mouse is moved. The {{var|dx}} and {{var|dy}} parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|args = playerID
|info = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|args = playerID
|info = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|args = playerID, reason
|info = Called whenever a player is removed from the game.
}}

=== Downloads ===

{{LuaCallin
|name = DownloadStarted
|args = id
|info = Called when a [[Pr-downloader]] download is started via [[Lua_VFS#Archives|VFS.DownloadArchive]].
}}

{{LuaCallin
|name = DownloadFinished
|args = id
|info = Called when a [[Pr-downloader]] download finishes successfully(?).
}}

{{LuaCallin
|name = DownloadFailed
|args = id, errorID
|info = Called when a [[Pr-downloader]] download fails to complete.
}}

{{LuaCallin
|name = DownloadProgress
|args = id, downloaded, total
|info = Called incrementally during a [[Pr-downloader]] download.
}}

=== Drawing ===
{{LuaCallin
|name = ViewResize
|args = viewSizeX, viewSizeY
|info = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|args = dt
|info = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}

Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

{{LuaCallin
|name = DrawGenesis
|info = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

{{LuaCallin
|name = DrawWorldPreUnit
|info = Spring draws units, features, some water types, cloaked units, and the sun.
}}

{{LuaCallin
|name = DrawWorld
|info = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|info = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|info = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|info = ???
}}

{{LuaCallin
|name = DrawGroundPreForward
|info = Runs at the start of the forward pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPreDeferred
|info = Runs at the start of the deferred pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPostDeferred
|info = This runs at the end of its respective deferred pass and allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and [[#API:DrawWorldPreUnit|{{name|DrawWorldPreUnit}}]]) via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]].
}}

{{LuaCallin
|name = DrawUnitsPostDeferred
|info = Runs at the end of the unit deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawFeaturesPostDeferred
|info = Runs at the end of the feature deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawScreen
|info = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|args = vsx, vsy
|info = Where {{var|vsx}}, {{var|vsy}} are screen coordinates.
}}

{{LuaCallin
|name = DrawLoadScreen
|info = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls {{var|drawMode}} can be one of the following, {{var|1=notDrawing = {{value|0}}}}, {{var|1=normalDraw = {{value|1}}}}, {{var|1=shadowDraw = {{value|2}}}}, {{var|1=reflectionDraw = {{value|3}}}}, {{var|1=refractionDraw = {{value|4}}}}, and finally {{var|1=gameDeferredDraw = {{value|5}}}} which was added in 102.0.

{{LuaCallin
|name = DrawUnit
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of units, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawFeature
|args = unitID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of features, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawShield
|args = unitID, weaponID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of [[Gamedev:WeaponDefs#Shield_(WeaponType)|shields]].
}}

{{LuaCallin
|name = DrawProjectile
|args = projectileID, drawMode
|return = {{type|bool}} suppressEngineDraw
|info = For custom rendering of weapon (& other) projectiles.
}}

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|args = msg, player
|info = Called when a player issues a UI command e.g. types {{var|/foo}} or {{var|/luarules foo}}.
}}

=== Game ===

{{LuaCallin
|name = GameID
|args = gameID
|info = Called once to deliver the {{var|gameID}}. As of 101.0+ the string is encoded in hex.
}}

{{LuaCallin
|name = GamePaused
|info = Called when the game is paused.
}}

{{LuaCallin
|name = GameOver
|args = winningAllyTeams
|info = The parameter is a {{type|table}} list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}

{{LuaCallin
|name = GameFrame
|args = frame
|info = Called for every game simulation frame (30 per second). Starts at frame {{value|0}} in 101.0+ and {{value|1}} in previous versions.
}}

{{LuaCallin
|name = GamePreload
|info = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|args = teamID
|info = ???
}}

{{LuaCallin
|name = TeamDied
|args = teamID
|info = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}

=== Units ===
{{LuaCallin
|name = UnitCreated
|args = unitID, unitDefID, unitTeam, builderID
|info = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|args = unitID, unitDefID, unitTeam
|info = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|args = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|info = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitReverseBuilt
|args = unitID, unitDefID, unitTeam
|info = Called when a living unit becomes a nanoframe again.
}}

{{LuaCallin
|name = UnitGiven
|args = unitID, unitDefID, newTeam, oldTeam
|info = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|args = unitID, unitDefID, oldTeam, newTeam
|info = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is damaged (after {{name|UnitPreDamaged}}).
}}

{{LuaCallin
|name = UnitDestroyed
|args = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is destroyed.
}}

{{LuaCallin
|name = RenderUnitDestroyed
|args = unitID, unitDefID, unitTeam
|info = Called just before a unit is invalid, after it finishes its death animation. {{new|101.0}}
}}

{{LuaCallin
|name = UnitStunned
|args = unitID, unitDefID, unitTeam, stunned
|info = Called when a unit changes its stun status. {{new|99.0}}
}}

{{LuaCallin
|name = UnitUnitCollision
|args = colliderID, collideeID
|info = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}

{{LuaCallin
|name = UnitFeatureCollision
|args = colliderID, collideeID
|info = Called when a unit collides with a feature. The unit must be registered with [[Lua_System#Synced|Script.SetWatchUnit]] and the feature registered with [[Lua_System#Synced|Script.SetWatchFeature]].
}}

{{LuaCallin
|name = UnitCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
}}

{{LuaCallin
|name = UnitCmdDone
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|args = unitID, unitDefID, unitTeam, experience, oldExperience
|info = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|args = unitID, unitDefID, unitTeam
|info = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = StockpileChanged
|args = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|info = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}

{{LuaCallin
|name = UnitEnteredLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitSeismicPing
|args = x, y, z, strength, allyTeam, unitID, unitDefID
|info = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}

=== Features ===
{{LuaCallin
|name = FeatureCreated
|args = featureID, allyTeamID
|info = Called when a feature is created.
}}

{{LuaCallin
|name = FeatureDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a feature is damaged.
}}

{{LuaCallin
|name = FeatureDestroyed
|args = featureID, allyTeamID
|info = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|args = ???
|info = ???
}}

=== Projectiles ===
The following Callins are only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].

{{LuaCallin
|name = ProjectileCreated
|args = proID, proOwnerID, weaponDefID
|info = Called when the projectile is created. Note that {{var|weaponDefID}} is missing if the projectile is spawned as part of a burst, but [[Lua_SyncedRead#Projectiles|Spring.GetProjectileDefID]] and [[Lua_SyncedRead#Projectiles|Spring.GetProjectileName]] still work in callin scope using {{var|proID}}.
}}

{{LuaCallin
|name = ProjectileDestroyed
|args = proID
|info = Called when the projectile is destroyed.
}}

== Synced Only ==
{{LuaCallin
|name = CommandFallback
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = {{type|bool}} used, {{type|bool}} finished
|info = Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns {{var|used}} as {{value|true}} the command is dropped, if an addon returns {{value|true}}, {{value|true}} the command is removed because it's done, with {{value|true}}, {{value|false}} it's kept in the queue and {{name|CommandFallback}} gets called again on the next slowupdate.
}}

{{LuaCallin
|name = AllowCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = {{type|bool}} allow
|info = Called when the command is given, before the unit's queue is altered. The return value is whether it should be let into the queue. The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.
}}

{{LuaCallin
|name = AllowUnitCreation
|args = unitDefID, builderID, builderTeam, x, y, z, facing
|return = {{type|bool}} allow
|info = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|args = unitID, unitDefID, oldTeam, newTeam, capture
|return = {{type|bool}} allow
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowUnitBuildStep
|args = builderID, builderTeam, unitID, unitDefID, part
|return = {{type|bool}} allow
|info = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

{{LuaCallin
|name = AllowFeatureCreation
|args = featureDefID, teamID, x, y, z
|return = {{type|bool}} allow
|info = Called just before feature is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowFeatureBuildStep
|args = builderID, builderTeam, featureID, featureDefID, part
|return = {{type|bool}} allow
|info = Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.
}}

{{LuaCallin
|name = AllowResourceLevel
|args = teamID, res, level
|return = {{type|bool}} allow
|info = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
}}

{{LuaCallin
|name = AllowResourceTransfer
|args = oldTeamID, newTeamID, res, amount
|return = {{type|bool}} allow
|info = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|args = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = {{type|bool}} allow
|info = {{var|clamped{X,Y,Z}}} are the coordinates clamped into start-boxes, {{var|raw}} is where player tried to place their marker. The {{var|readyState}} can be any one of
* {{value|0}} - player picked a position,
* {{value|1}} - player clicked ready,
* {{value|2}} - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* {{value|3}} - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.
}}

{{LuaCallin
|name = AllowDirectUnitControl
|args = unitID, unitDefID, unitTeam, playerID
|return = {{type|bool}} allow
|info = Determines if this unit can be controlled directly in FPS view.
}}

{{LuaCallin
|name = AllowWeaponTargetCheck
|args = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = {{type|bool}} allowCheck, {{type|bool}} ignoreCheck
|info = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag. The {{var|ignoreCheck}} return value was added in 99.0 to allow ignoring the callin i.e. running normal engine check for this weapon.
}}

{{LuaCallin
|name = AllowWeaponTarget
|args = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = {{type|bool}} allowed, {{type|number}} newPriority
|info = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value is the new priority for this target (if you don't want to change it, return {{var|defPriority}}). Lower priority targets are targeted first.
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|args = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = {{type|bool}} allowed
|info = Controls blocking of a specific intercept target from being considered during an {{xtaglink|Gamedev:WeaponDefs|interceptor}} weapon's periodic auto-targeting sweep. Only called for {{var|weaponDefIDs}} registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

{{LuaCallin
|name = AllowBuilderHoldFire
|args = unitID, unitDefID, action
|return = {{type|bool}} actionAllowed
|info = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}} Called when a construction unit wants to "use his nano beams". {{var|action}} is one of following:
* {{value|-1}} Build
* {{value|CMD.REPAIR}} Repair
* {{value|CMD.RECLAIM}} Reclaim
* {{value|CMD.RESTORE}} Restore
* {{value|CMD.RESURRECT}} Resurrect
* {{value|CMD.CAPTURE}} Capture
}}

{{LuaCallin
|name = Explosion
|args = weaponDefID, px, py, pz, AttackerID
|return = {{type|bool}} noGfx
|info = Called when an explosion occurs. If it returns {{value|true}} then no graphical effects are drawn by the engine for this explosion.
}}

{{LuaCallin
|name = TerraformComplete
|args = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = {{type|bool}} stop
|info = Called when pre-building terrain levelling terraforms are completed (c.f. {{xtaglink|Gamedev:UnitDefs|levelGround}}). If the return value is {{value|true}} the current build order is terminated.
}}

{{LuaCallin
|name = MoveCtrlNotify
|args = unitID, unitDefID, unitTeam, data
|return = {{type|bool}} moveCtrlComplete
|info = Enable both [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetCollideStop]] and [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetTrackGround]] to enable this call-in, data was supposed to indicate the type of notification but currently never has a value other than {{value|1}} ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled ({{value|false}}) or return to engine controlled movement ({{value|true}}).
}}

{{LuaCallin
|name = RecvLuaMsg
|args = msg, playerID
|info = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}

{{LuaCallin
|name = Load
|args = zip
|info = Called after {{name|GamePreload}} and before {{name|GameStart}}. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

=== Damage Controllers ===
For the following callins, in addition to being a regular weapon, {{var|weaponDefID}} may be one of the following:
* {{value|-1}} - debris collision, also default of [[Lua_SyncedCtrl#Unit_Control|Spring.AddUnitDamage]]
* {{value|-2}} - ground collision
* {{value|-3}} - object collision
* {{value|-4}} - fire damage
* {{value|-5}} - water damage
* {{value|-6}} - kill damage
* {{value|-7}} - crush damage

{{LuaCallin
|name = UnitPreDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the unit, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

{{LuaCallin
|name = ShieldPreDamaged
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID
|return = {{type|bool}} handleCollision
|info = Called before any engine shield-vs-projectile logic executes. If the return value is {{value|true}} the gadget handles the collision event and the engine does not remove the projectile. If the weapon is a hitscan type ([[Gamedev:WeaponDefs#Tag:weaponType|BeamLaser]] or [[Gamedev:WeaponDefs#Tag:weaponType|LightningCanon]]) then {{var|proID}} is {{value|nil}} and {{var|beamEmitterWeaponNum}} and {{var|beamEmitterUnitID}} are populated instead.
}}

{{LuaCallin
|name = FeaturePreDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the feature, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

[[Category: Lua]]

Building Spring on Linux

2016-08-27T14:47:31Z

Picassoct: Librarys needed for ubuntubuild updated

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the >=4.6 series should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL2
** ''boost'' (version 1.47 or later)
*** ''chrono''
*** ''filesystem''
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Jessie (debian 8.0 stable) this should work:

<code><pre>
sudo apt-get install build-essential zlib1g-dev libfreetype6-dev cmake \
libsdl2-dev libopenal-dev libglew-dev zip libvorbis-dev libxcursor-dev \
libdevil-dev libboost-system1.55-dev libboost-thread1.55-dev \
libboost-regex1.55-dev libboost-serialization1.55-dev \
libboost-program-options1.55-dev libboost-chrono1.55-dev \
libunwind-dev libboost-filesystem1.55-dev \
libboost-signals1.55-dev libboost-test1.55-dev \
xsltproc libfontconfig1-dev libcurl4-openssl-dev
</pre></code>

=== Ubuntu ===
<code><pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl2-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread-dev libboost-regex-dev libboost-system-dev \
libboost-program-options-dev libboost-signals-dev \
libboost-chrono-dev libboost-filesystem-dev libunwind8-dev
default-jdk libcurl4-gnutls-dev
</pre></code>

to speed up compiling/linking, you can install gold, an alternative linker and when you plan to develop / recompile often ccache :

<code><pre>sudo apt-get install binutils-gold ccache</pre></code>

to make ccache useful, the cache size needs to be increased by:

<code><pre>ccache -M 5G</pre></code>

to set it to 5GB.

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-2
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

Or better you install Spring via [http://springrts.com/wiki/Gentoo_install layman], it will install all dependencies.

== Fedora ==

On Fedora 12-21:

<code><pre>
sudo yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel libunwind-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL2-devel p7zip
</pre></code>

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL2-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL2 already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

Try to use [http://idlemoor.github.io/slackrepo/ slackrepo], will search, update and install spring and dependences.

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
cmake .
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>~/spring</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=~/spring .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

For other targets see the output of <code>make help</code>.

= See Also: =
* [[Finalizing_linux_install]]
* [[Troubleshooting_linux]]

[[Category:Compiling]]
[[Category:Linux]]

Games

2016-06-04T01:11:29Z

Picassoct: /* Proprietary */

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Game can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([https://github.com/spring1944/spring1944/blob/master/docs/License.txt CC-BY-NC])
|-
| | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| | <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://springfiles.com/spring/games/edge-1}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|-
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
| width=40 |
| align="center" width="300px" | <h2>[http://www.metalfactions.pt Metal Factions]</h2>
([http://www.metalfactions.pt/about.html#license CC-BY-ND, with GPL/PD code])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|
| align="center" | {{navimgx|xsize=300|ysize=225|image=Mf_spring_wiki.jpg|link=http://www.metalfactions.pt}}
|-
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|
| align="justify" valign="top" | An evolving game that started as a TA mod and currently features four factions: AVEN, GEAR, CLAW and SPHERE. Commanders can morph to fit into different play styles and be easily revived. Economy scaling is more strictly tied to map control.
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
| width=40 |
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=69 Journeywar] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" | {{navimgx|xsize=300|ysize=225|image=JwLogo.jpg|link=https://springrts.com/phpbb/viewtopic.php?f=69&t=23275&start=1180}}
|
| align="center" |
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | Journeywar is the final battle between Combine and Exobiotics. Join the fight and rediscover the HL- Universe from a new, strategic perspective. Download in Springlogbby as jw:test archive.

|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| | <h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
| width=40 |
| | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| | {{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)

|-
| | <h2>[http://nota.machys.net/downloads NOTA]</h2>
| width=40 |
| | <h2> [[XTA]] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=notAgame02.jpg|link=http://nota.machys.net/downloads}}
| width=40 |
| | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
| width=40 |
| valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

File:JwLogo.jpg

2016-06-04T01:10:38Z

Picassoct: Logo of Journeywar

Logo of Journeywar

Games

2016-06-03T23:51:52Z

Picassoct: /* Proprietary */

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Game can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([https://github.com/spring1944/spring1944/blob/master/docs/License.txt CC-BY-NC])
|-
| | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| | <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://springfiles.com/spring/games/edge-1}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|-
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
| width=40 |
| align="center" width="300px" | <h2>[http://www.metalfactions.pt Metal Factions]</h2>
([http://www.metalfactions.pt/about.html#license CC-BY-ND, with GPL/PD code])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|
| align="center" | {{navimgx|xsize=300|ysize=225|image=Mf_spring_wiki.jpg|link=http://www.metalfactions.pt}}
|-
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|
| align="justify" valign="top" | An evolving game that started as a TA mod and currently features four factions: AVEN, GEAR, CLAW and SPHERE. Commanders can morph to fit into different play styles and be easily revived. Economy scaling is more strictly tied to map control.
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
| width=40 |
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=69 Journeywar] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" | {{navimgx|xsize=300|ysize=225|image= JWLogo.jpg|link=https://springrts.com/phpbb/viewtopic.php?f=69&t=23275&start=1180}}
|
| align="center" |
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | Journeywar is the final battle between Combine and Exobiotics. Join the fight and rediscover the HL- Universe from a new, strategic perspective. Download in Springlogbby as jw:test archive.

|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| | <h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
| width=40 |
| | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| | {{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)

|-
| | <h2>[http://nota.machys.net/downloads NOTA]</h2>
| width=40 |
| | <h2> [[XTA]] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=notAgame02.jpg|link=http://nota.machys.net/downloads}}
| width=40 |
| | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
| width=40 |
| valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Games

2016-06-03T23:50:51Z

Picassoct: /* Proprietary - Added my game into the Section where Mech Warrior and Gundam will go.*/

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Game can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([https://github.com/spring1944/spring1944/blob/master/docs/License.txt CC-BY-NC])
|-
| | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| | <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://springfiles.com/spring/games/edge-1}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|-
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
| width=40 |
| align="center" width="300px" | <h2>[http://www.metalfactions.pt Metal Factions]</h2>
([http://www.metalfactions.pt/about.html#license CC-BY-ND, with GPL/PD code])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|
| align="center" | {{navimgx|xsize=300|ysize=225|image=Mf_spring_wiki.jpg|link=http://www.metalfactions.pt}}
|-
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|
| align="justify" valign="top" | An evolving game that started as a TA mod and currently features four factions: AVEN, GEAR, CLAW and SPHERE. Commanders can morph to fit into different play styles and be easily revived. Economy scaling is more strictly tied to map control.
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
| width=40 |
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=69 Journeywar] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" | {{navimgx|xsize=300|ysize=225|image= JWLogo.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | Journeywar is the final battle between Combine and Exobiotics. Join the fight and rediscover the HL- Universe from a new, strategic perspective. Download in Springlogbby as jw:test archive.

|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| | <h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
| width=40 |
| | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| | {{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)

|-
| | <h2>[http://nota.machys.net/downloads NOTA]</h2>
| width=40 |
| | <h2> [[XTA]] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=notAgame02.jpg|link=http://nota.machys.net/downloads}}
| width=40 |
| | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
| width=40 |
| valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Lua WeaponDefs

2016-05-15T11:28:19Z

Picassoct: He who removed this from the page should be ashamed- rather show outdated information or just a link to source- then no information

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

The '''WeaponDefs[]''' table holds all information about the weapons used in a game.

Works the same way as [[Lua_UnitDefs]] except the tables are called '''WeaponDefs[]''' and '''WeaponDefNames[]'''

Note: Its entries are metatables, so you can't use the pairs() iterator on them, use this instead:
<code>
for id,weaponDef in pairs(WeaponDefs) do
for name,param in weaponDef:pairs() do
Spring.Echo(name,param)
end
end
</code>

==Naming==
If a unit named "tank" has a weapon named "gun", the resulting <code>name</code> will be "tank_gun" and you can get this weaponDefID like:

<code>local gunID = WeaponDefNames["tank_gun"].id</code>

==Example==
For a more detailed, but outdated tag definition look at
[[Weapon_Variables]] or look directly at the source at
https://github.com/spring/spring/blob/5f08624585852b8c8dfd1a16d020ae530269dc09/rts/Sim/Weapons/WeaponLoader.cpp

In key = value format, where WeaponDefs[weaponDefID].key==value, with subtables at the end.
<code><pre>
accuracy = 0,
avoidFeature = false,
avoidFriendly = true,
avoidNeutral = false,
beamTTL = 0,
beamburst = false,
beamtime = 0.10000000149012,
bouncerebound = 1,
canAttackGround = true,
cegTag = "",
collisionSize = 0.050000000745058,
coverageRange = 0,
craterAreaOfEffect = 0,
cylinderTargeting = 1,
cylinderTargetting = 1,
damageAreaOfEffect = 6,
dance = 0,
description = "J7Laser",
duration = 0.050000000745058,
dynDamageExp = 0,
dynDamageInverted = false,
dynDamageMin = 0,
dynDamageRange = 0,
edgeEffectiveness = 0.99000000953674,
energyCost = 0,
explosionSpeed = 3.233583688736,
exteriorShield = false,
fireStarter = 0.69999998807907,
flightTime = 0,
gravityAffected = false,
groundbounce = false,
groundslip = 1,
heightBoostFactor = -1,
heightMod = 1,
highTrajectory = 2,
id = 220,
impactOnly = true,
intensity = 0.89999997615814,
interceptSolo = true,
interceptedByShieldType = 2,
interceptor = 0,
isShield = false,
largeBeamLaser = false,
laserHardStop = false,
leadBonus = 0,
leadLimit = -1,
manualFire = false,
maxAngle = 0.95873802900314,
metalCost = 0,
minIntensity = 0,
movingAccuracy = 0,
myGravity = 0,
name = "corcom_armcomlaser",
noAutoTarget = false,
noEnemyCollide = false,
noExplode = false,
noFeatureCollide = false,
noFriendlyCollide = false,
noGroundCollide = false,
noNeutralCollide = false,
noSelfDamage = true,
numbounce = -1,
onlyForward = false,
paralyzer = false,
predictBoost = 0,
projectiles = 1,
projectilespeed = 30.000001907349,
proximityPriority = 1,
range = 300,
reload = 0.40000000596046,
salvoDelay = 0.10000000149012,
salvoSize = 1,
selfExplode = false,
shieldAlpha = 0.20000000298023,
shieldBadColorB = 0.5,
shieldBadColorG = 0.5,
shieldBadColorR = 1,
shieldEnergyUse = 0,
shieldForce = 0,
shieldGoodColorB = 1,
shieldGoodColorG = 0.5,
shieldGoodColorR = 0.5,
shieldInterceptType = 0,
shieldMaxSpeed = 0,
shieldPower = 0,
shieldPowerRegen = 0,
shieldPowerRegenEnergy = 0,
shieldRadius = 0,
shieldRechargeDelay = 0,
shieldRepulser = false,
size = 2.1875,
sizeGrowth = 0.5,
smartShield = false,
soundTrigger = true,
sprayAngle = 0,
startvelocity = 0.0099999997764826,
stockpile = false,
stockpileTime = 30,
sweepFire = false,
targetBorder = 0,
targetMoveError = 0.050000000745058,
targetable = 0,
tdfId = 0,
tracks = false,
trajectoryHeight = 0,
turnRate = 0,
turret = true,
type = "BeamLaser",
uptime = 0,
visibleShield = false,
visibleShieldHitFrames = 0,
visibleShieldRepulse = false,
waterWeapon = false,
waterbounce = false,
weaponAcceleration = 0,
wobble = 0,
customParams = {},
damages = {
craterBoost = 0,
...
},
fireSound = {
[1] = {
id = 36,
name = "lasrfir1",
volume = 6.1237244606018,
},
...
},
hitSound = {
[1] = {
id = -1,
name = "",
volume = 6.1237244606018,
},
...
},
visuals = {
alphaDecay = 1,
alwaysVisible = false,
beamDecay = 1,
beamWeapon = false,
color2B = 1,
color2G = 1,
color2R = 1,
colorB = 0,
colorG = 0,
colorR = 1,
coreThickness = 0.10000000149012,
laserFlareSize = 7,
modelName = "",
noGap = true,
pulseSpeed = 1,
scrollSpeed = 5,
separation = 1,
sizeDecay = 0,
smokeTrail = false,
stages = 5,
thickness = 2,
tileLength = 200,
},
</pre></code>

[[category: Lua]]

Gamedev:WeaponDefs

2016-03-01T22:23:40Z

Picassoct: /*He was a good tag, he served is time - and now he is gone. Replaced by some hardcoded behaviour sniff.. */

[[Gamedev:Main|Development]] < [[Gamedev:Main]] < {{FULLPAGENAME}}

==Location==
WeaponDef files are .lua files stored in the <code>Weapons/</code> directory of a Spring Game. Alternatively they can be integrated into [[Gamedev:UnitDefs|UnitDefs]].

==Purpose==
WeaponDef files have one purpose; to define the properties of weapons. They are the main description file for what attributes your weapon should have and how it should behave. Since version 100.0, Spring will record a warning whenever it finds an unknown tag.

==Source==
The engine source code which loads the tags from these files is viewable here:

* {{sourcelink|file=rts/Sim/Weapons/WeaponDef.cpp}}

==Data Types==
{{DataTypes}}

==Details==
There follows a comprehensive (certain deprecated tags are not present) list of the tags available, their data type, default value and a brief description of what they do. Bear in mind that the source code linked above is the ultimate reference when dealing with these tags.

In lua tables keys (i.e. the tags) should be lower case, here they are represented in camelCase for readability. In your files you may use the <code>lowerkeys</code> function on your final table to ensure the keys are properly cased.

It is usual to name the returned WeaponDef table the internal <code>weaponName</code> desired for the weapon.

===Common===
The following tags are common to all or at least a majority of '''WeaponTypes''', depending on the tag.

====General====
{{tag
|name = weaponType
|type = string
|default = "Cannon"
|description = Spring has 14 '''WeaponTypes''' which provide game developers with basic behaviours which they can customise to an extent with the '''WeaponDef''' tags. Some tags are specific to certain '''WeaponTypes''' and not implemented for others, [https://docs.google.com/spreadsheet/ccc?key=0Am5BbZxm93S9dEZXc1Q4dXR4TFRYTFM4NlR4OFJFdWc#gid=0 this two-way table] indicates which tags work for which types.}} The possible values are:
* [[#AircraftBomb|AircraftBomb]]
* [[#BeamLaser|BeamLaser]]
* [[#Cannon|Cannon]]
* [[#DGun|Dgun]]
* [[#EmgCannon|EmgCannon]]
* [[#Flame|Flame]]
* [[#LaserCannon|LaserCannon]]
* [[#LightningCannon|LightningCanon]]
* [[#Melee|Melee]]
* [[#MissileLauncher|MissileLauncher]]
* [[#Rifle|Rifle]]
* [[#Shield (WeaponType)|Shield]]
* [[#StarburstLauncher|StarburstLauncher]]
* [[#TorpedoLauncher|TorpedoLauncher]]

{{tag
|name = name
|type = string
|default = "Weapon"
|description = The descriptive name of the weapon as listed in FPS mode.}}

{{tag
|name = turret
|type = bool
|default = false
|description = Does the unit aim within an arc (up-to and including full 360Â° turret traverse) or always aim along the owner's heading?}}

{{tag
|name = noSelfDamage
|type = bool
|default = false
|description = Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.}}

{{tag
|name = impactOnly
|type = bool
|default = false
|description = Does the weapon only deal damage through direct hits and not 'splash' damage through {{taglink|areaOfEffect}}?}}

{{tag
|name = noExplode
|type = bool
|default = false
|description = Does the weapon explode on impact with a target or continue through? Note that these weapons will do damage every single frame they are inside the [[Gamedev:CollisionVolumes|collision volume]] of an object, underground or under water, massively multiplying their damage.}}

{{tag
|name = burnblow
|type = bool
|default = false
|special = lua: selfExplode
|description = Does the weapon explode when it reaches its maximum range or continue on its path? The name is an [[OTAism]].}}

{{tag
|name = range
|type = float
|default = 10.0
|description = The maximum range in [[elmo]]s that the weapon can fire at.}}

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile. Since 99.0 <code>maxVelocity</code> is a synonym.}}

{{tag
|name = reloadTime
|type = float
|default = 1.0
|description = The time in seconds between shots fired.}}

{{tag
|name = metalPerShot
|type = float
|default = 0.0
|description = Metal used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = energyPerShot
|type = float
|default = 0.0
|description = Energy used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = myGravity
|type = float
|default = 0.0
|description = Overrides the map gravity for ballistic weapons. The default of <code>0.0</code> disables the tag in favour of map gravity.}}

{{tag
|name = fireStarter
|type = float
|default = 0.0
|description = The percentage chance (<code>0.0</code> to <code>100.0</code>) of the weapon setting fire to static map features on impact.}}

{{tag
|name = cameraShake
|type = float
|default = damage (0.0 for paralyzers)
|description = Passed to the [[LuaCallinReturn#Game_Events:|ShockFront() callin]] as the first argument. Intended as a means to make the camera shake if in range of detonation.}}

{{tag
|name = stockpile
|type = bool
|default = false
|description = Does each round of the weapon have to be built and stockpiled by the player? Will only correctly function for the first of each stockpiled weapons a unit has.}}

{{tag
|name = stockpileTime
|type = float
|default = reloadTime
|description = The time in seconds taken to stockpile one round of the weapon.}}

{{tag
|name = interceptedByShieldType
|type = int
|default = Depends on {{taglink|weaponType}}
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of shields that can intercept this weapon. Each digit of binary that is set to one means that a shield with the corresponding digit in its {{taglink|interceptType}} will intercept this weapon. A value of <code>0</code> means that no shields will intercept the weapon. The defaults are as follows:
* <code>0</code> - [[#DGun]]
* <code>1</code> - [[#Cannon]] and [[#EmgCannon]]
* <code>2</code> - [[#LaserCannon]] and [[#BeamLaser]]
* <code>4</code> - [[#MissileLauncher]] and [[#StarburstLauncher]]
* <code>8</code> - [[#AircraftBomb]]
* <code>16</code> - [[#Flame]]
* <code>32</code> - [[#TorpedoLauncher]]
* <code>64</code> - [[#LightningCannon]]
* <code>128</code> - [[#Rifle]]
* <code>256</code> - [[#Melee]]
(See [[Shield Interception Tag Use]]).}}

====Collision & Avoidance====

{{tag
|name = avoidGround
|type = bool
|default = true
|description = Should the weapon avoid firing if terrain blocks the line of fire?}}

{{tag
|name = avoidFriendly
|type = bool
|default = true
|description = Should the weapon avoid firing if a friendly unit is in the line of fire?}}

{{tag
|name = avoidFeature
|type = bool
|default = true
|description = Should the weapon avoid firing if a static map feature is in the line of fire?}}

{{tag
|name = avoidNeutral
|type = bool
|default = false
|description = Should the weapon avoid firing if a neutral unit is in the line of fire?}}

{{tag
|name = collideEnemy
|type = bool
|default = true
|special = lua: noEnemyCollide
|description = Does the weapon projectile collide with enemy units or pass through?}}

{{tag
|name = collideFriendly
|type = bool
|default = true
|special = lua: noFriendlyCollide
|description = Does the weapon projectile collide with friendly units or pass through?}}

{{tag
|name = collideFeature
|type = bool
|default = true
|special = lua: noFeatureCollide
|description = Does the weapon projectile collide with static map features or pass through?}}

{{tag
|name = collideNeutral
|type = bool
|default = true
|special = lua: noNeutralCollide
|description = Does the weapon projectile collide with neutral units or pass through?}}

{{tag
|name = collideGround
|type = bool
|default = true
|special = lua: noGroundCollide
|description = Does the weapon projectile collide with terrain or pass through?}}

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = Modifies visual size of EMG and Flame projectiles, and physical size '''only''' for hitscan interceptor weapons (e.g. antinuke lasers). [[https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 1]][[https://github.com/spring/spring/blob/master/rts/Sim/Misc/CollisionHandler.cpp#L33 2]]}}

====Targeting & Accuracy====
{{tag
|name = commandFire
|type = bool
|default = false
|description = Determines if the weapon will automatically fire on enemy units in range or only when manually ordered to attack.}}

{{tag
|name = canAttackGround
|type = bool
|default = true
|description = Determines if the weapon can be force-fired on ground positions or only fire on targeted units.}}

{{tag
|name = waterWeapon
|type = bool
|default = false
|description = Determines if the weapon can pass through water and target underwater units.}}

{{tag
|name = fireSubmersed
|type = bool
|default = waterWeapon
|description = Determines if the weapon can fire whilst underwater.}}

{{tag
|name = targetBorder
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon aims for the centre or the edge of its target's [[Gamedev:CollisionVolumes|collision volume]]. Clamped between <code>-1.0</code> - target the far border, and <code>1.0</code> - target the near border.}}

{{tag
|name = cylinderTargeting
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of this tag multiplied by the {{taglink|range}}. Clamped between <code>0.0</code> and <code>128.0</code>.}}

{{tag
|name = tolerance
|type = float
|default = 3000.0 (+/- ~18 degrees)
|description = The amount (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For {{taglink|turret|false}} or {{taglink|fixedLauncher|true}} weapons this determines in what arc the unit will fire.}}

{{tag
|name = fireTolerance
|type = float
|default = 32768.0 (+/- 180 degrees)
|special = {{new|99.0}}
|description = Final check to prevent weapons from shooting sideways. If a weapon is about to fire but the difference between its old aim and requested aim is greater than this angle (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) then it will not fire.}}

{{tag
|name = allowNonBlockingAim
|type = bool
|default = false
|special = {{new|99.0}}
|description = When enabled it makes [[Animation-LuaCallins#Weapons|AimWeapon()]] script calls non-blocking (still the {{taglink|fireTolerance}} tag might prevent the weapon firing). This is very useful for fast units that need to re-target often.}}

{{tag
|name = targetMoveError
|type = float
|default = 0.0
|description = The degree to which a weapon's aiming will fail to keep up with its target's movement. If set very low or not set at all, a weapon will lead its target and almost always hit.}}

{{tag
|name = leadLimit
|type = float
|default = -1.0
|description = Limits the maximum distance a unit will lead a target. The default of <code>-1</code> allows an infinite distance.}}

{{tag
|name = leadBonus
|type = float
|default = 0.0
|description = Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the {{taglink|leadLimit}}.}}

{{tag
|name = predictBoost
|type = float
|default = 0.0 (0.5 for {{taglink|burnblow|true}} weapons)
|description = Controls how well the weapon predicts unit speeds. Works in a similar way to {{taglink|targetMoveError}} except that it is 1-dimensional. This tag spreads the shots in a line based on the direction of the target whereas {{taglink|targetMoveError}} spreads the shots all around based on the movement.}}

{{tag
|name = heightMod
|type = float
|default = 0.2 (0.8 for [[#Cannon]], 1.0 for [[#BeamLaser]] and [[#LightningCannon]])
|description = Changes the spherical weapon range into an ellipsoid. Values above <code>1.0</code> mean the weapon cannot target as high as it can far, values below <code>1.0</code> mean it can target higher than it can far. For example <code>0.5</code> would allow the weapon to target twice as high as far.}}

{{tag
|name = proximityPriority
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance to the target in the priority calculation. Note that negative values make weapons prefer distant targets.}}

{{tag
|name = accuracy
|type = float
|default = 0.0
|description = How accurate the weapon is. Lower values are more accurate. Accuracy is relative to the distance to the target; for instance, if the target is very close, even a very high value will probably still hit. If a target is very far away, even a very low value will likely cause the weapon to miss.}}

{{tag
|name = movingAccuracy
|type = float
|default = accuracy
|description = A weapon's {{taglink|accuracy}} whilst the owning unit is moving.}}

{{tag
|name = sprayAngle
|type = float
|default = 0.0
|description = How wide the the angle of a burst from a [[#Bursts|burst weapon]] can be. Very similar to {{taglink|accuracy}}, except that this tag affects each projectile in a burst, whilst the former does not.}}

{{tag
|name = ownerExpAccWeight
|type = float
|default = 0.0 (See description)
|description = A multiplier to {{taglink|accuracy}} and {{taglink|sprayAngle}} that reduces inaccuracy as a units experience increases. Defaults are as follows:
* <code>0.9</code> - [[#Cannon]], [[#Rifle]]
* <code>0.7</code> - [[#LaserCannon]], [[#BeamLaser]], [[#StarburstLauncher]]
* <code>0.5</code> - [[#MissileLauncher]], [[#LightningCannon]], [[#EmgCannon]], [[#DGun]]
* <code>0.2</code> - [[#Flame]]
}}

{{tag
|name = targetable
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapon that can intercept this weapon. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptor}} tag will intercept this weapon. Instant-hitting weapons such as [[#BeamLaser]], [[#LightningCannon]] and [[#Rifle]] cannot be targeted.
}}

{{tag
|name = interceptor
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this weapon can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|targetable}} tag will be intercepted by this weapon.
}}

{{tag
|name = interceptSolo
|type = bool
|default = true
|special = {{new|92.0}}
|description = If <code>true</code> no other interceptors may target the same projectile.
}}

{{tag
|name = coverage
|type = float
|default = 0.0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = The radius in [[elmo]]s within which an {{taglink|interceptor}} weapon will fire on {{taglink|targetable}} weapons.
}}

====Bouncing====

{{tag
|name = waterBounce
|type = bool
|default = false
|description = Does the weapon bounce on water impacts?}}

{{tag
|name = groundBounce
|type = bool
|default = false
|description = Does the weapon bounce on ground impacts?}}

{{tag
|name = bounceSlip
|type = float
|default = 1.0
|description = The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.}}

{{tag
|name = bounceRebound
|type = float
|default = 1.0
|description = The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.}}

{{tag
|name = numBounce
|type = int
|default = -1
|description = The number of times the weapon will bounce on impact before exploding. The default value of <code>-1</code> allows infinite bounces (at least until velocity reaches 0).}}

====Area Of Effect, Impulse & Cratering====

{{tag
|name = areaOfEffect
|type = float
|default = 8.0 * 0.5
|special = lua: damageAreaOfEffect
|description = The ''diameter'' in [[elmo]]s in which the weapons explosion will cause damage.}}

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering. Behaviour changed slightly in 98.0 as previously craters were 1.5x {{taglink|craterAreaOfEffect}} whilst decals were 1.0x, they are now both the same size.}}

{{tag
|name = edgeEffectiveness
|type = float
|default = 0.0
|description = Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's {{taglink|areaOfEffect}}. Falls off from the epicentre according to the formula <code>damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))]</code>, a graph of the function for various values is available [[Media:EdgeEffectiveness.png|here]].}}

{{tag
|name = explosionSpeed
|type = float
|default = See description
|description = The speed at which the weapon's explosion propagates from the epicentre. The default is calculated by this complex formula: <code>defExpSpeed = {8.0 + [max(30.0, default_damage / 20.0) * 2.5]} / {9.0f + [sqrt(max(30.0, default_damage / 20.0f)) * 0.7]} * 0.5</code>.}}

{{tag
|name = impulseFactor
|type = float
|default = 1.0
|description = A multiplier to the impulse given to units within the explosion {{taglink|areaOfEffect}}, which is otherwise equal to the damage dealt after {{taglink|edgeEffectiveness}} is taken into account. For [[#Melee]] weapons this is instead multiplied by the owning unit's mass (See [[Gamedev:UnitDefs#Tag:mass|Gamedev:UnitDefs]]).}}

{{tag
|name = impulseBoost
|type = float
|default = 0.0
|description = A constant amount added to the weapon's impulse, regardless of distance from the epicentre or the damage potential of the explosion, prior to the application of {{taglink|impulseFactor}}}}

{{tag
|name = craterMult
|type = float
|default = impulseFactor
|description = A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.}}

{{tag
|name = craterBoost
|type = float
|default = 0.0
|description = A constant amount, added to the weapon's cratering depth before the application of {{taglink|craterMult}}.}}

====Bursts====

{{tag
|name = burst
|type = int
|default = 1
|special = lua: salvoSize
|description = How many shots to fire per burst.
}}

{{tag
|name = burstRate
|type = float
|default = 0.1
|special = lua: salvoDelay
|description = The time in seconds between shots in a burst. Note that {{taglink|reloadTime}} starts to count down from the ''first'' round fired, not the last so if <code>reloadTime < burst * burstRate</code> the weapon will fire continuously.
}}

{{tag
|name = projectiles
|type = int
|default = 1
|description = How many projectiles released per shot (shotgun style). e.g. a weapon with {{taglink|burst|5}}, {{taglink|burstRate|0.5}} and {{taglink|projectiles|2}} will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for {{taglink|reloadTime}}. Best used in conjunction with {{taglink|sprayAngle}} or changing the firing piece using [[Animation-LuaCallins#Weapons|ShotX]] as otherwise they'll all be clumped in one shot.
}}

====Paralyzing====
{{tag
|name = paralyzer
|type = bool
|default = false
|description = Is the weapon a paralyzer? If <code>true</code> the weapon only stuns enemy units and does not cause damage in the form of lost hit-points.
}}

{{tag
|name = paralyzeTime
|type = int
|default = 10
|special = lua: damages.paralyzeDamageTime
|description = Determines the maximum length of time in seconds that the target will be paralyzed. The timer is restarted every time the target is hit by the weapon. Cannot be less than <code>0</code>.
}}

====Dynamic Damage====
The following set of tags allow for a weapon's damage potential to vary with the distance to its target.

{{tag
|name = dynDamageExp
|type = float
|default = 0.0
|description = Exponent of the range-dependent damage formula, the default of <code>0.0</code> disables dynamic damage, <code>1.0</code> means linear scaling, <code>2.0</code> quadratic and so on.
}}

{{tag
|name = dynDamageMin
|type = float
|default = 0.0
|description = The minimum floor value that range-dependent damage can drop to.
}}

{{tag
|name = dynDamageRange
|type = float
|default = 0.0
|description = If set to non-zero values the weapon will use this value in the range-dependant damage formula instead of the actual {{taglink|range}}.
}}

{{tag
|name = dynDamageInverted
|type = bool
|default = false
|description = If <code>true</code> the damage curve is inverted i.e. the weapon does more damage at greater ranges as opposed to less.
}}

====Sounds====
{{tag
|name = soundTrigger
|type = bool
|default = false (true for [[#Melee]], [[#Rifle]] and non-beamBurst [[#BeamLaser]])
|description = Does the weapon play {{taglink|soundStart}} only once for each salvo (<code>true</code>) or for every round in a burst (<code>false</code>)?}}

{{tag
|name = soundStart
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon fires.}}

{{tag
|name = soundHitDry
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with solid ground. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

{{tag
|name = soundHitWet
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with water. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

====Visuals====

{{tag
|name = cegTag
|type = string
|default = ""
|description = The name, without prefixes, of a [[CEG]] to be emitted by the projectile each frame.
}}

{{tag
|name = intensity
|type = float
|default = 0.9 (0.2 for [[#Cannon]])
|description = Alpha transparency for non-3D model projectiles. Lower values are more opaque, but <code>0.0</code> will cause the projectile to disappear entirely.
}}

{{tag
|name = model
|type = string
|default = ""
|description = The filename of a 3D model to use when rendering the projectile. Note that only the root piece of a projectile model is rendered. Currently only for [[#Cannon]], [[#LaserCannon]], [[#MissileLauncher]], [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = explosionScar
|type = bool
|default = false
|description = Does the weapon's explosion leave a scar decal on the ground? For all types except [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If <code>true</code> the weapon is always rendered regardless of whether or not it is in LOS range of a player's units.
}}

{{tag
|name = rgbColor
|type = float[3]
|default = {1.0, 0.0, 0.0} (See Description)
|description = The primary colour for sprite rendering weapons. Additional defaults are as follows:
* [[#Cannon]] - <code>{1.0, 0.5, 0.0}</code>
* [[#EmgCannon]] - <code>{0.9, 0.9, 0.2}</code>
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of a [[CEG]], with <code>custom:</code> prefix, to spawn as the weapon's explosion. Does not currently work for [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = bounceExplosionGenerator
|type = string
|default = ""
|description = For weapons which can use {{taglink|groundBounce|true}}, the name of a [[CEG]], with <code>custom:</code> prefix, to spawn when weapon the bounces.
}}

{{tag
|name = texture1
|type = string
|default = ""
|description = The projectile texture for [[#AircraftBomb]], [[#Cannon]], [[#EmgCannon]], [[#Flame]]; beam texture for [[#LaserCannon]], [[#BeamLaser]], [[#LightningCannon]]; flare texture for [[#MissileLauncher]], [[#StarburstLauncher]] and dome texture for the [[#Shield]].
}}

{{tag
|name = texture2
|type = string
|default = ""
|description = The end-of-beam texture for [[#LaserCannon]], [[#BeamLaser]] and {{taglink|smoketrail}} texture for [[#MissileLauncher]], [[#StarburstLauncher]].
}}

{{tag
|name = texture3
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]], or muzzle texture if {{taglink|largeBeamLaser|true}}. Also used as the flame texture for [[#StarburstLauncher]].
}}

{{tag
|name = texture4
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]] with {{taglink|largeBeamLaser|true}}.
}}

===AircraftBomb===
Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. Visually drawn as a billboarded sprite as used by the [[#Cannon]], but more commonly used with a 3D model.

There are no tags specific to this '''WeaponType'''

====AircraftBomb Visuals====

When not using a {{taglink|model}}, the AircraftBomb is the same as [[#Cannon Visuals]].

===BeamLaser===
An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be [[Animation-LuaCallouts#Effects|script emitted]] if it has a {{taglink|beamTime}} longer than one frame. Visually drawn as a [http://en.wikipedia.org/wiki/Star_Trek Star Trek] Phaser-style laser weapon. The {{taglink|largeBeamLaser}} tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

{{tag
|name = minIntensity
|type = float
|default = 0.0
|description = The minimum percentage the weapon's damage can fall-off to over its range. Setting to <code>1.0</code> will disable fall off entirely. Unrelated to the visual-only {{taglink|intensity}} tag.
}}

{{tag
|name = beamTime
|type = float
|default = 1.0
|description = How long in seconds to fire the laser before waiting for {{taglink|reloadTime}} to start. Damage is distributed over the duration of the {{taglink|beamTime}}, and the weapon will aim to hit the target when the beam is in the middle of its {{taglink|beamTime}} (i.e. using prediction).
}}

{{tag
|name = beamBurst
|type = bool
|default = false
|description = Makes the laser fire a burst of beams that are all aimed towards the target (instead of aimed with the piece). A [[#BeamLaser]] can do its full damage with every shot if {{taglink|beamBurst}} is enabled. Disables {{taglink|beamTime}} in favour of the [[#Bursts|burst tags]].
}}

{{tag
|name = sweepFire
|type = bool
|default = false
|description = Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Reimplemented in 95.0, still has no script interaction so use with care. Respects {{taglink|reloadTime}} constraint but not much else.
}}

====BeamLaser Visuals====

See also {{taglink|thickness}} and {{taglink|coreThickness}}.

{{tag
|name = beamTTL
|type = int
|default = 0
|description = The time in frames for which the laser beam remains visible.
}}

{{tag
|name = beamDecay
|type = float
|default = 1.0
|description = How fast the beam fades out. Each frame the {{taglink|intensity}} is multiplied by this value.
}}

{{tag
|name = laserFlareSize
|type = float
|default = 15.0
|description = Determines the size of the firing flare.
}}

{{tag
|name = largeBeamLaser
|type = bool
|default = false
|description = Changes the visual effect allowing tiling and scrolling of the texture and a pulsating firing flare.
}}

{{tag
|name = tileLength
|type = float
|default = 200.0
|description = Defines the length before the texture used is repeated (tiled). Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = scrollSpeed
|type = float
|default = 5.0
|description = Controls how fast the texture scrolls. Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = pulseSpeed
|type = float
|default = 1.0
|description = Controls how fast the pulsating effect at the start of the beam is. Only if {{taglink|largeBeamLaser|true}}.
}}

===Cannon===
The default '''WeaponType'''. Fires a ballistic projectile, for the best result (without under/overshooting) the {{taglink|weaponVelocity}} should be set so as to give an elevation of 45Â° when firing at the maximum {{taglink|range}}. Substituting the angle into the [http://en.wikipedia.org/wiki/Trajectory#Range_and_height trajectory equation] and rearranging, we get:
<code><pre>weaponVelocity = âˆš(range * g)</pre></code>
where <code>g</code> is the map gravity, usually around <code>120</code> for most Spring maps (You can use the {{taglink|myGravity}} tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

{{tag
|name = highTrajectory
|type = int
|default = 2
|description = Can this weapon be fired in a high trajectory (>45Â° angle). Can be <code>0</code> - low trajectory only, <code>1</code> - high trajectory only or <code>2</code> - enables a high/low toggle button on the unit.
}}

{{tag
|name = heightBoostFactor
|type = float
|default = -1.0
|description = Controls the boost given to {{taglink|range}} by high terrain. Values > <code>1.0</code> result in increased range, <code>0.0</code> means the cannon has fixed range regardless of height difference to target. Any value < <code>0.0</code> (i.e. the default value) result in an automatically calculated value based on {{taglink|range}} and theoretical maximum range.
}}

====Cannon Visuals====

{{tag
|name = size
|type = float
|default = 2.0 + min(default_damage * 0.0025, {{taglink|areaOfEffect}} * 0.1)
|description = The drawing radius of the billboarded sprite. Also for [[#AircraftBomb Visuals]], [[#EmgCannon Visuals]] (default: <code>3.0</code>) and [[#Flame Visuals]].
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = A set of RGB colours to transition between over the projectile's lifetime. Can be given as a string of RGB digits or an image filename (See [[CColorMap]]). Also for [[#Flame Visuals]].
}}

{{tag
|name = sizeDecay
|type = float
|default = 0.0
|description = How quickly each particle of the Cannon shot decays in size.
}}

{{tag
|name = alphaDecay
|type = float
|default = 1.0
|description = How quickly each particle of the Cannon shot fades out.
}}

{{tag
|name = separation
|type = float
|default = 0.0
|description = The distance between each particle of the Cannon shot.
}}

{{tag
|name = noGap
|type = bool
|default = true
|description = Switch between the distance between particles being proportional to the size of the two particles (<code>true</code>) or proportional to the size of the first particle (<code>false</code>).
}}

{{tag
|name = stages
|type = int
|default = 5
|description = The number of particles in each Cannon shot.
}}

===DGun===
Fires a line-of-sight or ballistic projectile (selected via the {{taglink|gravityAffected}} tag). Visually represented by a fireball effect that cannot be customised, however it can be replaced by a 3D model. The name and visual effect are [[OTAism]]s.

{{tag
|name = gravityAffected
|type = bool
|default = false
|description = Does the fireball projectile lose height due to map gravity?
}}

===EmgCannon===
A line-of-sight weapon. Visually drawn as a billboarded sprite very similar to that of the [[#Cannon]], however not as customisable, or a 3D model. The name is another [[OTAism]].

There are no tags specific to this '''WeaponType'''.

===Flame===
A line-of-sight weapon intended for use as a flamethrower or similar. Visually drawn as a stream of textured particles, the colour of which can be controlled very precisely using the {{taglink|colorMap}} tag (see [[CColorMap]]).

====Flame Visuals====
See also {{taglink|colorMap}}.

{{tag
|name = sizeGrowth
|type = float
|default = 0.5
|description = How much the draw radius of the flame projectile increases each frame.
}}

{{tag
|name = flameGFXTime
|type = float
|default = 1.2
|description = Makes the flamethrower projectile stay alive as a visual-only effect (i.e. does not deal any damage) after it has reached maximum {{taglink|range}}. It is a percentage multiplier, e.g. <code>1.2</code> makes the projectile stay alive until it reaches 20% beyond {{taglink|range}}.
}}

===LaserCannon===
A particularly versatile line-of-sight weapon. Visually drawn like a [http://en.wikipedia.org/wiki/Star_Wars Star Wars] Blaster-style laser weapon, or a 3D model.

====LaserCannon Visuals====

{{tag
|name = duration
|type = float
|default = 0.05
|description = Multiplied against {{taglink|weaponVelocity}} to determine the visual length of the beam projectile.
}}

{{tag
|name = hardStop
|type = bool
|default = false
|description = Does the laser projectile stop dead or fade out?
}}

{{tag
|name = fallOffRate
|type = float
|default = 0.5
|description = Rate at which the beam fades out after it goes past its maximum {{taglink|range}} if {{taglink|hardStop|false}}. A value of <code>0.0</code> is never fade out, <code>1.0</code> is finish fading out exactly at maximum {{taglink|range}}.
}}

{{tag
|name = lodDistance
|type = int
|default = 1000
|description = Minimum camera distance at which the default LaserCannon projectile is simplified to a single rectangle.
}}

{{tag
|name = thickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = coreThickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = rgbColor2
|type = float
|default = {1.0, 1.0, 1.0}
|description = The colour of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

===LightningCannon===
An instant-hit weapon similar to the [[#BeamLaser]], but which does all its damage at once. Visually drawn like [http://en.wikipedia.org/wiki/Star_Wars Star Wars] 'Force Lightning' or [http://en.wikipedia.org/wiki/Command_%26_Conquer:_Red_Alert CnC: Red Alert] [http://en.wikipedia.org/wiki/Tesla_coil Tesla Coil] weapons, the effect is not very customisable.

There are no tags specific to this '''WeaponType'''.

===Melee===
A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters [http://en.wikipedia.org/wiki/Melee#Use_in_gaming 'melee'] weapon. It does not fire a projectile and does not care about the line of fire.

There are no tags specific to this '''WeaponType'''.

===MissileLauncher===
A versatile weapon which can optionally track targets and accelerate from a low initial velocity. It can also use {{taglink|trajectoryHeight}} to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = startVelocity
|type = float
|default = 0.0
|description = The initial velocity of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = weaponAcceleration
|type = float
|default = 0.0
|description = The initial acceleration of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Note that if it is <code>0.0</code> the weapon can never increase from its {{taglink|startVelocity}} and will not reach its maximum {{taglink|weaponVelocity}}. Since 99.0 <code>acceleration</code> is a synonym.
}}

{{tag
|name = tracks
|type = bool
|default = false
|description = Can the weapon projectile track a moving target? Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = The rate (in [[Elmo#Angular|cau]]) at which {{taglink|tracks|true}} weapons turn towards their target. This is relative to a projectile's current velocity; a weapon with a higher velocity will need a higher value in order to be able to hit targets that turn suddenly.}}

{{tag
|name = flightTime
|type = float
|default = 0.0
|description = The time in seconds before a missile projectile's fuel runs out; it ceases to obey {{taglink|tracks}}, loses velocity and falls to the ground. Also for [[#StarburstLauncher]]. Large values may cause over/undershoot problems.
}}

{{tag
|name = fixedLauncher
|type = bool
|default = false
|description = Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Weapons may not correctly obey [[#Collision & Avoidance|avoidance settings]] when using this tag.
}}

{{tag
|name = wobble
|type = float
|default = 0.0
|description = Adds a random vector to the direction of travel every 16 frames, multiplied by the value of the tag. The effect is reduced as the firing unit gains experience. As this missiles direction is changed, wobbling swarm of missiles will diverge.
}}

{{tag
|name = dance
|type = float
|default = 0.0
|description = Adds a random vector to the position of a missile projectile every 8 frames, multiplied by the value of the tag. As the projectile is not rotated, a dancing swarm of missiles will remain relatively coherent.
}}

{{tag
|name = trajectoryHeight
|type = float
|default = 0.0
|description = Determines the height of the arc the missile will reach as it moves towards its target. A value of <code>0.0</code> will result in a flat trajectory, <code>1.0</code> will launch at 45°. Can be any value >= <code>0.0</code>; extreme values may require the {{taglink|tracks}} tag to be able to hit a target.
}}

====MissileLauncher Visuals====
A note about the missile exhaust flare: the size of the flare is determined by the model radius. The emit position of the flare is at (0,0,-radius) so the model may need careful adjustment to get the flare looking right.

{{tag
|name = smokeTrail
|type = bool
|default = false
|description = Does the missile projectile emit a smoke trail as it travels? Also for [[#StarburstLauncher]].
}}

===Rifle===
An instant hit weapon which does all its damage at once. Visually represented by a hardcoded tracer, firing and hitting effects. Rarely used.

There are no tags specific to this '''WeaponType'''.

===Shield (WeaponType)===
As the name suggests, not a weapon but a defensive shield. Can absorb or deflect ({{taglink|shieldrepulser|true}}) projectiles. Individual weapons can be set to be intercepted or not by the shield using a [http://en.wikipedia.org/wiki/Mask_(computing) bitmask] (see [[Shield Interception Tag Use]]). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible ({{taglink|visible|false}}).

See the [[#shield]] sub-table section for other tags specific to this type.

===StarburstLauncher===
Fires a projectile that rises vertically for {{taglink|weaponTimer}} seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. Before spring 92.0 was the only weapon that can be {{taglink|targetable}} and act as an {{taglink|interceptor}}. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = weaponTimer
|type = float
|default = 0.0
|description = The time in seconds during which the missile ascends vertically before turning towards its target.
}}

===TorpedoLauncher===
Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with {{taglink|waterWeapon|true}} so they can fire underwater and target underwater units. An aircraft carrying a [[#TorpedoLauncher]] is a special case, the weapon turns into an [[#AircraftBomb]] projectile that will spawn a torpedo projectile on impact with water. Visually represented by a pointed black cuboid, usually the default object is replaced by a 3D model.

{{tag
|name = subMissile
|type = bool
|default = false
|description = Can the torpedo leave the water and target units and positions on land?
}}

===NoWeapon===
Not actually a '''WeaponType''', but an individual weapon requested by Spring to 'fill in the gaps' if a unit claims to have a weapon which isn't actually defined. There needs to be only one of these weapons and it is created by setting {{taglink|weaponName|"NOWEAPON"}} rather than by the {{taglink|weaponType}} tag.

==Sub Tables==

===damage===
The damage subtable lists how many hit points the weapon depletes against each armor class (See [[Armordefs.lua]]). It is a key-value map of armor class names and damage values. The special <code>default</code> entry is as the name suggests the default damage applied to any unit which does not belong to a listed armor class, or to shields.

For example a weapon which deals 100 damage by default but only 50 to units in the 'tank' armor class:

<code><pre>damage = {
default = 100,
tank = 50,
}</pre></code>

===shield===
The preferred way to create a shield or repulser is to use the shield subtable rather than the old shield tags.

The following tags are repulser specific:

{{tag
|name = shieldrepulser
|type = bool
|default = false
|description = Does the shield [http://dictionary.reference.com/browse/repulse?s=t repulse] (deflect) projectiles or absorb them? Btw its [http://springrts.com/mantis/view.php?id=4206 not repulsOr, but repulsEr]!}}

{{tag
|name = shieldForce
|type = float
|default = 0.0
|description = The force applied by the repulser to the weapon - higher values will deflect weapons away at higher velocities.}}

{{tag
|name = shieldMaxSpeed
|type = float
|default = 0.0
|description = The maximum speed the repulser will impart to deflected projectiles.}}

{{tag
|name = visibleShieldRepulse
|type = bool
|default = false
|description = Is the (hard-coded) repulse effect rendered or not?}}

The following tags are general behaviour for all shields:

{{tag
|name = shieldInterceptType
|type = int
|default = 0
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this shield can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptedByShieldType}} will be intercepted by this shield (See [[Shield Interception Tag Use]]).}}

{{tag
|name = armorType
|type = string
|default = ""
|description = Specifies the armorclass of the shield; you can input either an [[Armordefs.lua|armorclass]] name OR a unitdef {{xtaglink|Gamedev:UnitDefs|name}} to share that unit's armorclass.}}

{{tag
|name = smartShield
|type = bool
|default = false
|description = Determines whether or not projectiles fired by allied units can pass through the shield (<code>true</code>) or are intercepted as enemy weapons are (<code>false</code>).}}

{{tag
|name = exteriorShield
|type = bool
|default = false
|description = Determines whether or not projectiles fired within the shield's radius can pass through the shield (<code>true</code>) or are intercepted (<code>false</code>).}}

{{tag
|name = shieldEnergyUse
|type = float
|default = 0.0
|description = The amount of the energy resource consumed by the shield to absorb or repulse weapons, continually drained by a repulser as long as the projectile is in range.}}

{{tag
|name = shieldRadius
|type = float
|default = 0.0
|description = The radius of the circular area the shield covers.}}

{{tag
|name = shieldPower
|type = float
|default = 0.0
|description = Essentially the maximum allowed hit-points of the shield - reduced by the <code>damage</code> of a weapon upon impact.}}

{{tag
|name = shieldPowerRegen
|type = float
|default = 0.0
|description = How many hit-points the shield regenerates each second.}}

{{tag
|name = shieldPowerRegenEnergy
|type = float
|default = 0.0
|description = How much energy resource is consumed to regenerate each hit-point.}}

{{tag
|name = shieldRechargeDelay
|type = float
|default = 0.0
|description = The delay in seconds before a shield begins to regenerate after it is hit.}}

The following tags control the visual aspects of the shield:

{{tag
|name = visibleShield
|type = bool
|default = false
|description = Is the shield visible or not?}}

{{tag
|name = visibleShieldHitFrames
|type = int
|default = 0
|description = The number of frames a shield becomes visible for when hit.}}

{{tag
|name = shieldBadColor
|type = float[3]
|default = {1.0, 0.5, 0.5} (Red)
|description = The RGB colour the shield transitions to as its hit-points are reduced towards <code>0</code>.}}

{{tag
|name = shieldGoodColor
|type = float[3]
|default = {0.5, 0.5, 1.0} (Blue)
|description = The RGB colour the shield transitions to as its hit-points are regenerated towards its maximum {{taglink|power}}.}}

{{tag
|name = shieldAlpha
|type = float
|default = 0.2
|description = The alpha transparency of the shield whilst it is visible.}}

===customParams===
The <code>customParams</code> subtable of a WeaponDef allows the game designer to give their weapons custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
Some games may have most WeaponDefs integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]].

S44 and MC:L implement an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance].

{{ExampleRepoLinks
|path = weapons/
|entity = WeaponDefs
}}

[[Category: Game Dev]]

Gamedev:WeaponDefs

2016-03-01T22:19:54Z

Picassoct: /* https://github.com/spring/spring/blob/034a372c5017cd2f46fd57c904460a0775a59764/rts/Lua/LuaWeaponDefs.cpp */

[[Gamedev:Main|Development]] < [[Gamedev:Main]] < {{FULLPAGENAME}}

==Location==
WeaponDef files are .lua files stored in the <code>Weapons/</code> directory of a Spring Game. Alternatively they can be integrated into [[Gamedev:UnitDefs|UnitDefs]].

==Purpose==
WeaponDef files have one purpose; to define the properties of weapons. They are the main description file for what attributes your weapon should have and how it should behave. Since version 100.0, Spring will record a warning whenever it finds an unknown tag.

==Source==
The engine source code which loads the tags from these files is viewable here:

* {{sourcelink|file=rts/Sim/Weapons/WeaponDef.cpp}}

==Data Types==
{{DataTypes}}

==Details==
There follows a comprehensive (certain deprecated tags are not present) list of the tags available, their data type, default value and a brief description of what they do. Bear in mind that the source code linked above is the ultimate reference when dealing with these tags.

In lua tables keys (i.e. the tags) should be lower case, here they are represented in camelCase for readability. In your files you may use the <code>lowerkeys</code> function on your final table to ensure the keys are properly cased.

It is usual to name the returned WeaponDef table the internal <code>weaponName</code> desired for the weapon.

===Common===
The following tags are common to all or at least a majority of '''WeaponTypes''', depending on the tag.

====General====
{{tag
|name = weaponType
|type = string
|default = "Cannon"
|description = Spring has 14 '''WeaponTypes''' which provide game developers with basic behaviours which they can customise to an extent with the '''WeaponDef''' tags. Some tags are specific to certain '''WeaponTypes''' and not implemented for others, [https://docs.google.com/spreadsheet/ccc?key=0Am5BbZxm93S9dEZXc1Q4dXR4TFRYTFM4NlR4OFJFdWc#gid=0 this two-way table] indicates which tags work for which types.}} The possible values are:
* [[#AircraftBomb|AircraftBomb]]
* [[#BeamLaser|BeamLaser]]
* [[#Cannon|Cannon]]
* [[#DGun|Dgun]]
* [[#EmgCannon|EmgCannon]]
* [[#Flame|Flame]]
* [[#LaserCannon|LaserCannon]]
* [[#LightningCannon|LightningCanon]]
* [[#Melee|Melee]]
* [[#MissileLauncher|MissileLauncher]]
* [[#Rifle|Rifle]]
* [[#Shield (WeaponType)|Shield]]
* [[#StarburstLauncher|StarburstLauncher]]
* [[#TorpedoLauncher|TorpedoLauncher]]

{{tag
|name = name
|type = string
|default = "Weapon"
|description = The descriptive name of the weapon as listed in FPS mode.}}

{{tag
|name = turret
|type = bool
|default = false
|description = Does the unit aim within an arc (up-to and including full 360Â° turret traverse) or always aim along the owner's heading?}}

{{tag
|name = noSelfDamage
|type = bool
|default = false
|description = Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.}}

{{tag
|name = impactOnly
|type = bool
|default = false
|description = Does the weapon only deal damage through direct hits and not 'splash' damage through {{taglink|areaOfEffect}}?}}

{{tag
|name = noExplode
|type = bool
|default = false
|description = Does the weapon explode on impact with a target or continue through? Note that these weapons will do damage every single frame they are inside the [[Gamedev:CollisionVolumes|collision volume]] of an object, underground or under water, massively multiplying their damage.}}

{{tag
|name = burnblow
|type = bool
|default = false
|special = lua: selfExplode
|description = Does the weapon explode when it reaches its maximum range or continue on its path? The name is an [[OTAism]].}}

{{tag
|name = range
|type = float
|default = 10.0
|description = The maximum range in [[elmo]]s that the weapon can fire at.}}

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile. Since 99.0 <code>maxVelocity</code> is a synonym.}}

{{tag
|name = reloadTime
|type = float
|default = 1.0
|description = The time in seconds between shots fired.}}

{{tag
|name = metalPerShot
|type = float
|default = 0.0
|description = Metal used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = energyPerShot
|type = float
|default = 0.0
|description = Energy used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = myGravity
|type = float
|default = 0.0
|description = Overrides the map gravity for ballistic weapons. The default of <code>0.0</code> disables the tag in favour of map gravity.}}

{{tag
|name = fireStarter
|type = float
|default = 0.0
|description = The percentage chance (<code>0.0</code> to <code>100.0</code>) of the weapon setting fire to static map features on impact.}}

{{tag
|name = cameraShake
|type = float
|default = damage (0.0 for paralyzers)
|description = Passed to the [[LuaCallinReturn#Game_Events:|ShockFront() callin]] as the first argument. Intended as a means to make the camera shake if in range of detonation.}}

{{tag
|name = stockpile
|type = bool
|default = false
|description = Does each round of the weapon have to be built and stockpiled by the player? Will only correctly function for the first of each stockpiled weapons a unit has.}}

{{tag
|name = stockpileTime
|type = float
|default = reloadTime
|description = The time in seconds taken to stockpile one round of the weapon.}}

{{tag
|name = interceptedByShieldType
|type = int
|default = Depends on {{taglink|weaponType}}
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of shields that can intercept this weapon. Each digit of binary that is set to one means that a shield with the corresponding digit in its {{taglink|interceptType}} will intercept this weapon. A value of <code>0</code> means that no shields will intercept the weapon. The defaults are as follows:
* <code>0</code> - [[#DGun]]
* <code>1</code> - [[#Cannon]] and [[#EmgCannon]]
* <code>2</code> - [[#LaserCannon]] and [[#BeamLaser]]
* <code>4</code> - [[#MissileLauncher]] and [[#StarburstLauncher]]
* <code>8</code> - [[#AircraftBomb]]
* <code>16</code> - [[#Flame]]
* <code>32</code> - [[#TorpedoLauncher]]
* <code>64</code> - [[#LightningCannon]]
* <code>128</code> - [[#Rifle]]
* <code>256</code> - [[#Melee]]
(See [[Shield Interception Tag Use]]).}}

====Collision & Avoidance====

{{tag
|name = avoidGround
|type = bool
|default = true
|description = Should the weapon avoid firing if terrain blocks the line of fire?}}

{{tag
|name = avoidFriendly
|type = bool
|default = true
|description = Should the weapon avoid firing if a friendly unit is in the line of fire?}}

{{tag
|name = avoidFeature
|type = bool
|default = true
|description = Should the weapon avoid firing if a static map feature is in the line of fire?}}

{{tag
|name = avoidNeutral
|type = bool
|default = false
|description = Should the weapon avoid firing if a neutral unit is in the line of fire?}}

{{tag
|name = collideEnemy
|type = bool
|default = true
|special = lua: noEnemyCollide
|description = Does the weapon projectile collide with enemy units or pass through?}}

{{tag
|name = collideFriendly
|type = bool
|default = true
|special = lua: noFriendlyCollide
|description = Does the weapon projectile collide with friendly units or pass through?}}

{{tag
|name = collideFeature
|type = bool
|default = true
|special = lua: noFeatureCollide
|description = Does the weapon projectile collide with static map features or pass through?}}

{{tag
|name = collideNeutral
|type = bool
|default = true
|special = lua: noNeutralCollide
|description = Does the weapon projectile collide with neutral units or pass through?}}

{{tag
|name = collideGround
|type = bool
|default = true
|special = lua: noGroundCollide
|description = Does the weapon projectile collide with terrain or pass through?}}

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = Modifies visual size of EMG and Flame projectiles, and physical size '''only''' for hitscan interceptor weapons (e.g. antinuke lasers). [[https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 1]][[https://github.com/spring/spring/blob/master/rts/Sim/Misc/CollisionHandler.cpp#L33 2]]}}

====Targeting & Accuracy====
{{tag
|name = commandFire
|type = bool
|default = false
|description = Determines if the weapon will automatically fire on enemy units in range or only when manually ordered to attack.}}

{{tag
|name = canAttackGround
|type = bool
|default = true
|description = Determines if the weapon can be force-fired on ground positions or only fire on targeted units.}}

{{tag
|name = waterWeapon
|type = bool
|default = false
|description = Determines if the weapon can pass through water and target underwater units.}}

{{tag
|name = fireSubmersed
|type = bool
|default = waterWeapon
|description = Determines if the weapon can fire whilst underwater.}}

{{tag
|name = targetBorder
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon aims for the centre or the edge of its target's [[Gamedev:CollisionVolumes|collision volume]]. Clamped between <code>-1.0</code> - target the far border, and <code>1.0</code> - target the near border.}}

{{tag
|name = cylinderTargeting
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of this tag multiplied by the {{taglink|range}}. Clamped between <code>0.0</code> and <code>128.0</code>.}}

{{tag
|name = tolerance
|type = float
|default = 3000.0 (+/- ~18 degrees)
|description = The amount (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For {{taglink|turret|false}} or {{taglink|fixedLauncher|true}} weapons this determines in what arc the unit will fire.}}

{{tag
|name = fireTolerance
|type = float
|default = 32768.0 (+/- 180 degrees)
|special = {{new|99.0}}
|description = Final check to prevent weapons from shooting sideways. If a weapon is about to fire but the difference between its old aim and requested aim is greater than this angle (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) then it will not fire.}}

{{tag
|name = allowNonBlockingAim
|type = bool
|default = false
|special = {{new|99.0}}
|description = When enabled it makes [[Animation-LuaCallins#Weapons|AimWeapon()]] script calls non-blocking (still the {{taglink|fireTolerance}} tag might prevent the weapon firing). This is very useful for fast units that need to re-target often.}}

{{tag
|name = targetMoveError
|type = float
|default = 0.0
|description = The degree to which a weapon's aiming will fail to keep up with its target's movement. If set very low or not set at all, a weapon will lead its target and almost always hit.}}

{{tag
|name = leadLimit
|type = float
|default = -1.0
|description = Limits the maximum distance a unit will lead a target. The default of <code>-1</code> allows an infinite distance.}}

{{tag
|name = leadBonus
|type = float
|default = 0.0
|description = Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the {{taglink|leadLimit}}.}}

{{tag
|name = predictBoost
|type = float
|default = 0.0 (0.5 for {{taglink|burnblow|true}} weapons)
|description = Controls how well the weapon predicts unit speeds. Works in a similar way to {{taglink|targetMoveError}} except that it is 1-dimensional. This tag spreads the shots in a line based on the direction of the target whereas {{taglink|targetMoveError}} spreads the shots all around based on the movement.}}

{{tag
|name = heightMod
|type = float
|default = 0.2 (0.8 for [[#Cannon]], 1.0 for [[#BeamLaser]] and [[#LightningCannon]])
|description = Changes the spherical weapon range into an ellipsoid. Values above <code>1.0</code> mean the weapon cannot target as high as it can far, values below <code>1.0</code> mean it can target higher than it can far. For example <code>0.5</code> would allow the weapon to target twice as high as far.}}

{{tag
|name = proximityPriority
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance to the target in the priority calculation. Note that negative values make weapons prefer distant targets.}}

{{tag
|name = accuracy
|type = float
|default = 0.0
|description = How accurate the weapon is. Lower values are more accurate. Accuracy is relative to the distance to the target; for instance, if the target is very close, even a very high value will probably still hit. If a target is very far away, even a very low value will likely cause the weapon to miss.}}

{{tag
|name = movingAccuracy
|type = float
|default = accuracy
|description = A weapon's {{taglink|accuracy}} whilst the owning unit is moving.}}

{{tag
|name = sprayAngle
|type = float
|default = 0.0
|description = How wide the the angle of a burst from a [[#Bursts|burst weapon]] can be. Very similar to {{taglink|accuracy}}, except that this tag affects each projectile in a burst, whilst the former does not.}}

{{tag
|name = ownerExpAccWeight
|type = float
|default = 0.0 (See description)
|description = A multiplier to {{taglink|accuracy}} and {{taglink|sprayAngle}} that reduces inaccuracy as a units experience increases. Defaults are as follows:
* <code>0.9</code> - [[#Cannon]], [[#Rifle]]
* <code>0.7</code> - [[#LaserCannon]], [[#BeamLaser]], [[#StarburstLauncher]]
* <code>0.5</code> - [[#MissileLauncher]], [[#LightningCannon]], [[#EmgCannon]], [[#DGun]]
* <code>0.2</code> - [[#Flame]]
}}

{{tag
|name = targetable
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapon that can intercept this weapon. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptor}} tag will intercept this weapon. Instant-hitting weapons such as [[#BeamLaser]], [[#LightningCannon]] and [[#Rifle]] cannot be targeted.
}}

{{tag
|name = interceptor
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this weapon can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|targetable}} tag will be intercepted by this weapon.
}}

{{tag
|name = interceptSolo
|type = bool
|default = true
|special = {{new|92.0}}
|description = If <code>true</code> no other interceptors may target the same projectile.
}}

{{tag
|name = coverage
|type = float
|default = 0.0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = The radius in [[elmo]]s within which an {{taglink|interceptor}} weapon will fire on {{taglink|targetable}} weapons.
}}

====Bouncing====

{{tag
|name = waterBounce
|type = bool
|default = false
|description = Does the weapon bounce on water impacts?}}

{{tag
|name = groundBounce
|type = bool
|default = false
|description = Does the weapon bounce on ground impacts?}}

{{tag
|name = bounceSlip
|type = float
|default = 1.0
|description = The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.}}

{{tag
|name = bounceRebound
|type = float
|default = 1.0
|description = The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.}}

{{tag
|name = numBounce
|type = int
|default = -1
|description = The number of times the weapon will bounce on impact before exploding. The default value of <code>-1</code> allows infinite bounces (at least until velocity reaches 0).}}

====Area Of Effect, Impulse & Cratering====

{{tag
|name = areaOfEffect
|type = float
|default = 8.0 * 0.5
|special = lua: damageAreaOfEffect
|description = The ''diameter'' in [[elmo]]s in which the weapons explosion will cause damage.}}

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering. Behaviour changed slightly in 98.0 as previously craters were 1.5x {{taglink|craterAreaOfEffect}} whilst decals were 1.0x, they are now both the same size.}}

{{tag
|name = edgeEffectiveness
|type = float
|default = 0.0
|description = Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's {{taglink|areaOfEffect}}. Falls off from the epicentre according to the formula <code>damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))]</code>, a graph of the function for various values is available [[Media:EdgeEffectiveness.png|here]].}}

{{tag
|name = explosionSpeed
|type = float
|default = See description
|description = The speed at which the weapon's explosion propagates from the epicentre. The default is calculated by this complex formula: <code>defExpSpeed = {8.0 + [max(30.0, default_damage / 20.0) * 2.5]} / {9.0f + [sqrt(max(30.0, default_damage / 20.0f)) * 0.7]} * 0.5</code>.}}

{{tag
|name = impulseFactor
|type = float
|default = 1.0
|description = A multiplier to the impulse given to units within the explosion {{taglink|areaOfEffect}}, which is otherwise equal to the damage dealt after {{taglink|edgeEffectiveness}} is taken into account. For [[#Melee]] weapons this is instead multiplied by the owning unit's mass (See [[Gamedev:UnitDefs#Tag:mass|Gamedev:UnitDefs]]).}}

{{tag
|name = impulseBoost
|type = float
|default = 0.0
|description = A constant amount added to the weapon's impulse, regardless of distance from the epicentre or the damage potential of the explosion, prior to the application of {{taglink|impulseFactor}}}}

{{tag
|name = craterMult
|type = float
|default = impulseFactor
|description = A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.}}

{{tag
|name = craterBoost
|type = float
|default = 0.0
|description = A constant amount, added to the weapon's cratering depth before the application of {{taglink|craterMult}}.}}

====Bursts====

{{tag
|name = burst
|type = int
|default = 1
|special = lua: salvoSize
|description = How many shots to fire per burst.
}}

{{tag
|name = burstRate
|type = float
|default = 0.1
|special = lua: salvoDelay
|description = The time in seconds between shots in a burst. Note that {{taglink|reloadTime}} starts to count down from the ''first'' round fired, not the last so if <code>reloadTime < burst * burstRate</code> the weapon will fire continuously.
}}

{{tag
|name = projectiles
|type = int
|default = 1
|description = How many projectiles released per shot (shotgun style). e.g. a weapon with {{taglink|burst|5}}, {{taglink|burstRate|0.5}} and {{taglink|projectiles|2}} will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for {{taglink|reloadTime}}. Best used in conjunction with {{taglink|sprayAngle}} or changing the firing piece using [[Animation-LuaCallins#Weapons|ShotX]] as otherwise they'll all be clumped in one shot.
}}

====Paralyzing====
{{tag
|name = paralyzer
|type = bool
|default = false
|description = Is the weapon a paralyzer? If <code>true</code> the weapon only stuns enemy units and does not cause damage in the form of lost hit-points.
}}

{{tag
|name = paralyzeTime
|type = int
|default = 10
|special = lua: damages.paralyzeDamageTime
|description = Determines the maximum length of time in seconds that the target will be paralyzed. The timer is restarted every time the target is hit by the weapon. Cannot be less than <code>0</code>.
}}

====Dynamic Damage====
The following set of tags allow for a weapon's damage potential to vary with the distance to its target.

{{tag
|name = dynDamageExp
|type = float
|default = 0.0
|description = Exponent of the range-dependent damage formula, the default of <code>0.0</code> disables dynamic damage, <code>1.0</code> means linear scaling, <code>2.0</code> quadratic and so on.
}}

{{tag
|name = dynDamageMin
|type = float
|default = 0.0
|description = The minimum floor value that range-dependent damage can drop to.
}}

{{tag
|name = dynDamageRange
|type = float
|default = 0.0
|description = If set to non-zero values the weapon will use this value in the range-dependant damage formula instead of the actual {{taglink|range}}.
}}

{{tag
|name = dynDamageInverted
|type = bool
|default = false
|description = If <code>true</code> the damage curve is inverted i.e. the weapon does more damage at greater ranges as opposed to less.
}}

====Sounds====
{{tag
|name = soundTrigger
|type = bool
|default = false (true for [[#Melee]], [[#Rifle]] and non-beamBurst [[#BeamLaser]])
|description = Does the weapon play {{taglink|soundStart}} only once for each salvo (<code>true</code>) or for every round in a burst (<code>false</code>)?}}

{{tag
|name = soundStart
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon fires.}}

{{tag
|name = soundHitDry
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with solid ground. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

{{tag
|name = soundHitWet
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with water. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

====Visuals====

{{tag
|name = cegTag
|type = string
|default = ""
|description = The name, without prefixes, of a [[CEG]] to be emitted by the projectile each frame.
}}

{{tag
|name = intensity
|type = float
|default = 0.9 (0.2 for [[#Cannon]])
|description = Alpha transparency for non-3D model projectiles. Lower values are more opaque, but <code>0.0</code> will cause the projectile to disappear entirely.
}}

{{tag
|name = model
|type = string
|default = ""
|description = The filename of a 3D model to use when rendering the projectile. Note that only the root piece of a projectile model is rendered. Currently only for [[#Cannon]], [[#LaserCannon]], [[#MissileLauncher]], [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = explosionScar
|type = bool
|default = false
|description = Does the weapon's explosion leave a scar decal on the ground? For all types except [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If <code>true</code> the weapon is always rendered regardless of whether or not it is in LOS range of a player's units.
}}

{{tag
|name = rgbColor
|type = float[3]
|default = {1.0, 0.0, 0.0} (See Description)
|description = The primary colour for sprite rendering weapons. Additional defaults are as follows:
* [[#Cannon]] - <code>{1.0, 0.5, 0.0}</code>
* [[#EmgCannon]] - <code>{0.9, 0.9, 0.2}</code>
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of a [[CEG]], with <code>custom:</code> prefix, to spawn as the weapon's explosion. Does not currently work for [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = bounceExplosionGenerator
|type = string
|default = ""
|description = For weapons which can use {{taglink|groundBounce|true}}, the name of a [[CEG]], with <code>custom:</code> prefix, to spawn when weapon the bounces.
}}

{{tag
|name = texture1
|type = string
|default = ""
|description = The projectile texture for [[#AircraftBomb]], [[#Cannon]], [[#EmgCannon]], [[#Flame]]; beam texture for [[#LaserCannon]], [[#BeamLaser]], [[#LightningCannon]]; flare texture for [[#MissileLauncher]], [[#StarburstLauncher]] and dome texture for the [[#Shield]].
}}

{{tag
|name = texture2
|type = string
|default = ""
|description = The end-of-beam texture for [[#LaserCannon]], [[#BeamLaser]] and {{taglink|smoketrail}} texture for [[#MissileLauncher]], [[#StarburstLauncher]].
}}

{{tag
|name = texture3
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]], or muzzle texture if {{taglink|largeBeamLaser|true}}. Also used as the flame texture for [[#StarburstLauncher]].
}}

{{tag
|name = texture4
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]] with {{taglink|largeBeamLaser|true}}.
}}

===AircraftBomb===
Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. Visually drawn as a billboarded sprite as used by the [[#Cannon]], but more commonly used with a 3D model.

There are no tags specific to this '''WeaponType'''

====AircraftBomb Visuals====

When not using a {{taglink|model}}, the AircraftBomb is the same as [[#Cannon Visuals]].

===BeamLaser===
An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be [[Animation-LuaCallouts#Effects|script emitted]] if it has a {{taglink|beamTime}} longer than one frame. Visually drawn as a [http://en.wikipedia.org/wiki/Star_Trek Star Trek] Phaser-style laser weapon. The {{taglink|largeBeamLaser}} tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

{{tag
|name = minIntensity
|type = float
|default = 0.0
|description = The minimum percentage the weapon's damage can fall-off to over its range. Setting to <code>1.0</code> will disable fall off entirely. Unrelated to the visual-only {{taglink|intensity}} tag.
}}

{{tag
|name = beamTime
|type = float
|default = 1.0
|description = How long in seconds to fire the laser before waiting for {{taglink|reloadTime}} to start. Damage is distributed over the duration of the {{taglink|beamTime}}, and the weapon will aim to hit the target when the beam is in the middle of its {{taglink|beamTime}} (i.e. using prediction).
}}

{{tag
|name = beamBurst
|type = bool
|default = false
|description = Makes the laser fire a burst of beams that are all aimed towards the target (instead of aimed with the piece). A [[#BeamLaser]] can do its full damage with every shot if {{taglink|beamBurst}} is enabled. Disables {{taglink|beamTime}} in favour of the [[#Bursts|burst tags]].
}}

{{tag
|name = sweepFire
|type = bool
|default = false
|description = Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Reimplemented in 95.0, still has no script interaction so use with care. Respects {{taglink|reloadTime}} constraint but not much else.
}}

====BeamLaser Visuals====

See also {{taglink|thickness}} and {{taglink|coreThickness}}.

{{tag
|name = beamTTL
|type = int
|default = 0
|description = The time in frames for which the laser beam remains visible.
}}

{{tag
|name = beamDecay
|type = float
|default = 1.0
|description = How fast the beam fades out. Each frame the {{taglink|intensity}} is multiplied by this value.
}}

{{tag
|name = laserFlareSize
|type = float
|default = 15.0
|description = Determines the size of the firing flare.
}}

{{tag
|name = largeBeamLaser
|type = bool
|default = false
|description = Changes the visual effect allowing tiling and scrolling of the texture and a pulsating firing flare.
}}

{{tag
|name = tileLength
|type = float
|default = 200.0
|description = Defines the length before the texture used is repeated (tiled). Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = scrollSpeed
|type = float
|default = 5.0
|description = Controls how fast the texture scrolls. Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = pulseSpeed
|type = float
|default = 1.0
|description = Controls how fast the pulsating effect at the start of the beam is. Only if {{taglink|largeBeamLaser|true}}.
}}

===Cannon===
The default '''WeaponType'''. Fires a ballistic projectile, for the best result (without under/overshooting) the {{taglink|weaponVelocity}} should be set so as to give an elevation of 45Â° when firing at the maximum {{taglink|range}}. Substituting the angle into the [http://en.wikipedia.org/wiki/Trajectory#Range_and_height trajectory equation] and rearranging, we get:
<code><pre>weaponVelocity = âˆš(range * g)</pre></code>
where <code>g</code> is the map gravity, usually around <code>120</code> for most Spring maps (You can use the {{taglink|myGravity}} tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

{{tag
|name = highTrajectory
|type = int
|default = 2
|description = Can this weapon be fired in a high trajectory (>45Â° angle). Can be <code>0</code> - low trajectory only, <code>1</code> - high trajectory only or <code>2</code> - enables a high/low toggle button on the unit.
}}

{{tag
|name = heightBoostFactor
|type = float
|default = -1.0
|description = Controls the boost given to {{taglink|range}} by high terrain. Values > <code>1.0</code> result in increased range, <code>0.0</code> means the cannon has fixed range regardless of height difference to target. Any value < <code>0.0</code> (i.e. the default value) result in an automatically calculated value based on {{taglink|range}} and theoretical maximum range.
}}

====Cannon Visuals====

{{tag
|name = size
|type = float
|default = 2.0 + min(default_damage * 0.0025, {{taglink|areaOfEffect}} * 0.1)
|description = The drawing radius of the billboarded sprite. Also for [[#AircraftBomb Visuals]], [[#EmgCannon Visuals]] (default: <code>3.0</code>) and [[#Flame Visuals]].
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = A set of RGB colours to transition between over the projectile's lifetime. Can be given as a string of RGB digits or an image filename (See [[CColorMap]]). Also for [[#Flame Visuals]].
}}

{{tag
|name = sizeDecay
|type = float
|default = 0.0
|description = How quickly each particle of the Cannon shot decays in size.
}}

{{tag
|name = alphaDecay
|type = float
|default = 1.0
|description = How quickly each particle of the Cannon shot fades out.
}}

{{tag
|name = separation
|type = float
|default = 0.0
|description = The distance between each particle of the Cannon shot.
}}

{{tag
|name = noGap
|type = bool
|default = true
|description = Switch between the distance between particles being proportional to the size of the two particles (<code>true</code>) or proportional to the size of the first particle (<code>false</code>).
}}

{{tag
|name = stages
|type = int
|default = 5
|description = The number of particles in each Cannon shot.
}}

===DGun===
Fires a line-of-sight or ballistic projectile (selected via the {{taglink|gravityAffected}} tag). Visually represented by a fireball effect that cannot be customised, however it can be replaced by a 3D model. The name and visual effect are [[OTAism]]s.

{{tag
|name = gravityAffected
|type = bool
|default = false
|description = Does the fireball projectile lose height due to map gravity?
}}

===EmgCannon===
A line-of-sight weapon. Visually drawn as a billboarded sprite very similar to that of the [[#Cannon]], however not as customisable, or a 3D model. The name is another [[OTAism]].

There are no tags specific to this '''WeaponType'''.

===Flame===
A line-of-sight weapon intended for use as a flamethrower or similar. Visually drawn as a stream of textured particles, the colour of which can be controlled very precisely using the {{taglink|colorMap}} tag (see [[CColorMap]]).

====Flame Visuals====
See also {{taglink|colorMap}}.

{{tag
|name = sizeGrowth
|type = float
|default = 0.5
|description = How much the draw radius of the flame projectile increases each frame.
}}

{{tag
|name = flameGFXTime
|type = float
|default = 1.2
|description = Makes the flamethrower projectile stay alive as a visual-only effect (i.e. does not deal any damage) after it has reached maximum {{taglink|range}}. It is a percentage multiplier, e.g. <code>1.2</code> makes the projectile stay alive until it reaches 20% beyond {{taglink|range}}.
}}

===LaserCannon===
A particularly versatile line-of-sight weapon. Visually drawn like a [http://en.wikipedia.org/wiki/Star_Wars Star Wars] Blaster-style laser weapon, or a 3D model.

====LaserCannon Visuals====

{{tag
|name = duration
|type = float
|default = 0.05
|description = Multiplied against {{taglink|weaponVelocity}} to determine the visual length of the beam projectile.
}}

{{tag
|name = hardStop
|type = bool
|default = false
|description = Does the laser projectile stop dead or fade out?
}}

{{tag
|name = fallOffRate
|type = float
|default = 0.5
|description = Rate at which the beam fades out after it goes past its maximum {{taglink|range}} if {{taglink|hardStop|false}}. A value of <code>0.0</code> is never fade out, <code>1.0</code> is finish fading out exactly at maximum {{taglink|range}}.
}}

{{tag
|name = lodDistance
|type = int
|default = 1000
|description = Minimum camera distance at which the default LaserCannon projectile is simplified to a single rectangle.
}}

{{tag
|name = thickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = coreThickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = rgbColor2
|type = float
|default = {1.0, 1.0, 1.0}
|description = The colour of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

===LightningCannon===
An instant-hit weapon similar to the [[#BeamLaser]], but which does all its damage at once. Visually drawn like [http://en.wikipedia.org/wiki/Star_Wars Star Wars] 'Force Lightning' or [http://en.wikipedia.org/wiki/Command_%26_Conquer:_Red_Alert CnC: Red Alert] [http://en.wikipedia.org/wiki/Tesla_coil Tesla Coil] weapons, the effect is not very customisable.

There are no tags specific to this '''WeaponType'''.

===Melee===
A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters [http://en.wikipedia.org/wiki/Melee#Use_in_gaming 'melee'] weapon. It does not fire a projectile and does not care about the line of fire.

There are no tags specific to this '''WeaponType'''.

===MissileLauncher===
A versatile weapon which can optionally track targets and accelerate from a low initial velocity. It can also use {{taglink|trajectoryHeight}} to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = startVelocity
|type = float
|default = 0.0
|description = The initial velocity of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = weaponAcceleration
|type = float
|default = 0.0
|description = The initial acceleration of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Note that if it is <code>0.0</code> the weapon can never increase from its {{taglink|startVelocity}} and will not reach its maximum {{taglink|weaponVelocity}}. Since 99.0 <code>acceleration</code> is a synonym.
}}

{{tag
|name = tracks
|type = bool
|default = false
|description = Can the weapon projectile track a moving target? Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = The rate (in [[Elmo#Angular|cau]]) at which {{taglink|tracks|true}} weapons turn towards their target. This is relative to a projectile's current velocity; a weapon with a higher velocity will need a higher value in order to be able to hit targets that turn suddenly.}}

{{tag
|name = flightTime
|type = float
|default = 0.0
|description = The time in seconds before a missile projectile's fuel runs out; it ceases to obey {{taglink|tracks}}, loses velocity and falls to the ground. Also for [[#StarburstLauncher]]. Large values may cause over/undershoot problems.
}}

{{tag
|name = fixedLauncher
|type = bool
|default = false
|description = Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Weapons may not correctly obey [[#Collision & Avoidance|avoidance settings]] when using this tag.
}}

{{tag
|name = wobble
|type = float
|default = 0.0
|description = Adds a random vector to the direction of travel every 16 frames, multiplied by the value of the tag. The effect is reduced as the firing unit gains experience. As this missiles direction is changed, wobbling swarm of missiles will diverge.
}}

{{tag
|name = dance
|type = float
|default = 0.0
|description = Adds a random vector to the position of a missile projectile every 8 frames, multiplied by the value of the tag. As the projectile is not rotated, a dancing swarm of missiles will remain relatively coherent.
}}

{{tag
|name = trajectoryHeight
|type = float
|default = 0.0
|description = Determines the height of the arc the missile will reach as it moves towards its target. A value of <code>0.0</code> will result in a flat trajectory, <code>1.0</code> will launch at 45°. Can be any value >= <code>0.0</code>; extreme values may require the {{taglink|tracks}} tag to be able to hit a target.
}}

====MissileLauncher Visuals====
A note about the missile exhaust flare: the size of the flare is determined by the model radius. The emit position of the flare is at (0,0,-radius) so the model may need careful adjustment to get the flare looking right.

{{tag
|name = smokeTrail
|type = bool
|default = false
|description = Does the missile projectile emit a smoke trail as it travels? Also for [[#StarburstLauncher]].
}}

===Rifle===
An instant hit weapon which does all its damage at once. Visually represented by a hardcoded tracer, firing and hitting effects. Rarely used.

There are no tags specific to this '''WeaponType'''.

===Shield (WeaponType)===
As the name suggests, not a weapon but a defensive shield. Can absorb or deflect ({{taglink|shieldrepulser|true}}) projectiles. Individual weapons can be set to be intercepted or not by the shield using a [http://en.wikipedia.org/wiki/Mask_(computing) bitmask] (see [[Shield Interception Tag Use]]). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible ({{taglink|visible|false}}).

See the [[#shield]] sub-table section for other tags specific to this type.

===StarburstLauncher===
Fires a projectile that rises vertically for {{taglink|weaponTimer}} seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. Before spring 92.0 was the only weapon that can be {{taglink|targetable}} and act as an {{taglink|interceptor}}. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = weaponTimer
|type = float
|default = 0.0
|description = The time in seconds during which the missile ascends vertically before turning towards its target.
}}

===TorpedoLauncher===
Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with {{taglink|waterWeapon|true}} so they can fire underwater and target underwater units. An aircraft carrying a [[#TorpedoLauncher]] is a special case, the weapon turns into an [[#AircraftBomb]] projectile that will spawn a torpedo projectile on impact with water. Visually represented by a pointed black cuboid, usually the default object is replaced by a 3D model.

{{tag
|name = subMissile
|type = bool
|default = false
|description = Can the torpedo leave the water and target units and positions on land?
}}

===NoWeapon===
Not actually a '''WeaponType''', but an individual weapon requested by Spring to 'fill in the gaps' if a unit claims to have a weapon which isn't actually defined. There needs to be only one of these weapons and it is created by setting {{taglink|weaponName|"NOWEAPON"}} rather than by the {{taglink|weaponType}} tag.

==Sub Tables==

===damage===
The damage subtable lists how many hit points the weapon depletes against each armor class (See [[Armordefs.lua]]). It is a key-value map of armor class names and damage values. The special <code>default</code> entry is as the name suggests the default damage applied to any unit which does not belong to a listed armor class, or to shields.

For example a weapon which deals 100 damage by default but only 50 to units in the 'tank' armor class:

<code><pre>damage = {
default = 100,
tank = 50,
}</pre></code>

===shield===
The preferred way to create a shield or repulser is to use the shield subtable rather than the old shield tags.

The following tags are repulser specific:

{{tag
|name = shieldrepulser
|type = bool
|default = false
|description = Does the shield [http://dictionary.reference.com/browse/repulse?s=t repulse] (deflect) projectiles or absorb them? Btw its [http://springrts.com/mantis/view.php?id=4206 not repulsOr, but repulsEr]!}}

{{tag
|name = shieldForce
|type = float
|default = 0.0
|description = The force applied by the repulser to the weapon - higher values will deflect weapons away at higher velocities.}}

{{tag
|name = shieldMaxSpeed
|type = float
|default = 0.0
|description = The maximum speed the repulser will impart to deflected projectiles.}}

{{tag
|name = visibleShieldRepulse
|type = bool
|default = false
|description = Is the (hard-coded) repulse effect rendered or not?}}

The following tags are general behaviour for all shields:

{{tag
|name = shieldInterceptType
|type = int
|default = 0
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this shield can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptedByShieldType}} will be intercepted by this shield (See [[Shield Interception Tag Use]]).}}

{{tag
|name = armorType
|type = string
|default = ""
|description = Specifies the armorclass of the shield; you can input either an [[Armordefs.lua|armorclass]] name OR a unitdef {{xtaglink|Gamedev:UnitDefs|name}} to share that unit's armorclass.}}

{{tag
|name = smartShield
|type = bool
|default = false
|description = Determines whether or not projectiles fired by allied units can pass through the shield (<code>true</code>) or are intercepted as enemy weapons are (<code>false</code>).}}

{{tag
|name = exteriorShield
|type = bool
|default = false
|description = Determines whether or not projectiles fired within the shield's radius can pass through the shield (<code>true</code>) or are intercepted (<code>false</code>).}}

{{tag
|name = shieldEnergyUse
|type = float
|default = 0.0
|description = The amount of the energy resource consumed by the shield to absorb or repulse weapons, continually drained by a repulser as long as the projectile is in range.}}

{{tag
|name = shieldRadius
|type = float
|default = 0.0
|description = The radius of the circular area the shield covers.}}

{{tag
|name = shieldPower
|type = float
|default = 0.0
|description = Essentially the maximum allowed hit-points of the shield - reduced by the <code>damage</code> of a weapon upon impact.}}

{{tag
|name = startingPower
|type = float
|default = 0.0
|description = How many hit-points the shield starts with - otherwise the shield must regenerate from <code>0</code> until it reaches maximum {{taglink|power}}.}}

{{tag
|name = shieldPowerRegen
|type = float
|default = 0.0
|description = How many hit-points the shield regenerates each second.}}

{{tag
|name = shieldPowerRegenEnergy
|type = float
|default = 0.0
|description = How much energy resource is consumed to regenerate each hit-point.}}

{{tag
|name = shieldRechargeDelay
|type = float
|default = 0.0
|description = The delay in seconds before a shield begins to regenerate after it is hit.}}

The following tags control the visual aspects of the shield:

{{tag
|name = visibleShield
|type = bool
|default = false
|description = Is the shield visible or not?}}

{{tag
|name = visibleShieldHitFrames
|type = int
|default = 0
|description = The number of frames a shield becomes visible for when hit.}}

{{tag
|name = shieldBadColor
|type = float[3]
|default = {1.0, 0.5, 0.5} (Red)
|description = The RGB colour the shield transitions to as its hit-points are reduced towards <code>0</code>.}}

{{tag
|name = shieldGoodColor
|type = float[3]
|default = {0.5, 0.5, 1.0} (Blue)
|description = The RGB colour the shield transitions to as its hit-points are regenerated towards its maximum {{taglink|power}}.}}

{{tag
|name = shieldAlpha
|type = float
|default = 0.2
|description = The alpha transparency of the shield whilst it is visible.}}

===customParams===
The <code>customParams</code> subtable of a WeaponDef allows the game designer to give their weapons custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
Some games may have most WeaponDefs integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]].

S44 and MC:L implement an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance].

{{ExampleRepoLinks
|path = weapons/
|entity = WeaponDefs
}}

[[Category: Game Dev]]

Gamedev:WeaponDefs

2016-03-01T22:13:35Z

Picassoct: /* Shield (WeaponType) */

[[Gamedev:Main|Development]] < [[Gamedev:Main]] < {{FULLPAGENAME}}

==Location==
WeaponDef files are .lua files stored in the <code>Weapons/</code> directory of a Spring Game. Alternatively they can be integrated into [[Gamedev:UnitDefs|UnitDefs]].

==Purpose==
WeaponDef files have one purpose; to define the properties of weapons. They are the main description file for what attributes your weapon should have and how it should behave. Since version 100.0, Spring will record a warning whenever it finds an unknown tag.

==Source==
The engine source code which loads the tags from these files is viewable here:

* {{sourcelink|file=rts/Sim/Weapons/WeaponDef.cpp}}

==Data Types==
{{DataTypes}}

==Details==
There follows a comprehensive (certain deprecated tags are not present) list of the tags available, their data type, default value and a brief description of what they do. Bear in mind that the source code linked above is the ultimate reference when dealing with these tags.

In lua tables keys (i.e. the tags) should be lower case, here they are represented in camelCase for readability. In your files you may use the <code>lowerkeys</code> function on your final table to ensure the keys are properly cased.

It is usual to name the returned WeaponDef table the internal <code>weaponName</code> desired for the weapon.

===Common===
The following tags are common to all or at least a majority of '''WeaponTypes''', depending on the tag.

====General====
{{tag
|name = weaponType
|type = string
|default = "Cannon"
|description = Spring has 14 '''WeaponTypes''' which provide game developers with basic behaviours which they can customise to an extent with the '''WeaponDef''' tags. Some tags are specific to certain '''WeaponTypes''' and not implemented for others, [https://docs.google.com/spreadsheet/ccc?key=0Am5BbZxm93S9dEZXc1Q4dXR4TFRYTFM4NlR4OFJFdWc#gid=0 this two-way table] indicates which tags work for which types.}} The possible values are:
* [[#AircraftBomb|AircraftBomb]]
* [[#BeamLaser|BeamLaser]]
* [[#Cannon|Cannon]]
* [[#DGun|Dgun]]
* [[#EmgCannon|EmgCannon]]
* [[#Flame|Flame]]
* [[#LaserCannon|LaserCannon]]
* [[#LightningCannon|LightningCanon]]
* [[#Melee|Melee]]
* [[#MissileLauncher|MissileLauncher]]
* [[#Rifle|Rifle]]
* [[#Shield (WeaponType)|Shield]]
* [[#StarburstLauncher|StarburstLauncher]]
* [[#TorpedoLauncher|TorpedoLauncher]]

{{tag
|name = name
|type = string
|default = "Weapon"
|description = The descriptive name of the weapon as listed in FPS mode.}}

{{tag
|name = turret
|type = bool
|default = false
|description = Does the unit aim within an arc (up-to and including full 360Â° turret traverse) or always aim along the owner's heading?}}

{{tag
|name = noSelfDamage
|type = bool
|default = false
|description = Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.}}

{{tag
|name = impactOnly
|type = bool
|default = false
|description = Does the weapon only deal damage through direct hits and not 'splash' damage through {{taglink|areaOfEffect}}?}}

{{tag
|name = noExplode
|type = bool
|default = false
|description = Does the weapon explode on impact with a target or continue through? Note that these weapons will do damage every single frame they are inside the [[Gamedev:CollisionVolumes|collision volume]] of an object, underground or under water, massively multiplying their damage.}}

{{tag
|name = burnblow
|type = bool
|default = false
|special = lua: selfExplode
|description = Does the weapon explode when it reaches its maximum range or continue on its path? The name is an [[OTAism]].}}

{{tag
|name = range
|type = float
|default = 10.0
|description = The maximum range in [[elmo]]s that the weapon can fire at.}}

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile. Since 99.0 <code>maxVelocity</code> is a synonym.}}

{{tag
|name = reloadTime
|type = float
|default = 1.0
|description = The time in seconds between shots fired.}}

{{tag
|name = metalPerShot
|type = float
|default = 0.0
|description = Metal used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = energyPerShot
|type = float
|default = 0.0
|description = Energy used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = myGravity
|type = float
|default = 0.0
|description = Overrides the map gravity for ballistic weapons. The default of <code>0.0</code> disables the tag in favour of map gravity.}}

{{tag
|name = fireStarter
|type = float
|default = 0.0
|description = The percentage chance (<code>0.0</code> to <code>100.0</code>) of the weapon setting fire to static map features on impact.}}

{{tag
|name = cameraShake
|type = float
|default = damage (0.0 for paralyzers)
|description = Passed to the [[LuaCallinReturn#Game_Events:|ShockFront() callin]] as the first argument. Intended as a means to make the camera shake if in range of detonation.}}

{{tag
|name = stockpile
|type = bool
|default = false
|description = Does each round of the weapon have to be built and stockpiled by the player? Will only correctly function for the first of each stockpiled weapons a unit has.}}

{{tag
|name = stockpileTime
|type = float
|default = reloadTime
|description = The time in seconds taken to stockpile one round of the weapon.}}

{{tag
|name = interceptedByShieldType
|type = int
|default = Depends on {{taglink|weaponType}}
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of shields that can intercept this weapon. Each digit of binary that is set to one means that a shield with the corresponding digit in its {{taglink|interceptType}} will intercept this weapon. A value of <code>0</code> means that no shields will intercept the weapon. The defaults are as follows:
* <code>0</code> - [[#DGun]]
* <code>1</code> - [[#Cannon]] and [[#EmgCannon]]
* <code>2</code> - [[#LaserCannon]] and [[#BeamLaser]]
* <code>4</code> - [[#MissileLauncher]] and [[#StarburstLauncher]]
* <code>8</code> - [[#AircraftBomb]]
* <code>16</code> - [[#Flame]]
* <code>32</code> - [[#TorpedoLauncher]]
* <code>64</code> - [[#LightningCannon]]
* <code>128</code> - [[#Rifle]]
* <code>256</code> - [[#Melee]]
(See [[Shield Interception Tag Use]]).}}

====Collision & Avoidance====

{{tag
|name = avoidGround
|type = bool
|default = true
|description = Should the weapon avoid firing if terrain blocks the line of fire?}}

{{tag
|name = avoidFriendly
|type = bool
|default = true
|description = Should the weapon avoid firing if a friendly unit is in the line of fire?}}

{{tag
|name = avoidFeature
|type = bool
|default = true
|description = Should the weapon avoid firing if a static map feature is in the line of fire?}}

{{tag
|name = avoidNeutral
|type = bool
|default = false
|description = Should the weapon avoid firing if a neutral unit is in the line of fire?}}

{{tag
|name = collideEnemy
|type = bool
|default = true
|special = lua: noEnemyCollide
|description = Does the weapon projectile collide with enemy units or pass through?}}

{{tag
|name = collideFriendly
|type = bool
|default = true
|special = lua: noFriendlyCollide
|description = Does the weapon projectile collide with friendly units or pass through?}}

{{tag
|name = collideFeature
|type = bool
|default = true
|special = lua: noFeatureCollide
|description = Does the weapon projectile collide with static map features or pass through?}}

{{tag
|name = collideNeutral
|type = bool
|default = true
|special = lua: noNeutralCollide
|description = Does the weapon projectile collide with neutral units or pass through?}}

{{tag
|name = collideGround
|type = bool
|default = true
|special = lua: noGroundCollide
|description = Does the weapon projectile collide with terrain or pass through?}}

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = Modifies visual size of EMG and Flame projectiles, and physical size '''only''' for hitscan interceptor weapons (e.g. antinuke lasers). [[https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 1]][[https://github.com/spring/spring/blob/master/rts/Sim/Misc/CollisionHandler.cpp#L33 2]]}}

====Targeting & Accuracy====
{{tag
|name = commandFire
|type = bool
|default = false
|description = Determines if the weapon will automatically fire on enemy units in range or only when manually ordered to attack.}}

{{tag
|name = canAttackGround
|type = bool
|default = true
|description = Determines if the weapon can be force-fired on ground positions or only fire on targeted units.}}

{{tag
|name = waterWeapon
|type = bool
|default = false
|description = Determines if the weapon can pass through water and target underwater units.}}

{{tag
|name = fireSubmersed
|type = bool
|default = waterWeapon
|description = Determines if the weapon can fire whilst underwater.}}

{{tag
|name = targetBorder
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon aims for the centre or the edge of its target's [[Gamedev:CollisionVolumes|collision volume]]. Clamped between <code>-1.0</code> - target the far border, and <code>1.0</code> - target the near border.}}

{{tag
|name = cylinderTargeting
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of this tag multiplied by the {{taglink|range}}. Clamped between <code>0.0</code> and <code>128.0</code>.}}

{{tag
|name = tolerance
|type = float
|default = 3000.0 (+/- ~18 degrees)
|description = The amount (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For {{taglink|turret|false}} or {{taglink|fixedLauncher|true}} weapons this determines in what arc the unit will fire.}}

{{tag
|name = fireTolerance
|type = float
|default = 32768.0 (+/- 180 degrees)
|special = {{new|99.0}}
|description = Final check to prevent weapons from shooting sideways. If a weapon is about to fire but the difference between its old aim and requested aim is greater than this angle (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) then it will not fire.}}

{{tag
|name = allowNonBlockingAim
|type = bool
|default = false
|special = {{new|99.0}}
|description = When enabled it makes [[Animation-LuaCallins#Weapons|AimWeapon()]] script calls non-blocking (still the {{taglink|fireTolerance}} tag might prevent the weapon firing). This is very useful for fast units that need to re-target often.}}

{{tag
|name = targetMoveError
|type = float
|default = 0.0
|description = The degree to which a weapon's aiming will fail to keep up with its target's movement. If set very low or not set at all, a weapon will lead its target and almost always hit.}}

{{tag
|name = leadLimit
|type = float
|default = -1.0
|description = Limits the maximum distance a unit will lead a target. The default of <code>-1</code> allows an infinite distance.}}

{{tag
|name = leadBonus
|type = float
|default = 0.0
|description = Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the {{taglink|leadLimit}}.}}

{{tag
|name = predictBoost
|type = float
|default = 0.0 (0.5 for {{taglink|burnblow|true}} weapons)
|description = Controls how well the weapon predicts unit speeds. Works in a similar way to {{taglink|targetMoveError}} except that it is 1-dimensional. This tag spreads the shots in a line based on the direction of the target whereas {{taglink|targetMoveError}} spreads the shots all around based on the movement.}}

{{tag
|name = heightMod
|type = float
|default = 0.2 (0.8 for [[#Cannon]], 1.0 for [[#BeamLaser]] and [[#LightningCannon]])
|description = Changes the spherical weapon range into an ellipsoid. Values above <code>1.0</code> mean the weapon cannot target as high as it can far, values below <code>1.0</code> mean it can target higher than it can far. For example <code>0.5</code> would allow the weapon to target twice as high as far.}}

{{tag
|name = proximityPriority
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance to the target in the priority calculation. Note that negative values make weapons prefer distant targets.}}

{{tag
|name = accuracy
|type = float
|default = 0.0
|description = How accurate the weapon is. Lower values are more accurate. Accuracy is relative to the distance to the target; for instance, if the target is very close, even a very high value will probably still hit. If a target is very far away, even a very low value will likely cause the weapon to miss.}}

{{tag
|name = movingAccuracy
|type = float
|default = accuracy
|description = A weapon's {{taglink|accuracy}} whilst the owning unit is moving.}}

{{tag
|name = sprayAngle
|type = float
|default = 0.0
|description = How wide the the angle of a burst from a [[#Bursts|burst weapon]] can be. Very similar to {{taglink|accuracy}}, except that this tag affects each projectile in a burst, whilst the former does not.}}

{{tag
|name = ownerExpAccWeight
|type = float
|default = 0.0 (See description)
|description = A multiplier to {{taglink|accuracy}} and {{taglink|sprayAngle}} that reduces inaccuracy as a units experience increases. Defaults are as follows:
* <code>0.9</code> - [[#Cannon]], [[#Rifle]]
* <code>0.7</code> - [[#LaserCannon]], [[#BeamLaser]], [[#StarburstLauncher]]
* <code>0.5</code> - [[#MissileLauncher]], [[#LightningCannon]], [[#EmgCannon]], [[#DGun]]
* <code>0.2</code> - [[#Flame]]
}}

{{tag
|name = targetable
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapon that can intercept this weapon. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptor}} tag will intercept this weapon. Instant-hitting weapons such as [[#BeamLaser]], [[#LightningCannon]] and [[#Rifle]] cannot be targeted.
}}

{{tag
|name = interceptor
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this weapon can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|targetable}} tag will be intercepted by this weapon.
}}

{{tag
|name = interceptSolo
|type = bool
|default = true
|special = {{new|92.0}}
|description = If <code>true</code> no other interceptors may target the same projectile.
}}

{{tag
|name = coverage
|type = float
|default = 0.0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = The radius in [[elmo]]s within which an {{taglink|interceptor}} weapon will fire on {{taglink|targetable}} weapons.
}}

====Bouncing====

{{tag
|name = waterBounce
|type = bool
|default = false
|description = Does the weapon bounce on water impacts?}}

{{tag
|name = groundBounce
|type = bool
|default = false
|description = Does the weapon bounce on ground impacts?}}

{{tag
|name = bounceSlip
|type = float
|default = 1.0
|description = The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.}}

{{tag
|name = bounceRebound
|type = float
|default = 1.0
|description = The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.}}

{{tag
|name = numBounce
|type = int
|default = -1
|description = The number of times the weapon will bounce on impact before exploding. The default value of <code>-1</code> allows infinite bounces (at least until velocity reaches 0).}}

====Area Of Effect, Impulse & Cratering====

{{tag
|name = areaOfEffect
|type = float
|default = 8.0 * 0.5
|special = lua: damageAreaOfEffect
|description = The ''diameter'' in [[elmo]]s in which the weapons explosion will cause damage.}}

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering. Behaviour changed slightly in 98.0 as previously craters were 1.5x {{taglink|craterAreaOfEffect}} whilst decals were 1.0x, they are now both the same size.}}

{{tag
|name = edgeEffectiveness
|type = float
|default = 0.0
|description = Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's {{taglink|areaOfEffect}}. Falls off from the epicentre according to the formula <code>damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))]</code>, a graph of the function for various values is available [[Media:EdgeEffectiveness.png|here]].}}

{{tag
|name = explosionSpeed
|type = float
|default = See description
|description = The speed at which the weapon's explosion propagates from the epicentre. The default is calculated by this complex formula: <code>defExpSpeed = {8.0 + [max(30.0, default_damage / 20.0) * 2.5]} / {9.0f + [sqrt(max(30.0, default_damage / 20.0f)) * 0.7]} * 0.5</code>.}}

{{tag
|name = impulseFactor
|type = float
|default = 1.0
|description = A multiplier to the impulse given to units within the explosion {{taglink|areaOfEffect}}, which is otherwise equal to the damage dealt after {{taglink|edgeEffectiveness}} is taken into account. For [[#Melee]] weapons this is instead multiplied by the owning unit's mass (See [[Gamedev:UnitDefs#Tag:mass|Gamedev:UnitDefs]]).}}

{{tag
|name = impulseBoost
|type = float
|default = 0.0
|description = A constant amount added to the weapon's impulse, regardless of distance from the epicentre or the damage potential of the explosion, prior to the application of {{taglink|impulseFactor}}}}

{{tag
|name = craterMult
|type = float
|default = impulseFactor
|description = A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.}}

{{tag
|name = craterBoost
|type = float
|default = 0.0
|description = A constant amount, added to the weapon's cratering depth before the application of {{taglink|craterMult}}.}}

====Bursts====

{{tag
|name = burst
|type = int
|default = 1
|special = lua: salvoSize
|description = How many shots to fire per burst.
}}

{{tag
|name = burstRate
|type = float
|default = 0.1
|special = lua: salvoDelay
|description = The time in seconds between shots in a burst. Note that {{taglink|reloadTime}} starts to count down from the ''first'' round fired, not the last so if <code>reloadTime < burst * burstRate</code> the weapon will fire continuously.
}}

{{tag
|name = projectiles
|type = int
|default = 1
|description = How many projectiles released per shot (shotgun style). e.g. a weapon with {{taglink|burst|5}}, {{taglink|burstRate|0.5}} and {{taglink|projectiles|2}} will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for {{taglink|reloadTime}}. Best used in conjunction with {{taglink|sprayAngle}} or changing the firing piece using [[Animation-LuaCallins#Weapons|ShotX]] as otherwise they'll all be clumped in one shot.
}}

====Paralyzing====
{{tag
|name = paralyzer
|type = bool
|default = false
|description = Is the weapon a paralyzer? If <code>true</code> the weapon only stuns enemy units and does not cause damage in the form of lost hit-points.
}}

{{tag
|name = paralyzeTime
|type = int
|default = 10
|special = lua: damages.paralyzeDamageTime
|description = Determines the maximum length of time in seconds that the target will be paralyzed. The timer is restarted every time the target is hit by the weapon. Cannot be less than <code>0</code>.
}}

====Dynamic Damage====
The following set of tags allow for a weapon's damage potential to vary with the distance to its target.

{{tag
|name = dynDamageExp
|type = float
|default = 0.0
|description = Exponent of the range-dependent damage formula, the default of <code>0.0</code> disables dynamic damage, <code>1.0</code> means linear scaling, <code>2.0</code> quadratic and so on.
}}

{{tag
|name = dynDamageMin
|type = float
|default = 0.0
|description = The minimum floor value that range-dependent damage can drop to.
}}

{{tag
|name = dynDamageRange
|type = float
|default = 0.0
|description = If set to non-zero values the weapon will use this value in the range-dependant damage formula instead of the actual {{taglink|range}}.
}}

{{tag
|name = dynDamageInverted
|type = bool
|default = false
|description = If <code>true</code> the damage curve is inverted i.e. the weapon does more damage at greater ranges as opposed to less.
}}

====Sounds====
{{tag
|name = soundTrigger
|type = bool
|default = false (true for [[#Melee]], [[#Rifle]] and non-beamBurst [[#BeamLaser]])
|description = Does the weapon play {{taglink|soundStart}} only once for each salvo (<code>true</code>) or for every round in a burst (<code>false</code>)?}}

{{tag
|name = soundStart
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon fires.}}

{{tag
|name = soundHitDry
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with solid ground. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

{{tag
|name = soundHitWet
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with water. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

====Visuals====

{{tag
|name = cegTag
|type = string
|default = ""
|description = The name, without prefixes, of a [[CEG]] to be emitted by the projectile each frame.
}}

{{tag
|name = intensity
|type = float
|default = 0.9 (0.2 for [[#Cannon]])
|description = Alpha transparency for non-3D model projectiles. Lower values are more opaque, but <code>0.0</code> will cause the projectile to disappear entirely.
}}

{{tag
|name = model
|type = string
|default = ""
|description = The filename of a 3D model to use when rendering the projectile. Note that only the root piece of a projectile model is rendered. Currently only for [[#Cannon]], [[#LaserCannon]], [[#MissileLauncher]], [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = explosionScar
|type = bool
|default = false
|description = Does the weapon's explosion leave a scar decal on the ground? For all types except [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If <code>true</code> the weapon is always rendered regardless of whether or not it is in LOS range of a player's units.
}}

{{tag
|name = rgbColor
|type = float[3]
|default = {1.0, 0.0, 0.0} (See Description)
|description = The primary colour for sprite rendering weapons. Additional defaults are as follows:
* [[#Cannon]] - <code>{1.0, 0.5, 0.0}</code>
* [[#EmgCannon]] - <code>{0.9, 0.9, 0.2}</code>
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of a [[CEG]], with <code>custom:</code> prefix, to spawn as the weapon's explosion. Does not currently work for [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = bounceExplosionGenerator
|type = string
|default = ""
|description = For weapons which can use {{taglink|groundBounce|true}}, the name of a [[CEG]], with <code>custom:</code> prefix, to spawn when weapon the bounces.
}}

{{tag
|name = texture1
|type = string
|default = ""
|description = The projectile texture for [[#AircraftBomb]], [[#Cannon]], [[#EmgCannon]], [[#Flame]]; beam texture for [[#LaserCannon]], [[#BeamLaser]], [[#LightningCannon]]; flare texture for [[#MissileLauncher]], [[#StarburstLauncher]] and dome texture for the [[#Shield]].
}}

{{tag
|name = texture2
|type = string
|default = ""
|description = The end-of-beam texture for [[#LaserCannon]], [[#BeamLaser]] and {{taglink|smoketrail}} texture for [[#MissileLauncher]], [[#StarburstLauncher]].
}}

{{tag
|name = texture3
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]], or muzzle texture if {{taglink|largeBeamLaser|true}}. Also used as the flame texture for [[#StarburstLauncher]].
}}

{{tag
|name = texture4
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]] with {{taglink|largeBeamLaser|true}}.
}}

===AircraftBomb===
Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. Visually drawn as a billboarded sprite as used by the [[#Cannon]], but more commonly used with a 3D model.

There are no tags specific to this '''WeaponType'''

====AircraftBomb Visuals====

When not using a {{taglink|model}}, the AircraftBomb is the same as [[#Cannon Visuals]].

===BeamLaser===
An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be [[Animation-LuaCallouts#Effects|script emitted]] if it has a {{taglink|beamTime}} longer than one frame. Visually drawn as a [http://en.wikipedia.org/wiki/Star_Trek Star Trek] Phaser-style laser weapon. The {{taglink|largeBeamLaser}} tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

{{tag
|name = minIntensity
|type = float
|default = 0.0
|description = The minimum percentage the weapon's damage can fall-off to over its range. Setting to <code>1.0</code> will disable fall off entirely. Unrelated to the visual-only {{taglink|intensity}} tag.
}}

{{tag
|name = beamTime
|type = float
|default = 1.0
|description = How long in seconds to fire the laser before waiting for {{taglink|reloadTime}} to start. Damage is distributed over the duration of the {{taglink|beamTime}}, and the weapon will aim to hit the target when the beam is in the middle of its {{taglink|beamTime}} (i.e. using prediction).
}}

{{tag
|name = beamBurst
|type = bool
|default = false
|description = Makes the laser fire a burst of beams that are all aimed towards the target (instead of aimed with the piece). A [[#BeamLaser]] can do its full damage with every shot if {{taglink|beamBurst}} is enabled. Disables {{taglink|beamTime}} in favour of the [[#Bursts|burst tags]].
}}

{{tag
|name = sweepFire
|type = bool
|default = false
|description = Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Reimplemented in 95.0, still has no script interaction so use with care. Respects {{taglink|reloadTime}} constraint but not much else.
}}

====BeamLaser Visuals====

See also {{taglink|thickness}} and {{taglink|coreThickness}}.

{{tag
|name = beamTTL
|type = int
|default = 0
|description = The time in frames for which the laser beam remains visible.
}}

{{tag
|name = beamDecay
|type = float
|default = 1.0
|description = How fast the beam fades out. Each frame the {{taglink|intensity}} is multiplied by this value.
}}

{{tag
|name = laserFlareSize
|type = float
|default = 15.0
|description = Determines the size of the firing flare.
}}

{{tag
|name = largeBeamLaser
|type = bool
|default = false
|description = Changes the visual effect allowing tiling and scrolling of the texture and a pulsating firing flare.
}}

{{tag
|name = tileLength
|type = float
|default = 200.0
|description = Defines the length before the texture used is repeated (tiled). Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = scrollSpeed
|type = float
|default = 5.0
|description = Controls how fast the texture scrolls. Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = pulseSpeed
|type = float
|default = 1.0
|description = Controls how fast the pulsating effect at the start of the beam is. Only if {{taglink|largeBeamLaser|true}}.
}}

===Cannon===
The default '''WeaponType'''. Fires a ballistic projectile, for the best result (without under/overshooting) the {{taglink|weaponVelocity}} should be set so as to give an elevation of 45Â° when firing at the maximum {{taglink|range}}. Substituting the angle into the [http://en.wikipedia.org/wiki/Trajectory#Range_and_height trajectory equation] and rearranging, we get:
<code><pre>weaponVelocity = âˆš(range * g)</pre></code>
where <code>g</code> is the map gravity, usually around <code>120</code> for most Spring maps (You can use the {{taglink|myGravity}} tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

{{tag
|name = highTrajectory
|type = int
|default = 2
|description = Can this weapon be fired in a high trajectory (>45Â° angle). Can be <code>0</code> - low trajectory only, <code>1</code> - high trajectory only or <code>2</code> - enables a high/low toggle button on the unit.
}}

{{tag
|name = heightBoostFactor
|type = float
|default = -1.0
|description = Controls the boost given to {{taglink|range}} by high terrain. Values > <code>1.0</code> result in increased range, <code>0.0</code> means the cannon has fixed range regardless of height difference to target. Any value < <code>0.0</code> (i.e. the default value) result in an automatically calculated value based on {{taglink|range}} and theoretical maximum range.
}}

====Cannon Visuals====

{{tag
|name = size
|type = float
|default = 2.0 + min(default_damage * 0.0025, {{taglink|areaOfEffect}} * 0.1)
|description = The drawing radius of the billboarded sprite. Also for [[#AircraftBomb Visuals]], [[#EmgCannon Visuals]] (default: <code>3.0</code>) and [[#Flame Visuals]].
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = A set of RGB colours to transition between over the projectile's lifetime. Can be given as a string of RGB digits or an image filename (See [[CColorMap]]). Also for [[#Flame Visuals]].
}}

{{tag
|name = sizeDecay
|type = float
|default = 0.0
|description = How quickly each particle of the Cannon shot decays in size.
}}

{{tag
|name = alphaDecay
|type = float
|default = 1.0
|description = How quickly each particle of the Cannon shot fades out.
}}

{{tag
|name = separation
|type = float
|default = 0.0
|description = The distance between each particle of the Cannon shot.
}}

{{tag
|name = noGap
|type = bool
|default = true
|description = Switch between the distance between particles being proportional to the size of the two particles (<code>true</code>) or proportional to the size of the first particle (<code>false</code>).
}}

{{tag
|name = stages
|type = int
|default = 5
|description = The number of particles in each Cannon shot.
}}

===DGun===
Fires a line-of-sight or ballistic projectile (selected via the {{taglink|gravityAffected}} tag). Visually represented by a fireball effect that cannot be customised, however it can be replaced by a 3D model. The name and visual effect are [[OTAism]]s.

{{tag
|name = gravityAffected
|type = bool
|default = false
|description = Does the fireball projectile lose height due to map gravity?
}}

===EmgCannon===
A line-of-sight weapon. Visually drawn as a billboarded sprite very similar to that of the [[#Cannon]], however not as customisable, or a 3D model. The name is another [[OTAism]].

There are no tags specific to this '''WeaponType'''.

===Flame===
A line-of-sight weapon intended for use as a flamethrower or similar. Visually drawn as a stream of textured particles, the colour of which can be controlled very precisely using the {{taglink|colorMap}} tag (see [[CColorMap]]).

====Flame Visuals====
See also {{taglink|colorMap}}.

{{tag
|name = sizeGrowth
|type = float
|default = 0.5
|description = How much the draw radius of the flame projectile increases each frame.
}}

{{tag
|name = flameGFXTime
|type = float
|default = 1.2
|description = Makes the flamethrower projectile stay alive as a visual-only effect (i.e. does not deal any damage) after it has reached maximum {{taglink|range}}. It is a percentage multiplier, e.g. <code>1.2</code> makes the projectile stay alive until it reaches 20% beyond {{taglink|range}}.
}}

===LaserCannon===
A particularly versatile line-of-sight weapon. Visually drawn like a [http://en.wikipedia.org/wiki/Star_Wars Star Wars] Blaster-style laser weapon, or a 3D model.

====LaserCannon Visuals====

{{tag
|name = duration
|type = float
|default = 0.05
|description = Multiplied against {{taglink|weaponVelocity}} to determine the visual length of the beam projectile.
}}

{{tag
|name = hardStop
|type = bool
|default = false
|description = Does the laser projectile stop dead or fade out?
}}

{{tag
|name = fallOffRate
|type = float
|default = 0.5
|description = Rate at which the beam fades out after it goes past its maximum {{taglink|range}} if {{taglink|hardStop|false}}. A value of <code>0.0</code> is never fade out, <code>1.0</code> is finish fading out exactly at maximum {{taglink|range}}.
}}

{{tag
|name = lodDistance
|type = int
|default = 1000
|description = Minimum camera distance at which the default LaserCannon projectile is simplified to a single rectangle.
}}

{{tag
|name = thickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = coreThickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = rgbColor2
|type = float
|default = {1.0, 1.0, 1.0}
|description = The colour of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

===LightningCannon===
An instant-hit weapon similar to the [[#BeamLaser]], but which does all its damage at once. Visually drawn like [http://en.wikipedia.org/wiki/Star_Wars Star Wars] 'Force Lightning' or [http://en.wikipedia.org/wiki/Command_%26_Conquer:_Red_Alert CnC: Red Alert] [http://en.wikipedia.org/wiki/Tesla_coil Tesla Coil] weapons, the effect is not very customisable.

There are no tags specific to this '''WeaponType'''.

===Melee===
A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters [http://en.wikipedia.org/wiki/Melee#Use_in_gaming 'melee'] weapon. It does not fire a projectile and does not care about the line of fire.

There are no tags specific to this '''WeaponType'''.

===MissileLauncher===
A versatile weapon which can optionally track targets and accelerate from a low initial velocity. It can also use {{taglink|trajectoryHeight}} to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = startVelocity
|type = float
|default = 0.0
|description = The initial velocity of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = weaponAcceleration
|type = float
|default = 0.0
|description = The initial acceleration of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Note that if it is <code>0.0</code> the weapon can never increase from its {{taglink|startVelocity}} and will not reach its maximum {{taglink|weaponVelocity}}. Since 99.0 <code>acceleration</code> is a synonym.
}}

{{tag
|name = tracks
|type = bool
|default = false
|description = Can the weapon projectile track a moving target? Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = The rate (in [[Elmo#Angular|cau]]) at which {{taglink|tracks|true}} weapons turn towards their target. This is relative to a projectile's current velocity; a weapon with a higher velocity will need a higher value in order to be able to hit targets that turn suddenly.}}

{{tag
|name = flightTime
|type = float
|default = 0.0
|description = The time in seconds before a missile projectile's fuel runs out; it ceases to obey {{taglink|tracks}}, loses velocity and falls to the ground. Also for [[#StarburstLauncher]]. Large values may cause over/undershoot problems.
}}

{{tag
|name = fixedLauncher
|type = bool
|default = false
|description = Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Weapons may not correctly obey [[#Collision & Avoidance|avoidance settings]] when using this tag.
}}

{{tag
|name = wobble
|type = float
|default = 0.0
|description = Adds a random vector to the direction of travel every 16 frames, multiplied by the value of the tag. The effect is reduced as the firing unit gains experience. As this missiles direction is changed, wobbling swarm of missiles will diverge.
}}

{{tag
|name = dance
|type = float
|default = 0.0
|description = Adds a random vector to the position of a missile projectile every 8 frames, multiplied by the value of the tag. As the projectile is not rotated, a dancing swarm of missiles will remain relatively coherent.
}}

{{tag
|name = trajectoryHeight
|type = float
|default = 0.0
|description = Determines the height of the arc the missile will reach as it moves towards its target. A value of <code>0.0</code> will result in a flat trajectory, <code>1.0</code> will launch at 45°. Can be any value >= <code>0.0</code>; extreme values may require the {{taglink|tracks}} tag to be able to hit a target.
}}

====MissileLauncher Visuals====
A note about the missile exhaust flare: the size of the flare is determined by the model radius. The emit position of the flare is at (0,0,-radius) so the model may need careful adjustment to get the flare looking right.

{{tag
|name = smokeTrail
|type = bool
|default = false
|description = Does the missile projectile emit a smoke trail as it travels? Also for [[#StarburstLauncher]].
}}

===Rifle===
An instant hit weapon which does all its damage at once. Visually represented by a hardcoded tracer, firing and hitting effects. Rarely used.

There are no tags specific to this '''WeaponType'''.

===Shield (WeaponType)===
As the name suggests, not a weapon but a defensive shield. Can absorb or deflect ({{taglink|shieldrepulser|true}}) projectiles. Individual weapons can be set to be intercepted or not by the shield using a [http://en.wikipedia.org/wiki/Mask_(computing) bitmask] (see [[Shield Interception Tag Use]]). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible ({{taglink|visible|false}}).

See the [[#shield]] sub-table section for other tags specific to this type.

===StarburstLauncher===
Fires a projectile that rises vertically for {{taglink|weaponTimer}} seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. Before spring 92.0 was the only weapon that can be {{taglink|targetable}} and act as an {{taglink|interceptor}}. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = weaponTimer
|type = float
|default = 0.0
|description = The time in seconds during which the missile ascends vertically before turning towards its target.
}}

===TorpedoLauncher===
Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with {{taglink|waterWeapon|true}} so they can fire underwater and target underwater units. An aircraft carrying a [[#TorpedoLauncher]] is a special case, the weapon turns into an [[#AircraftBomb]] projectile that will spawn a torpedo projectile on impact with water. Visually represented by a pointed black cuboid, usually the default object is replaced by a 3D model.

{{tag
|name = subMissile
|type = bool
|default = false
|description = Can the torpedo leave the water and target units and positions on land?
}}

===NoWeapon===
Not actually a '''WeaponType''', but an individual weapon requested by Spring to 'fill in the gaps' if a unit claims to have a weapon which isn't actually defined. There needs to be only one of these weapons and it is created by setting {{taglink|weaponName|"NOWEAPON"}} rather than by the {{taglink|weaponType}} tag.

==Sub Tables==

===damage===
The damage subtable lists how many hit points the weapon depletes against each armor class (See [[Armordefs.lua]]). It is a key-value map of armor class names and damage values. The special <code>default</code> entry is as the name suggests the default damage applied to any unit which does not belong to a listed armor class, or to shields.

For example a weapon which deals 100 damage by default but only 50 to units in the 'tank' armor class:

<code><pre>damage = {
default = 100,
tank = 50,
}</pre></code>

===shield===
The preferred way to create a shield or repulser is to use the shield subtable rather than the old shield tags.

The following tags are repulser specific:

{{tag
|name = repulser
|type = bool
|default = false
|description = Does the shield [http://dictionary.reference.com/browse/repulse?s=t repulse] (deflect) projectiles or absorb them? Btw its [http://springrts.com/mantis/view.php?id=4206 not repulsOr, but repulsEr]!}}

{{tag
|name = force
|type = float
|default = 0.0
|description = The force applied by the repulser to the weapon - higher values will deflect weapons away at higher velocities.}}

{{tag
|name = maxSpeed
|type = float
|default = 0.0
|description = The maximum speed the repulser will impart to deflected projectiles.}}

{{tag
|name = visibleRepulse
|type = bool
|default = false
|description = Is the (hard-coded) repulse effect rendered or not?}}

The following tags are general behaviour for all shields:

{{tag
|name = interceptType
|type = int
|default = 0
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this shield can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptedByShieldType}} will be intercepted by this shield (See [[Shield Interception Tag Use]]).}}

{{tag
|name = armorType
|type = string
|default = ""
|description = Specifies the armorclass of the shield; you can input either an [[Armordefs.lua|armorclass]] name OR a unitdef {{xtaglink|Gamedev:UnitDefs|name}} to share that unit's armorclass.}}

{{tag
|name = smart
|type = bool
|default = false
|description = Determines whether or not projectiles fired by allied units can pass through the shield (<code>true</code>) or are intercepted as enemy weapons are (<code>false</code>).}}

{{tag
|name = exterior
|type = bool
|default = false
|description = Determines whether or not projectiles fired within the shield's radius can pass through the shield (<code>true</code>) or are intercepted (<code>false</code>).}}

{{tag
|name = energyUse
|type = float
|default = 0.0
|description = The amount of the energy resource consumed by the shield to absorb or repulse weapons, continually drained by a repulser as long as the projectile is in range.}}

{{tag
|name = radius
|type = float
|default = 0.0
|description = The radius of the circular area the shield covers.}}

{{tag
|name = power
|type = float
|default = 0.0
|description = Essentially the maximum allowed hit-points of the shield - reduced by the <code>damage</code> of a weapon upon impact.}}

{{tag
|name = startingPower
|type = float
|default = 0.0
|description = How many hit-points the shield starts with - otherwise the shield must regenerate from <code>0</code> until it reaches maximum {{taglink|power}}.}}

{{tag
|name = powerRegen
|type = float
|default = 0.0
|description = How many hit-points the shield regenerates each second.}}

{{tag
|name = powerRegenEnergy
|type = float
|default = 0.0
|description = How much energy resource is consumed to regenerate each hit-point.}}

{{tag
|name = rechargeDelay
|type = float
|default = 0.0
|description = The delay in seconds before a shield begins to regenerate after it is hit.}}

The following tags control the visual aspects of the shield:

{{tag
|name = visible
|type = bool
|default = false
|description = Is the shield visible or not?}}

{{tag
|name = visibleHitFrames
|type = int
|default = 0
|description = The number of frames a shield becomes visible for when hit.}}

{{tag
|name = badColor
|type = float[3]
|default = {1.0, 0.5, 0.5} (Red)
|description = The RGB colour the shield transitions to as its hit-points are reduced towards <code>0</code>.}}

{{tag
|name = goodColor
|type = float[3]
|default = {0.5, 0.5, 1.0} (Blue)
|description = The RGB colour the shield transitions to as its hit-points are regenerated towards its maximum {{taglink|power}}.}}

{{tag
|name = alpha
|type = float
|default = 0.2
|description = The alpha transparency of the shield whilst it is visible.}}

===customParams===
The <code>customParams</code> subtable of a WeaponDef allows the game designer to give their weapons custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
Some games may have most WeaponDefs integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]].

S44 and MC:L implement an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance].

{{ExampleRepoLinks
|path = weapons/
|entity = WeaponDefs
}}

[[Category: Game Dev]]

Gamedev:WeaponDefs

2016-03-01T22:13:19Z

Picassoct: /* Shield (WeaponType) */

[[Gamedev:Main|Development]] < [[Gamedev:Main]] < {{FULLPAGENAME}}

==Location==
WeaponDef files are .lua files stored in the <code>Weapons/</code> directory of a Spring Game. Alternatively they can be integrated into [[Gamedev:UnitDefs|UnitDefs]].

==Purpose==
WeaponDef files have one purpose; to define the properties of weapons. They are the main description file for what attributes your weapon should have and how it should behave. Since version 100.0, Spring will record a warning whenever it finds an unknown tag.

==Source==
The engine source code which loads the tags from these files is viewable here:

* {{sourcelink|file=rts/Sim/Weapons/WeaponDef.cpp}}

==Data Types==
{{DataTypes}}

==Details==
There follows a comprehensive (certain deprecated tags are not present) list of the tags available, their data type, default value and a brief description of what they do. Bear in mind that the source code linked above is the ultimate reference when dealing with these tags.

In lua tables keys (i.e. the tags) should be lower case, here they are represented in camelCase for readability. In your files you may use the <code>lowerkeys</code> function on your final table to ensure the keys are properly cased.

It is usual to name the returned WeaponDef table the internal <code>weaponName</code> desired for the weapon.

===Common===
The following tags are common to all or at least a majority of '''WeaponTypes''', depending on the tag.

====General====
{{tag
|name = weaponType
|type = string
|default = "Cannon"
|description = Spring has 14 '''WeaponTypes''' which provide game developers with basic behaviours which they can customise to an extent with the '''WeaponDef''' tags. Some tags are specific to certain '''WeaponTypes''' and not implemented for others, [https://docs.google.com/spreadsheet/ccc?key=0Am5BbZxm93S9dEZXc1Q4dXR4TFRYTFM4NlR4OFJFdWc#gid=0 this two-way table] indicates which tags work for which types.}} The possible values are:
* [[#AircraftBomb|AircraftBomb]]
* [[#BeamLaser|BeamLaser]]
* [[#Cannon|Cannon]]
* [[#DGun|Dgun]]
* [[#EmgCannon|EmgCannon]]
* [[#Flame|Flame]]
* [[#LaserCannon|LaserCannon]]
* [[#LightningCannon|LightningCanon]]
* [[#Melee|Melee]]
* [[#MissileLauncher|MissileLauncher]]
* [[#Rifle|Rifle]]
* [[#Shield (WeaponType)|Shield]]
* [[#StarburstLauncher|StarburstLauncher]]
* [[#TorpedoLauncher|TorpedoLauncher]]

{{tag
|name = name
|type = string
|default = "Weapon"
|description = The descriptive name of the weapon as listed in FPS mode.}}

{{tag
|name = turret
|type = bool
|default = false
|description = Does the unit aim within an arc (up-to and including full 360Â° turret traverse) or always aim along the owner's heading?}}

{{tag
|name = noSelfDamage
|type = bool
|default = false
|description = Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.}}

{{tag
|name = impactOnly
|type = bool
|default = false
|description = Does the weapon only deal damage through direct hits and not 'splash' damage through {{taglink|areaOfEffect}}?}}

{{tag
|name = noExplode
|type = bool
|default = false
|description = Does the weapon explode on impact with a target or continue through? Note that these weapons will do damage every single frame they are inside the [[Gamedev:CollisionVolumes|collision volume]] of an object, underground or under water, massively multiplying their damage.}}

{{tag
|name = burnblow
|type = bool
|default = false
|special = lua: selfExplode
|description = Does the weapon explode when it reaches its maximum range or continue on its path? The name is an [[OTAism]].}}

{{tag
|name = range
|type = float
|default = 10.0
|description = The maximum range in [[elmo]]s that the weapon can fire at.}}

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile. Since 99.0 <code>maxVelocity</code> is a synonym.}}

{{tag
|name = reloadTime
|type = float
|default = 1.0
|description = The time in seconds between shots fired.}}

{{tag
|name = metalPerShot
|type = float
|default = 0.0
|description = Metal used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = energyPerShot
|type = float
|default = 0.0
|description = Energy used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = myGravity
|type = float
|default = 0.0
|description = Overrides the map gravity for ballistic weapons. The default of <code>0.0</code> disables the tag in favour of map gravity.}}

{{tag
|name = fireStarter
|type = float
|default = 0.0
|description = The percentage chance (<code>0.0</code> to <code>100.0</code>) of the weapon setting fire to static map features on impact.}}

{{tag
|name = cameraShake
|type = float
|default = damage (0.0 for paralyzers)
|description = Passed to the [[LuaCallinReturn#Game_Events:|ShockFront() callin]] as the first argument. Intended as a means to make the camera shake if in range of detonation.}}

{{tag
|name = stockpile
|type = bool
|default = false
|description = Does each round of the weapon have to be built and stockpiled by the player? Will only correctly function for the first of each stockpiled weapons a unit has.}}

{{tag
|name = stockpileTime
|type = float
|default = reloadTime
|description = The time in seconds taken to stockpile one round of the weapon.}}

{{tag
|name = interceptedByShieldType
|type = int
|default = Depends on {{taglink|weaponType}}
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of shields that can intercept this weapon. Each digit of binary that is set to one means that a shield with the corresponding digit in its {{taglink|interceptType}} will intercept this weapon. A value of <code>0</code> means that no shields will intercept the weapon. The defaults are as follows:
* <code>0</code> - [[#DGun]]
* <code>1</code> - [[#Cannon]] and [[#EmgCannon]]
* <code>2</code> - [[#LaserCannon]] and [[#BeamLaser]]
* <code>4</code> - [[#MissileLauncher]] and [[#StarburstLauncher]]
* <code>8</code> - [[#AircraftBomb]]
* <code>16</code> - [[#Flame]]
* <code>32</code> - [[#TorpedoLauncher]]
* <code>64</code> - [[#LightningCannon]]
* <code>128</code> - [[#Rifle]]
* <code>256</code> - [[#Melee]]
(See [[Shield Interception Tag Use]]).}}

====Collision & Avoidance====

{{tag
|name = avoidGround
|type = bool
|default = true
|description = Should the weapon avoid firing if terrain blocks the line of fire?}}

{{tag
|name = avoidFriendly
|type = bool
|default = true
|description = Should the weapon avoid firing if a friendly unit is in the line of fire?}}

{{tag
|name = avoidFeature
|type = bool
|default = true
|description = Should the weapon avoid firing if a static map feature is in the line of fire?}}

{{tag
|name = avoidNeutral
|type = bool
|default = false
|description = Should the weapon avoid firing if a neutral unit is in the line of fire?}}

{{tag
|name = collideEnemy
|type = bool
|default = true
|special = lua: noEnemyCollide
|description = Does the weapon projectile collide with enemy units or pass through?}}

{{tag
|name = collideFriendly
|type = bool
|default = true
|special = lua: noFriendlyCollide
|description = Does the weapon projectile collide with friendly units or pass through?}}

{{tag
|name = collideFeature
|type = bool
|default = true
|special = lua: noFeatureCollide
|description = Does the weapon projectile collide with static map features or pass through?}}

{{tag
|name = collideNeutral
|type = bool
|default = true
|special = lua: noNeutralCollide
|description = Does the weapon projectile collide with neutral units or pass through?}}

{{tag
|name = collideGround
|type = bool
|default = true
|special = lua: noGroundCollide
|description = Does the weapon projectile collide with terrain or pass through?}}

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = Modifies visual size of EMG and Flame projectiles, and physical size '''only''' for hitscan interceptor weapons (e.g. antinuke lasers). [[https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 1]][[https://github.com/spring/spring/blob/master/rts/Sim/Misc/CollisionHandler.cpp#L33 2]]}}

====Targeting & Accuracy====
{{tag
|name = commandFire
|type = bool
|default = false
|description = Determines if the weapon will automatically fire on enemy units in range or only when manually ordered to attack.}}

{{tag
|name = canAttackGround
|type = bool
|default = true
|description = Determines if the weapon can be force-fired on ground positions or only fire on targeted units.}}

{{tag
|name = waterWeapon
|type = bool
|default = false
|description = Determines if the weapon can pass through water and target underwater units.}}

{{tag
|name = fireSubmersed
|type = bool
|default = waterWeapon
|description = Determines if the weapon can fire whilst underwater.}}

{{tag
|name = targetBorder
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon aims for the centre or the edge of its target's [[Gamedev:CollisionVolumes|collision volume]]. Clamped between <code>-1.0</code> - target the far border, and <code>1.0</code> - target the near border.}}

{{tag
|name = cylinderTargeting
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of this tag multiplied by the {{taglink|range}}. Clamped between <code>0.0</code> and <code>128.0</code>.}}

{{tag
|name = tolerance
|type = float
|default = 3000.0 (+/- ~18 degrees)
|description = The amount (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For {{taglink|turret|false}} or {{taglink|fixedLauncher|true}} weapons this determines in what arc the unit will fire.}}

{{tag
|name = fireTolerance
|type = float
|default = 32768.0 (+/- 180 degrees)
|special = {{new|99.0}}
|description = Final check to prevent weapons from shooting sideways. If a weapon is about to fire but the difference between its old aim and requested aim is greater than this angle (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) then it will not fire.}}

{{tag
|name = allowNonBlockingAim
|type = bool
|default = false
|special = {{new|99.0}}
|description = When enabled it makes [[Animation-LuaCallins#Weapons|AimWeapon()]] script calls non-blocking (still the {{taglink|fireTolerance}} tag might prevent the weapon firing). This is very useful for fast units that need to re-target often.}}

{{tag
|name = targetMoveError
|type = float
|default = 0.0
|description = The degree to which a weapon's aiming will fail to keep up with its target's movement. If set very low or not set at all, a weapon will lead its target and almost always hit.}}

{{tag
|name = leadLimit
|type = float
|default = -1.0
|description = Limits the maximum distance a unit will lead a target. The default of <code>-1</code> allows an infinite distance.}}

{{tag
|name = leadBonus
|type = float
|default = 0.0
|description = Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the {{taglink|leadLimit}}.}}

{{tag
|name = predictBoost
|type = float
|default = 0.0 (0.5 for {{taglink|burnblow|true}} weapons)
|description = Controls how well the weapon predicts unit speeds. Works in a similar way to {{taglink|targetMoveError}} except that it is 1-dimensional. This tag spreads the shots in a line based on the direction of the target whereas {{taglink|targetMoveError}} spreads the shots all around based on the movement.}}

{{tag
|name = heightMod
|type = float
|default = 0.2 (0.8 for [[#Cannon]], 1.0 for [[#BeamLaser]] and [[#LightningCannon]])
|description = Changes the spherical weapon range into an ellipsoid. Values above <code>1.0</code> mean the weapon cannot target as high as it can far, values below <code>1.0</code> mean it can target higher than it can far. For example <code>0.5</code> would allow the weapon to target twice as high as far.}}

{{tag
|name = proximityPriority
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance to the target in the priority calculation. Note that negative values make weapons prefer distant targets.}}

{{tag
|name = accuracy
|type = float
|default = 0.0
|description = How accurate the weapon is. Lower values are more accurate. Accuracy is relative to the distance to the target; for instance, if the target is very close, even a very high value will probably still hit. If a target is very far away, even a very low value will likely cause the weapon to miss.}}

{{tag
|name = movingAccuracy
|type = float
|default = accuracy
|description = A weapon's {{taglink|accuracy}} whilst the owning unit is moving.}}

{{tag
|name = sprayAngle
|type = float
|default = 0.0
|description = How wide the the angle of a burst from a [[#Bursts|burst weapon]] can be. Very similar to {{taglink|accuracy}}, except that this tag affects each projectile in a burst, whilst the former does not.}}

{{tag
|name = ownerExpAccWeight
|type = float
|default = 0.0 (See description)
|description = A multiplier to {{taglink|accuracy}} and {{taglink|sprayAngle}} that reduces inaccuracy as a units experience increases. Defaults are as follows:
* <code>0.9</code> - [[#Cannon]], [[#Rifle]]
* <code>0.7</code> - [[#LaserCannon]], [[#BeamLaser]], [[#StarburstLauncher]]
* <code>0.5</code> - [[#MissileLauncher]], [[#LightningCannon]], [[#EmgCannon]], [[#DGun]]
* <code>0.2</code> - [[#Flame]]
}}

{{tag
|name = targetable
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapon that can intercept this weapon. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptor}} tag will intercept this weapon. Instant-hitting weapons such as [[#BeamLaser]], [[#LightningCannon]] and [[#Rifle]] cannot be targeted.
}}

{{tag
|name = interceptor
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this weapon can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|targetable}} tag will be intercepted by this weapon.
}}

{{tag
|name = interceptSolo
|type = bool
|default = true
|special = {{new|92.0}}
|description = If <code>true</code> no other interceptors may target the same projectile.
}}

{{tag
|name = coverage
|type = float
|default = 0.0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = The radius in [[elmo]]s within which an {{taglink|interceptor}} weapon will fire on {{taglink|targetable}} weapons.
}}

====Bouncing====

{{tag
|name = waterBounce
|type = bool
|default = false
|description = Does the weapon bounce on water impacts?}}

{{tag
|name = groundBounce
|type = bool
|default = false
|description = Does the weapon bounce on ground impacts?}}

{{tag
|name = bounceSlip
|type = float
|default = 1.0
|description = The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.}}

{{tag
|name = bounceRebound
|type = float
|default = 1.0
|description = The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.}}

{{tag
|name = numBounce
|type = int
|default = -1
|description = The number of times the weapon will bounce on impact before exploding. The default value of <code>-1</code> allows infinite bounces (at least until velocity reaches 0).}}

====Area Of Effect, Impulse & Cratering====

{{tag
|name = areaOfEffect
|type = float
|default = 8.0 * 0.5
|special = lua: damageAreaOfEffect
|description = The ''diameter'' in [[elmo]]s in which the weapons explosion will cause damage.}}

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering. Behaviour changed slightly in 98.0 as previously craters were 1.5x {{taglink|craterAreaOfEffect}} whilst decals were 1.0x, they are now both the same size.}}

{{tag
|name = edgeEffectiveness
|type = float
|default = 0.0
|description = Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's {{taglink|areaOfEffect}}. Falls off from the epicentre according to the formula <code>damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))]</code>, a graph of the function for various values is available [[Media:EdgeEffectiveness.png|here]].}}

{{tag
|name = explosionSpeed
|type = float
|default = See description
|description = The speed at which the weapon's explosion propagates from the epicentre. The default is calculated by this complex formula: <code>defExpSpeed = {8.0 + [max(30.0, default_damage / 20.0) * 2.5]} / {9.0f + [sqrt(max(30.0, default_damage / 20.0f)) * 0.7]} * 0.5</code>.}}

{{tag
|name = impulseFactor
|type = float
|default = 1.0
|description = A multiplier to the impulse given to units within the explosion {{taglink|areaOfEffect}}, which is otherwise equal to the damage dealt after {{taglink|edgeEffectiveness}} is taken into account. For [[#Melee]] weapons this is instead multiplied by the owning unit's mass (See [[Gamedev:UnitDefs#Tag:mass|Gamedev:UnitDefs]]).}}

{{tag
|name = impulseBoost
|type = float
|default = 0.0
|description = A constant amount added to the weapon's impulse, regardless of distance from the epicentre or the damage potential of the explosion, prior to the application of {{taglink|impulseFactor}}}}

{{tag
|name = craterMult
|type = float
|default = impulseFactor
|description = A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.}}

{{tag
|name = craterBoost
|type = float
|default = 0.0
|description = A constant amount, added to the weapon's cratering depth before the application of {{taglink|craterMult}}.}}

====Bursts====

{{tag
|name = burst
|type = int
|default = 1
|special = lua: salvoSize
|description = How many shots to fire per burst.
}}

{{tag
|name = burstRate
|type = float
|default = 0.1
|special = lua: salvoDelay
|description = The time in seconds between shots in a burst. Note that {{taglink|reloadTime}} starts to count down from the ''first'' round fired, not the last so if <code>reloadTime < burst * burstRate</code> the weapon will fire continuously.
}}

{{tag
|name = projectiles
|type = int
|default = 1
|description = How many projectiles released per shot (shotgun style). e.g. a weapon with {{taglink|burst|5}}, {{taglink|burstRate|0.5}} and {{taglink|projectiles|2}} will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for {{taglink|reloadTime}}. Best used in conjunction with {{taglink|sprayAngle}} or changing the firing piece using [[Animation-LuaCallins#Weapons|ShotX]] as otherwise they'll all be clumped in one shot.
}}

====Paralyzing====
{{tag
|name = paralyzer
|type = bool
|default = false
|description = Is the weapon a paralyzer? If <code>true</code> the weapon only stuns enemy units and does not cause damage in the form of lost hit-points.
}}

{{tag
|name = paralyzeTime
|type = int
|default = 10
|special = lua: damages.paralyzeDamageTime
|description = Determines the maximum length of time in seconds that the target will be paralyzed. The timer is restarted every time the target is hit by the weapon. Cannot be less than <code>0</code>.
}}

====Dynamic Damage====
The following set of tags allow for a weapon's damage potential to vary with the distance to its target.

{{tag
|name = dynDamageExp
|type = float
|default = 0.0
|description = Exponent of the range-dependent damage formula, the default of <code>0.0</code> disables dynamic damage, <code>1.0</code> means linear scaling, <code>2.0</code> quadratic and so on.
}}

{{tag
|name = dynDamageMin
|type = float
|default = 0.0
|description = The minimum floor value that range-dependent damage can drop to.
}}

{{tag
|name = dynDamageRange
|type = float
|default = 0.0
|description = If set to non-zero values the weapon will use this value in the range-dependant damage formula instead of the actual {{taglink|range}}.
}}

{{tag
|name = dynDamageInverted
|type = bool
|default = false
|description = If <code>true</code> the damage curve is inverted i.e. the weapon does more damage at greater ranges as opposed to less.
}}

====Sounds====
{{tag
|name = soundTrigger
|type = bool
|default = false (true for [[#Melee]], [[#Rifle]] and non-beamBurst [[#BeamLaser]])
|description = Does the weapon play {{taglink|soundStart}} only once for each salvo (<code>true</code>) or for every round in a burst (<code>false</code>)?}}

{{tag
|name = soundStart
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon fires.}}

{{tag
|name = soundHitDry
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with solid ground. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

{{tag
|name = soundHitWet
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with water. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

====Visuals====

{{tag
|name = cegTag
|type = string
|default = ""
|description = The name, without prefixes, of a [[CEG]] to be emitted by the projectile each frame.
}}

{{tag
|name = intensity
|type = float
|default = 0.9 (0.2 for [[#Cannon]])
|description = Alpha transparency for non-3D model projectiles. Lower values are more opaque, but <code>0.0</code> will cause the projectile to disappear entirely.
}}

{{tag
|name = model
|type = string
|default = ""
|description = The filename of a 3D model to use when rendering the projectile. Note that only the root piece of a projectile model is rendered. Currently only for [[#Cannon]], [[#LaserCannon]], [[#MissileLauncher]], [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = explosionScar
|type = bool
|default = false
|description = Does the weapon's explosion leave a scar decal on the ground? For all types except [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If <code>true</code> the weapon is always rendered regardless of whether or not it is in LOS range of a player's units.
}}

{{tag
|name = rgbColor
|type = float[3]
|default = {1.0, 0.0, 0.0} (See Description)
|description = The primary colour for sprite rendering weapons. Additional defaults are as follows:
* [[#Cannon]] - <code>{1.0, 0.5, 0.0}</code>
* [[#EmgCannon]] - <code>{0.9, 0.9, 0.2}</code>
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of a [[CEG]], with <code>custom:</code> prefix, to spawn as the weapon's explosion. Does not currently work for [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = bounceExplosionGenerator
|type = string
|default = ""
|description = For weapons which can use {{taglink|groundBounce|true}}, the name of a [[CEG]], with <code>custom:</code> prefix, to spawn when weapon the bounces.
}}

{{tag
|name = texture1
|type = string
|default = ""
|description = The projectile texture for [[#AircraftBomb]], [[#Cannon]], [[#EmgCannon]], [[#Flame]]; beam texture for [[#LaserCannon]], [[#BeamLaser]], [[#LightningCannon]]; flare texture for [[#MissileLauncher]], [[#StarburstLauncher]] and dome texture for the [[#Shield]].
}}

{{tag
|name = texture2
|type = string
|default = ""
|description = The end-of-beam texture for [[#LaserCannon]], [[#BeamLaser]] and {{taglink|smoketrail}} texture for [[#MissileLauncher]], [[#StarburstLauncher]].
}}

{{tag
|name = texture3
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]], or muzzle texture if {{taglink|largeBeamLaser|true}}. Also used as the flame texture for [[#StarburstLauncher]].
}}

{{tag
|name = texture4
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]] with {{taglink|largeBeamLaser|true}}.
}}

===AircraftBomb===
Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. Visually drawn as a billboarded sprite as used by the [[#Cannon]], but more commonly used with a 3D model.

There are no tags specific to this '''WeaponType'''

====AircraftBomb Visuals====

When not using a {{taglink|model}}, the AircraftBomb is the same as [[#Cannon Visuals]].

===BeamLaser===
An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be [[Animation-LuaCallouts#Effects|script emitted]] if it has a {{taglink|beamTime}} longer than one frame. Visually drawn as a [http://en.wikipedia.org/wiki/Star_Trek Star Trek] Phaser-style laser weapon. The {{taglink|largeBeamLaser}} tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

{{tag
|name = minIntensity
|type = float
|default = 0.0
|description = The minimum percentage the weapon's damage can fall-off to over its range. Setting to <code>1.0</code> will disable fall off entirely. Unrelated to the visual-only {{taglink|intensity}} tag.
}}

{{tag
|name = beamTime
|type = float
|default = 1.0
|description = How long in seconds to fire the laser before waiting for {{taglink|reloadTime}} to start. Damage is distributed over the duration of the {{taglink|beamTime}}, and the weapon will aim to hit the target when the beam is in the middle of its {{taglink|beamTime}} (i.e. using prediction).
}}

{{tag
|name = beamBurst
|type = bool
|default = false
|description = Makes the laser fire a burst of beams that are all aimed towards the target (instead of aimed with the piece). A [[#BeamLaser]] can do its full damage with every shot if {{taglink|beamBurst}} is enabled. Disables {{taglink|beamTime}} in favour of the [[#Bursts|burst tags]].
}}

{{tag
|name = sweepFire
|type = bool
|default = false
|description = Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Reimplemented in 95.0, still has no script interaction so use with care. Respects {{taglink|reloadTime}} constraint but not much else.
}}

====BeamLaser Visuals====

See also {{taglink|thickness}} and {{taglink|coreThickness}}.

{{tag
|name = beamTTL
|type = int
|default = 0
|description = The time in frames for which the laser beam remains visible.
}}

{{tag
|name = beamDecay
|type = float
|default = 1.0
|description = How fast the beam fades out. Each frame the {{taglink|intensity}} is multiplied by this value.
}}

{{tag
|name = laserFlareSize
|type = float
|default = 15.0
|description = Determines the size of the firing flare.
}}

{{tag
|name = largeBeamLaser
|type = bool
|default = false
|description = Changes the visual effect allowing tiling and scrolling of the texture and a pulsating firing flare.
}}

{{tag
|name = tileLength
|type = float
|default = 200.0
|description = Defines the length before the texture used is repeated (tiled). Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = scrollSpeed
|type = float
|default = 5.0
|description = Controls how fast the texture scrolls. Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = pulseSpeed
|type = float
|default = 1.0
|description = Controls how fast the pulsating effect at the start of the beam is. Only if {{taglink|largeBeamLaser|true}}.
}}

===Cannon===
The default '''WeaponType'''. Fires a ballistic projectile, for the best result (without under/overshooting) the {{taglink|weaponVelocity}} should be set so as to give an elevation of 45Â° when firing at the maximum {{taglink|range}}. Substituting the angle into the [http://en.wikipedia.org/wiki/Trajectory#Range_and_height trajectory equation] and rearranging, we get:
<code><pre>weaponVelocity = âˆš(range * g)</pre></code>
where <code>g</code> is the map gravity, usually around <code>120</code> for most Spring maps (You can use the {{taglink|myGravity}} tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

{{tag
|name = highTrajectory
|type = int
|default = 2
|description = Can this weapon be fired in a high trajectory (>45Â° angle). Can be <code>0</code> - low trajectory only, <code>1</code> - high trajectory only or <code>2</code> - enables a high/low toggle button on the unit.
}}

{{tag
|name = heightBoostFactor
|type = float
|default = -1.0
|description = Controls the boost given to {{taglink|range}} by high terrain. Values > <code>1.0</code> result in increased range, <code>0.0</code> means the cannon has fixed range regardless of height difference to target. Any value < <code>0.0</code> (i.e. the default value) result in an automatically calculated value based on {{taglink|range}} and theoretical maximum range.
}}

====Cannon Visuals====

{{tag
|name = size
|type = float
|default = 2.0 + min(default_damage * 0.0025, {{taglink|areaOfEffect}} * 0.1)
|description = The drawing radius of the billboarded sprite. Also for [[#AircraftBomb Visuals]], [[#EmgCannon Visuals]] (default: <code>3.0</code>) and [[#Flame Visuals]].
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = A set of RGB colours to transition between over the projectile's lifetime. Can be given as a string of RGB digits or an image filename (See [[CColorMap]]). Also for [[#Flame Visuals]].
}}

{{tag
|name = sizeDecay
|type = float
|default = 0.0
|description = How quickly each particle of the Cannon shot decays in size.
}}

{{tag
|name = alphaDecay
|type = float
|default = 1.0
|description = How quickly each particle of the Cannon shot fades out.
}}

{{tag
|name = separation
|type = float
|default = 0.0
|description = The distance between each particle of the Cannon shot.
}}

{{tag
|name = noGap
|type = bool
|default = true
|description = Switch between the distance between particles being proportional to the size of the two particles (<code>true</code>) or proportional to the size of the first particle (<code>false</code>).
}}

{{tag
|name = stages
|type = int
|default = 5
|description = The number of particles in each Cannon shot.
}}

===DGun===
Fires a line-of-sight or ballistic projectile (selected via the {{taglink|gravityAffected}} tag). Visually represented by a fireball effect that cannot be customised, however it can be replaced by a 3D model. The name and visual effect are [[OTAism]]s.

{{tag
|name = gravityAffected
|type = bool
|default = false
|description = Does the fireball projectile lose height due to map gravity?
}}

===EmgCannon===
A line-of-sight weapon. Visually drawn as a billboarded sprite very similar to that of the [[#Cannon]], however not as customisable, or a 3D model. The name is another [[OTAism]].

There are no tags specific to this '''WeaponType'''.

===Flame===
A line-of-sight weapon intended for use as a flamethrower or similar. Visually drawn as a stream of textured particles, the colour of which can be controlled very precisely using the {{taglink|colorMap}} tag (see [[CColorMap]]).

====Flame Visuals====
See also {{taglink|colorMap}}.

{{tag
|name = sizeGrowth
|type = float
|default = 0.5
|description = How much the draw radius of the flame projectile increases each frame.
}}

{{tag
|name = flameGFXTime
|type = float
|default = 1.2
|description = Makes the flamethrower projectile stay alive as a visual-only effect (i.e. does not deal any damage) after it has reached maximum {{taglink|range}}. It is a percentage multiplier, e.g. <code>1.2</code> makes the projectile stay alive until it reaches 20% beyond {{taglink|range}}.
}}

===LaserCannon===
A particularly versatile line-of-sight weapon. Visually drawn like a [http://en.wikipedia.org/wiki/Star_Wars Star Wars] Blaster-style laser weapon, or a 3D model.

====LaserCannon Visuals====

{{tag
|name = duration
|type = float
|default = 0.05
|description = Multiplied against {{taglink|weaponVelocity}} to determine the visual length of the beam projectile.
}}

{{tag
|name = hardStop
|type = bool
|default = false
|description = Does the laser projectile stop dead or fade out?
}}

{{tag
|name = fallOffRate
|type = float
|default = 0.5
|description = Rate at which the beam fades out after it goes past its maximum {{taglink|range}} if {{taglink|hardStop|false}}. A value of <code>0.0</code> is never fade out, <code>1.0</code> is finish fading out exactly at maximum {{taglink|range}}.
}}

{{tag
|name = lodDistance
|type = int
|default = 1000
|description = Minimum camera distance at which the default LaserCannon projectile is simplified to a single rectangle.
}}

{{tag
|name = thickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = coreThickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = rgbColor2
|type = float
|default = {1.0, 1.0, 1.0}
|description = The colour of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

===LightningCannon===
An instant-hit weapon similar to the [[#BeamLaser]], but which does all its damage at once. Visually drawn like [http://en.wikipedia.org/wiki/Star_Wars Star Wars] 'Force Lightning' or [http://en.wikipedia.org/wiki/Command_%26_Conquer:_Red_Alert CnC: Red Alert] [http://en.wikipedia.org/wiki/Tesla_coil Tesla Coil] weapons, the effect is not very customisable.

There are no tags specific to this '''WeaponType'''.

===Melee===
A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters [http://en.wikipedia.org/wiki/Melee#Use_in_gaming 'melee'] weapon. It does not fire a projectile and does not care about the line of fire.

There are no tags specific to this '''WeaponType'''.

===MissileLauncher===
A versatile weapon which can optionally track targets and accelerate from a low initial velocity. It can also use {{taglink|trajectoryHeight}} to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = startVelocity
|type = float
|default = 0.0
|description = The initial velocity of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = weaponAcceleration
|type = float
|default = 0.0
|description = The initial acceleration of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Note that if it is <code>0.0</code> the weapon can never increase from its {{taglink|startVelocity}} and will not reach its maximum {{taglink|weaponVelocity}}. Since 99.0 <code>acceleration</code> is a synonym.
}}

{{tag
|name = tracks
|type = bool
|default = false
|description = Can the weapon projectile track a moving target? Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = The rate (in [[Elmo#Angular|cau]]) at which {{taglink|tracks|true}} weapons turn towards their target. This is relative to a projectile's current velocity; a weapon with a higher velocity will need a higher value in order to be able to hit targets that turn suddenly.}}

{{tag
|name = flightTime
|type = float
|default = 0.0
|description = The time in seconds before a missile projectile's fuel runs out; it ceases to obey {{taglink|tracks}}, loses velocity and falls to the ground. Also for [[#StarburstLauncher]]. Large values may cause over/undershoot problems.
}}

{{tag
|name = fixedLauncher
|type = bool
|default = false
|description = Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Weapons may not correctly obey [[#Collision & Avoidance|avoidance settings]] when using this tag.
}}

{{tag
|name = wobble
|type = float
|default = 0.0
|description = Adds a random vector to the direction of travel every 16 frames, multiplied by the value of the tag. The effect is reduced as the firing unit gains experience. As this missiles direction is changed, wobbling swarm of missiles will diverge.
}}

{{tag
|name = dance
|type = float
|default = 0.0
|description = Adds a random vector to the position of a missile projectile every 8 frames, multiplied by the value of the tag. As the projectile is not rotated, a dancing swarm of missiles will remain relatively coherent.
}}

{{tag
|name = trajectoryHeight
|type = float
|default = 0.0
|description = Determines the height of the arc the missile will reach as it moves towards its target. A value of <code>0.0</code> will result in a flat trajectory, <code>1.0</code> will launch at 45°. Can be any value >= <code>0.0</code>; extreme values may require the {{taglink|tracks}} tag to be able to hit a target.
}}

====MissileLauncher Visuals====
A note about the missile exhaust flare: the size of the flare is determined by the model radius. The emit position of the flare is at (0,0,-radius) so the model may need careful adjustment to get the flare looking right.

{{tag
|name = smokeTrail
|type = bool
|default = false
|description = Does the missile projectile emit a smoke trail as it travels? Also for [[#StarburstLauncher]].
}}

===Rifle===
An instant hit weapon which does all its damage at once. Visually represented by a hardcoded tracer, firing and hitting effects. Rarely used.

There are no tags specific to this '''WeaponType'''.

===Shield (WeaponType)===
As the name suggests, not a weapon but a defensive shield. Can absorb or deflect ({{taglink|shieldrepulsor|true}}) projectiles. Individual weapons can be set to be intercepted or not by the shield using a [http://en.wikipedia.org/wiki/Mask_(computing) bitmask] (see [[Shield Interception Tag Use]]). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible ({{taglink|visible|false}}).

See the [[#shield]] sub-table section for other tags specific to this type.

===StarburstLauncher===
Fires a projectile that rises vertically for {{taglink|weaponTimer}} seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. Before spring 92.0 was the only weapon that can be {{taglink|targetable}} and act as an {{taglink|interceptor}}. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = weaponTimer
|type = float
|default = 0.0
|description = The time in seconds during which the missile ascends vertically before turning towards its target.
}}

===TorpedoLauncher===
Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with {{taglink|waterWeapon|true}} so they can fire underwater and target underwater units. An aircraft carrying a [[#TorpedoLauncher]] is a special case, the weapon turns into an [[#AircraftBomb]] projectile that will spawn a torpedo projectile on impact with water. Visually represented by a pointed black cuboid, usually the default object is replaced by a 3D model.

{{tag
|name = subMissile
|type = bool
|default = false
|description = Can the torpedo leave the water and target units and positions on land?
}}

===NoWeapon===
Not actually a '''WeaponType''', but an individual weapon requested by Spring to 'fill in the gaps' if a unit claims to have a weapon which isn't actually defined. There needs to be only one of these weapons and it is created by setting {{taglink|weaponName|"NOWEAPON"}} rather than by the {{taglink|weaponType}} tag.

==Sub Tables==

===damage===
The damage subtable lists how many hit points the weapon depletes against each armor class (See [[Armordefs.lua]]). It is a key-value map of armor class names and damage values. The special <code>default</code> entry is as the name suggests the default damage applied to any unit which does not belong to a listed armor class, or to shields.

For example a weapon which deals 100 damage by default but only 50 to units in the 'tank' armor class:

<code><pre>damage = {
default = 100,
tank = 50,
}</pre></code>

===shield===
The preferred way to create a shield or repulser is to use the shield subtable rather than the old shield tags.

The following tags are repulser specific:

{{tag
|name = repulser
|type = bool
|default = false
|description = Does the shield [http://dictionary.reference.com/browse/repulse?s=t repulse] (deflect) projectiles or absorb them? Btw its [http://springrts.com/mantis/view.php?id=4206 not repulsOr, but repulsEr]!}}

{{tag
|name = force
|type = float
|default = 0.0
|description = The force applied by the repulser to the weapon - higher values will deflect weapons away at higher velocities.}}

{{tag
|name = maxSpeed
|type = float
|default = 0.0
|description = The maximum speed the repulser will impart to deflected projectiles.}}

{{tag
|name = visibleRepulse
|type = bool
|default = false
|description = Is the (hard-coded) repulse effect rendered or not?}}

The following tags are general behaviour for all shields:

{{tag
|name = interceptType
|type = int
|default = 0
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this shield can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptedByShieldType}} will be intercepted by this shield (See [[Shield Interception Tag Use]]).}}

{{tag
|name = armorType
|type = string
|default = ""
|description = Specifies the armorclass of the shield; you can input either an [[Armordefs.lua|armorclass]] name OR a unitdef {{xtaglink|Gamedev:UnitDefs|name}} to share that unit's armorclass.}}

{{tag
|name = smart
|type = bool
|default = false
|description = Determines whether or not projectiles fired by allied units can pass through the shield (<code>true</code>) or are intercepted as enemy weapons are (<code>false</code>).}}

{{tag
|name = exterior
|type = bool
|default = false
|description = Determines whether or not projectiles fired within the shield's radius can pass through the shield (<code>true</code>) or are intercepted (<code>false</code>).}}

{{tag
|name = energyUse
|type = float
|default = 0.0
|description = The amount of the energy resource consumed by the shield to absorb or repulse weapons, continually drained by a repulser as long as the projectile is in range.}}

{{tag
|name = radius
|type = float
|default = 0.0
|description = The radius of the circular area the shield covers.}}

{{tag
|name = power
|type = float
|default = 0.0
|description = Essentially the maximum allowed hit-points of the shield - reduced by the <code>damage</code> of a weapon upon impact.}}

{{tag
|name = startingPower
|type = float
|default = 0.0
|description = How many hit-points the shield starts with - otherwise the shield must regenerate from <code>0</code> until it reaches maximum {{taglink|power}}.}}

{{tag
|name = powerRegen
|type = float
|default = 0.0
|description = How many hit-points the shield regenerates each second.}}

{{tag
|name = powerRegenEnergy
|type = float
|default = 0.0
|description = How much energy resource is consumed to regenerate each hit-point.}}

{{tag
|name = rechargeDelay
|type = float
|default = 0.0
|description = The delay in seconds before a shield begins to regenerate after it is hit.}}

The following tags control the visual aspects of the shield:

{{tag
|name = visible
|type = bool
|default = false
|description = Is the shield visible or not?}}

{{tag
|name = visibleHitFrames
|type = int
|default = 0
|description = The number of frames a shield becomes visible for when hit.}}

{{tag
|name = badColor
|type = float[3]
|default = {1.0, 0.5, 0.5} (Red)
|description = The RGB colour the shield transitions to as its hit-points are reduced towards <code>0</code>.}}

{{tag
|name = goodColor
|type = float[3]
|default = {0.5, 0.5, 1.0} (Blue)
|description = The RGB colour the shield transitions to as its hit-points are regenerated towards its maximum {{taglink|power}}.}}

{{tag
|name = alpha
|type = float
|default = 0.2
|description = The alpha transparency of the shield whilst it is visible.}}

===customParams===
The <code>customParams</code> subtable of a WeaponDef allows the game designer to give their weapons custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
Some games may have most WeaponDefs integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]].

S44 and MC:L implement an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance].

{{ExampleRepoLinks
|path = weapons/
|entity = WeaponDefs
}}

[[Category: Game Dev]]

Lua:Libarylinks

2015-09-13T18:03:41Z

Picassoct: /* Lua libraries */

[[Category:Lua]]

== Lua libraries ==

Many things you need for springs lua scripting, have been allready implemented and tested by others. It is considered good practice in allmost every software project to not reinvent the wheel. This statement does in no way imply you are unable to code this, but that you rather invest your time into not fixing the same bugs others found before you.
Other Projects have created lua-Librarys, lua files which you can include after copying (or referencing them on GitHub) into your project:

To use them in lua Units-scripts, download them into the same folder the Unitscript resides in and add
include "LibraryFileName.lua"

The referenced functions are now available. Many Librarys also include a Headerfile of all Functions made available.

If you want to include a Lua-Function into your gadget or widget

VFS.Include("Gamefolder/Relative/Path/ToLibrary/Library.lua

<big> Librarys</big>

=Journeywar =
Quality: Average

Table and UnitScript Operations

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_TableOp.lua?at=master

Library for Procedural Units and Buildings from Pieces

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_Build.lua?at=master

Miniature Operatings Systems and Statemachines

https://bitbucket.org/PicassoCT/journeywar/src/scripts/lib_OS.lua?at=master

=Zero-K=
Quality: Unknown

https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/constants.lua
https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/pieceControl.lua

=S44=
Quality: Unknown

https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_vector.lua
https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/utilities.lua

=BAR=
Quality: Unknown

Lua:Libarylinks

2015-09-13T18:02:02Z

Picassoct: /* Journeywar */

[[Category:Lua]]

== Lua libraries ==

Many things you need for springs lua scripting, have been allready implemented and tested by others. It is considered good practice in allmost every software project to not reinvent the wheel.
Other Projects have created lua-Librarys, lua files which you can include after copying (or referencing them on GitHub) into your project:

To use them in lua Units-scripts, download them into the same folder the Unitscript resides in and add
include "LibraryFileName.lua"

The referenced functions are now available. Many Librarys also include a Headerfile of all Functions made available.

If you want to include a Lua-Function into your gadget or widget

VFS.Include("Gamefolder/Relative/Path/ToLibrary/Library.lua

<big> Librarys</big>

=Journeywar =
Quality: Average

Table and UnitScript Operations

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_TableOp.lua?at=master

Library for Procedural Units and Buildings from Pieces

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_Build.lua?at=master

Miniature Operatings Systems and Statemachines

https://bitbucket.org/PicassoCT/journeywar/src/scripts/lib_OS.lua?at=master

=Zero-K=
Quality: Unknown

https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/constants.lua
https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/pieceControl.lua

=S44=
Quality: Unknown

https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_vector.lua
https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/utilities.lua

=BAR=
Quality: Unknown

Lua SyncedCtrl

2015-09-11T09:21:40Z

Picassoct: /* Unit Handling */ added Spring.SetUnitPieceParent

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

= Game End =
'''Spring.KillTeam''' {{new|83.0}}
( number teamID ) -> nil
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''' {{new|83.0}}
( {number allyTeamID1, number allyTeamID2, ...} ) -> nil
Will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed

= RulesParams =
string values are new since 95.0

'''Spring.SetUnitRulesParam'''
( number unitID, string paramName, number|string paramValue [, table losAccess] ) -> 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.SetTeamRulesParam'''
( number teamID, string paramName, number|string paramValue [, table losAccess] ) -> nil
see above for further documentation of losAccess

'''Spring.SetGameRulesParam'''
( string paramName, number|string paramValue [, table losAccess] ) -> nil
see above for further documentation of losAccess

= Resources =
'''Spring.AddTeamResource'''
( number teamID, string "metal" | "energy", number amount ) -> nil
'''Spring.UseTeamResource'''
( number teamID,
string "metal" | "energy",number amount |
{ metal = number amount, energy = number amount}
) -> nil | boolean hadEnough

'''Spring.SetTeamResource'''
( number teamID, string res, number amount ) -> nil

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


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

'''Spring.ShareTeamResource''' 0.82 and later
( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

= Teams =
'''Spring.SetAlly''' {{new|98.0}}
( number firstAllyTeamID, number secondAllyTeamID, boolean ally ) -> nil

Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID


'''Spring.AssignPlayerToTeam''' {{new|98.0}} {{Sourcelinkhash|7ed9a7e34814c60e5ae16281520cccc4daf3c367}}
( number playerID, number teamID)

= Unit Handling =
'''Spring.CreateUnit''' note: offmap positions are clamped! (you still can use MoveCtrl todo so)
( string "defName" | number unitDefID,
number x, number y, number z,
(number facing | string "facing"),
number teamID
[, boolean build = false]
[, boolean flattenGround = true]
[, number unitID]
[, number builderID]) -> number unitID | nil (meaning unit was not created)

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.


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

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


'''Spring.TransferUnit'''
( number unitID,
numer newTeamID
[, boolean given = true ] ) -> nil
if given=false, the unit is captured

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

'''Spring.SetUnitTooltip'''
( number unitID, string "tooltip" ) -> nil

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

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

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

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

'''Spring.SetUnitExperience'''
( number unitID, number experience ) -> nil

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

'''Spring.SetUnitCrashing''' {{new|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
( number unitID,
number enemyUnitID | number x, number y, number z, | nil,
[ boolean dgun = false ], [ boolean userTarget = false ] ) -> success

'''Spring.SetUnitMaxRange'''
( number unitID, number maxRange ) -> nil

'''Spring.SetUnitBlocking''' crushable new in version 85.0
( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil

'''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'''
( 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|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.SetUnitPieceParent''' {{new|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.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,]
["aimReady" = number value,] (<>0.0f := true)
}

'''Spring.SetUnitCollisionVolumeData'''
( number unitID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_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

'''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|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]

'''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|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|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|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|95.0}}
(number allyTeamID, number allyteamErrorSize
[, number baseErrorSize [, number baseErrorMult ]]) -> nil

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

== 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|97.0}}
( number unitid, number metal )

See also {{xtaglink|Gamedev:UnitDefs|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.SetFeatureReclaim'''
( number featureID, number reclaimLeft) -> nil

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

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


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

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

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

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

(like their feature counterparts at [[Lua_SyncedCtrl#Unit_Control]])

'''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.SetFeatureMidAndAimPos''' {{new|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|89.0}}
( number unitID, number radius, number height ) -> boolean success

'''Spring.SetFeatureBlocking'''
(number featureID, boolean blocking, boolean collidable) --> boolean

'''Spring.SetFeatureBlocking''' {{new|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#Get.2FSet|Lua_ConstCOB]]
 also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]

'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
 also see [[Animation-CobConstants#Custom_Variables|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:<code><pre>
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''' 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

== MetalAmount ==
'''Spring.SetMetalAmount''' {{new|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 ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}


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

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

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

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

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]


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

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


'''Spring.SpawnCEG'''
( string "cegname" | number 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

= 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.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.SetProjectileIsIntercepted''' {{new|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|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

'''Spring.SetProjectileAlwaysVisible''' {{new|95.0}}
(number projectileID, boolean alwaysVisible) --> nil
[[category: Lua]]

Lobby Development

2015-08-16T21:25:19Z

Picassoct: /* Lobby server development */

[[Engine_Development|Development]] < {{FULLPAGENAME}}

=Documentation=

==Protocol==
* [http://springrts.com/dl/LobbyProtocol/ HTML] (is updated once a day)
* [https://github.com/spring/LobbyProtocol/blob/master/ProtocolDescription.xml XML] (raw, always latest)

==Download Systems==
* [http://springrts.com/wiki/Dev:LobbyDownloadSystems Lobby Download Systems]

=Lobby client development=

==Useable lobby clients==

===[[SpringLobby]]===

===flobby===
Linux,
C++,
by cleanrock

[https://github.com/cleanrock/flobby github page]

===Weblobby===
cross-platform,
C++,
by CarRepairer

[https://github.com/springweblobby/swl-website#spring-web-lobby project site]

==WIP, abandoned or unusable==

===[[TASClient]]===
Windows,
Delphi,
unmaintained

===Alphalobby===
Windows,
C,
unmaintained

Alphalobby is still very much work in progress. If you still wish to use it, source available from the [http://code.google.com/p/alphalobby/source/checkout mercurial repository], binary available on the [http://springfiles.com/spring/lobby-clients/alphalobby springfiles page].

===CheeseLobby===
cross-platform,
Java,
by Cheesecan

[http://springrts.com/phpbb/viewtopic.php?f=64&t=24905 forum thread]

[https://github.com/jahwag/cheeselobby binaries and code]

===QtLobby===
cross-platform,
C++,
unmaintained

[https://github.com/tizbac/qtlobby project page]

===muslce===

Most useless spring lobby client ever

android,
java,
unmaintained

http://springrts.massive.ch/muslce/Muslce-20130617.tar.bz2

===Zero-K Lobby===

No longer uses the Spring lobby protocol

Windows/Linux,
C#,
by Licho & quantum

[https://github.com/ZeroK-RTS/Zero-K-Infrastructure/tree/master/ZeroKLobby Zero-K Lobby github]

=Libraries and frameworks=

==Spring-PythonBotFramework==
cross-platform,
Python, by
BrainDamage & koshi

A bot framework written in python. [https://github.com/renemilk/tasbot/wiki GitHub wiki]

==Go SpringLobbyClient==
cross-platform,
Go

A simple client implementation of the lobby protocol in Go.
[https://github.com/Agon/go-slc/ project page]

=Lobby server development=
==Actively maintained==
===UberServer===
cross-platform,
Python,
by aegis

The primary lobby server currently running on springrts.com. Most protocol commands in the primary documentation should be fully-functional and compatible between both uberserver and SpringLS (SpringLS hasn't seen as many updates recently). See the dedicated [[uberserver]] for more info.

===ZeroK Server===
cross-platform,
C#,
by Licho

The LobbyServer for Zero-K. Uses a diffrent Protocoll. Source can be found at
https://github.com/ZeroK-RTS/Zero-K-Infrastructure/tree/master/ZkLobbyServer

==Abandoned==
===SpringLS===
cross-platform,
Java,
hoijui

The longest-running lobby server, created by Betalord. You can fetch the sources through ''git''. Details can be found on the [http://github.com/spring/SpringLS development site].

[[Category: Lobby]]

Lua SyncedRead

2015-07-21T19:07:56Z

Picassoct: /* Ground Informations */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

== Game ==

=== Special TeamID Variables ===
(those special TeamIDs are not supported by all functions) 
'''Spring.ALL_UNITS''' 
'''Spring.MY_UNITS''' 
'''Spring.ALLY_UNITS''' 
'''Spring.ENEMY_UNITS'''

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

=== GameStates ===
'''Spring.IsGodModeEnabled'''
( ) -> boolean
'''Spring.IsCheatingEnabled'''
( ) -> boolean
'''Spring.IsDevLuaEnabled'''
( ) -> boolean
'''Spring.IsEditDefsEnabled'''
( ) -> boolean
'''Spring.AreHelperAIsEnabled'''
( ) -> boolean
'''Spring.FixedAllies'''
( ) -> nil | boolean

'''Spring.IsGameOver'''
( ) -> boolean

=== RulesParams ===
Those functions allow to save data per Game,Team and Unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
string values are new since 95.0

'''Spring.GetRulesInfoMap''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> nil | number value | string value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleIndex1] = {[ruleName1] = number | string value1}, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value | string value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleIndex1] = {[ruleName1] = number | string value1}, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value | string value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleIndex1] = {[ruleName1] = number | string value1}, ... }

=== Mod-/Map-Options ===
'''Spring.GetModOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }
'''Spring.GetMapOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }

! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition: 
"if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end" 
not only: 
"if (Spring.GetModOptions.exampleOption) then...end"

=== Speed/Time ===
'''Spring.GetGameSpeed''' As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

=== Vectors ===
'''Spring.GetWind'''
( ) -> number dirX, number dirY, number dirZ,
number strength, number normDirX, number normDirY, number normDirZ

'''Spring.GetHeadingFromVector'''
( number x, number z ) -> number heading
'''Spring.GetVectorFromHeading'''
( number heading ) -> number x, number z

== Sides/Factions ==
'''Spring.GetSideData'''
( string sideName ) -> nil | string startUnit, string caseSensitiveSideName
( number sideID ) -> nil | string sideName, string startUnit, string caseSensitiveSideName
( ) -> { [1] = { sideName=string,caseName=string,startUnit=string}, [2] = .., .. }

== Teams ==
=== StartBoxes/StartPositions ===
'''Spring.GetAllyTeamStartBox'''
( number allyID ) -> nil | number xmin, number zmin, number xmax, number zmax
'''Spring.GetTeamStartPosition'''
( number teamID ) -> nil | number x, number y, number z

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

'''Spring.GetPlayerInfo'''
( number playerID ) ->
nil | string "name", (PRE-83.0: in synced code this is "SYNCED_NONAME"!)
boolean active,
boolean spectator,
number teamID,
number allyTeamID,
number pingTime,
number cpuUsage,
string country,
number rank
table customPlayerKeys
'''Spring.GetPlayerControlledUnit'''
( number playerID ) -> nil | number unitID

'''Spring.GetAIInfo'''
( number teamID ) ->
number skirmishAIID,
string name,
number hostingPlayerID,
string shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN")
string version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN")
table options (synced & non-local => empty-table)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

'''Spring.GetAllyTeamInfo'''
( number allyteamID ) -> nil | table customTeamKeys

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
boolean isDead,
boolean isAiTeam,
string "side",
number allyTeam,
table customTeamKeys,
number incomeMultiplier
'''Spring.GetTeamResources'''
( number teamID, string "metal" | "energy" ) ->
nil | number currentLevel,
number storage,
number pull,
number income,
number expense,
number share,
number sent,
number received
'''Spring.GetTeamUnitStats'''
( number teamID ) ->
nil | number killed,
number died,
number capturedBy,
number capturedFrom,
number received,
number sent
'''Spring.GetTeamResourceStats''' 0.82 and later
( number teamID, string "metal" | "energy" ) ->
nil | number used,
number produced,
number excessed,
number received,
number sent
'''Spring.GetTeamStatsHistory'''
( number teamID [, number startIndex [, number endIndex = startIndex ]]) ->
nil |
number cur_max_index |
{
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''Spring.GetTeamLuaAI'''
( number teamID ) -> string "luaAI"

Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, so maybe depends, but in my LuaAI.lua name is on first position...

=== Teams/PlayersAllied ===
'''Spring.AreTeamsAllied'''
( number teamID1, number teamID2 ) -> nil | boolean
'''Spring.ArePlayersAllied'''
( number playerID1, number playerID2 ) -> nil | boolean

== Units ==
=== GetUnits ===
'''Spring.GetAllUnits'''
( ) -> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetTeamUnits'''
( number teamID ) -> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitsSorted'''
( number teamID ) -> nil |
unitDefTable = {
[number unitDefID] = { [1] = [number unitID], etc... },
etc...
}
'''Spring.GetTeamUnitsCounts'''
( number teamID ) -> nil | countTable = { [number unitDefID] = count, etc... }
'''Spring.GetTeamUnitsByDefs'''
( number teamID, number unitDefID | { number unitDefID1, ... } )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitDefCount'''
( number teamID, number unitDefID ) -> nil | number count
'''Spring.GetTeamUnitCount'''
( number teamID ) -> nil | number count

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }

plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0


'''Spring.GetUnitNearestAlly'''
( number unitID [, number range ] ) -> nil | number unitID
'''Spring.GetUnitNearestEnemy'''
( number unitID [, number range [, bool useLOS]] ) -> nil | number unitID

Post 95.0 this no longer returns neutral units

=== Unit Informations ===
'''Spring.ValidUnitID'''
( number unitID ) -> boolean
'''Spring.GetUnitIsDead'''
( number unitID ) -> nil | boolean
Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise 
keep this in mind when using (not Spring.GetUnitIsDead())

'''Spring.GetUnitTooltip'''
( number unitID ) -> nil | string tooltip
'''Spring.GetUnitDefID'''
( number unitID ) -> nil | number unitDefID
'''Spring.GetUnitTeam'''
( number unitID ) -> nil | number teamID
'''Spring.GetUnitAllyTeam'''
( number unitID ) -> nil | number allyID
'''Spring.GetUnitLineage''' Removed from version 0.83.x 
( number unitID ) -> nil | number lineage | number lineage, boolean lineageIsRoot
'''Spring.GetUnitNeutral'''
( number unitID ) -> nil | boolean neutral
'''Spring.GetUnitHealth'''
( number unitID ) -> nil | number health, number maxHealth, number paralyzeDamage,
number captureProgress, number buildProgress
build Progress is returned as floating Point between 0.0 and 1.0

'''Spring.GetUnitArmored''' armorMultiple new in version 0.83.x
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitMaxRange'''
( number unitID ) -> nil | number maxEngagementRange
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitHarvestStorage'''
( number unitID ) -> nil | number metal
See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.

'''Spring.GetUnitMetalExtraction''' 0.82+ and later
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' {{new|85.0}}
( number unitID ) -> nil | boolean blocking, boolean crushable
{{new|95.0}} Now return values are:
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

'''Spring.GetUnitPosition'''
( number unitID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
since 89.0, returns the base (default), middle or aim position of the unit.

'''Spring.GetUnitBasePosition''' Deprecated in 89.0, use GetUnitPosition
( number unitID ) -> nil | number x, number y, number z
returns the bottom of the unit.

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
returns the direction vector

'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
returns heading directions used in COB scripts

'''Spring.GetUnitRotation''' {{New|95.0}}
(number unitID) --> nil | number pitch, number yaw, number roll
Marked as (WIP) in changelog

'''Spring.GetUnitVelocity''' velw new in 95.0
( number unitID ) -> nil | number velx, number vely, number velz, number velLength
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' returns what unit a constructor/factory is currently building
( number unitID ) -> nil | number unitID
'''Spring.GetUnitCurrentBuildPower''' {{new|92.0}}
( number unitID ) -> nil | number buildPower
'''Spring.GetUnitNanoPieces'''
( number unitID ) -> nil | { [1] = number piece1, etc ... }
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
possible types are: los, airLos, radar, sonar, seismic, radarJammer & sonarJammer

'''Spring.GetUnitLosState''' raw is only available in gadgets
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil | number raw |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' surfaceDist new in 95.0
( number unitID1, number unitID2 [, boolean 2D] [, boolean surfaceDist] ) -> nil | number distance
returns the distance of 2 units, surfaceDist calculates the distance between the unitsphere surfaces instead of their midpos

'''Spring.GetUnitDefDimensions'''
( number unitDefID ) -> nil |
{
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

==== Unit Weapon Informations ====
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

'''Spring.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ

'''Spring.GetUnitWeaponTryTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponTestTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponTestRange''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponHaveFreeLineOfFire''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponCanFire''' {{new|95.0}}
( number unitID, number weaponNum ) -> nil | boolean canFire

'''Spring.GetUnitWeaponTarget''' {{new|95.0}}
( number unitID, number weaponNum ) -> nil |
number 0 | number 1, bool isUserTarget, number unitID |
number 2, bool isUserTarget, { number posX, number posY, number posZ } |
number 3, bool isUserTarget, number ProjectileID

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

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

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want move a piece to another piece.

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)

'''Spring.GetUnitPieceMatrix'''
( number unitID, number piece ) -> { [1] = number, ... , [16] = number }
'''Spring.GetUnitPieceList'''
( number unitID ) -> { [1] = string "piecename", ... , [pieceNumN] = string "piecename" }
'''Spring.GetUnitPieceMap'''
( number unitID ) -> { "piecename1" = pieceNum1, ... , "piecenameN" = pieceNumN }
'''Spring.GetUnitPieceInfo'''
( number unitID, number piece ) -> {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}
"parent" field {{New|95.0}}

'''Spring.GetUnitScriptPiece'''
( number unitID [, number scriptPiece ] )
-> nil | { scriptPieceNum = number modelPieceNum } | number modelPieceNum

This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get via Cob2Lua a pieceID you have to translate it with this function. Btw the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.

=== CommandQueues ===
'''Spring.GetUnitCommands''' 
'''Spring.GetCommandQueue''' (Alias)
( number unitID, number count = 0 ) -> nil | number commandQueueSize {{new|96}}
( number unitID [, number count = -1] )
-> nil | table commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}

This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]

'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' (cleans the buildqueue of things the unit can't build itself)
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID, number count = 0 ) -> nil | number commandQueueSize {{new|96}}
( number unitID [, number count = -1 ] )
-> nil | table commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}

'''Spring.GetFactoryCounts''' (used to get the buildqueue of a factory, seems screwed o_O)
( number unitID [, number count [, boolean addCMDs ] ] ) -> nil | commandQueueTable = {
[2] = { [number unitDefID | number -cmdID] = number count }, ...
}

=== Command Descriptions/Buttons ===
'''Spring.GetUnitCmdDescs'''
( number unitID [, number startIndex [, number endIndex ] ] ) -> nil | {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}
'''Spring.FindUnitCmdDesc'''
( number unitID, number cmdID ) -> nil | number index

== Features ==
=== GetFeatures ===
'''Spring.GetFeaturesInRectangle'''
( number xmin, number zmin, number xmax, number zmax )
-> featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
since 89.0, returns the base (default), middle or aim position of the feature.

'''Spring.GetFeatureVelocity''' {{new|95.0}}
( number featureID [, boolean norm] )
-> nil | number velx, number vely, number velz, number velLength

'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

'''Spring.GetFeatureBlocking'''
(number featureID) --> boolean collidable, boolean crushable, boolean blocking
{{new|95.0}} Now return values are:
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

== COB ==
'''Spring.GetCOBUnitVar'''
( number unitID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBTeamVar'''
( number teamID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBAllyTeamVar'''
( number allyID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBGlobalVar'''
( integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY

== Ground ==
=== Ground Informations ===
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundNormal'''
( number x, number z ) -> number x, number y, number z, number slope
'''Spring.GetGroundInfo'''
( number x, number z ) -> string "Type", number metal, number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed,
number shipSpeed, boolean receiveTracks
'''Spring.GetGroundBlocked'''
( number x, number z |
number x1, number z1, number x2, number z2 )
-> nil | string "feature", number featureID | string "unit", number unitID
'''Spring.GetGroundExtremes'''
( ) -> nil | number minHeight, number maxHeight

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

'''Spring.GetMetalMapSize'''
( ) -> number sizeX, number sizeY

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetTerrainTypeData''' {{new|92.0}}
( number i )
-> nil | string "name", number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed, number shipSpeed,
boolean receiveTracks

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove
{{New|95.0}} parameters now are:
number unitDefID,
number pos.x, number pos.y, number pos.z
[, number dir.x
[, number dir.y
[, number dir.z
[, boolean testTerrain
[, boolean testObjects
[, boolean centerOnly ]]]]]]
) --> boolean

'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos''' optional param ''facing'' supported in 0.83 and later
( number unitDefID, number x, number y, number z[, number facing] )
-> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState''' jammed new in 95.0
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar, boolean jammed
jammed indicates if a position is actively being radar- or sonar-jammed by '''any''' allyteam

'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

( number xmin, number zmin, number xmax, number zmax
[, boolean excludeWeaponProjectiles
[, boolean excludePieceProjectiles] ] )
-> nil | projectileTable = { [1] = number projectileID, etc... }

'''Spring.GetProjectileOwnerID''' {{new|99.0}}
(number projectileID) -> nil | number unitID

'''Spring.GetProjectileTeamID''' {{new|99.0}}
(number projectileID) -> nil | number teamID

'''Spring.GetProjectileDefID'''
(number projectileID) -> nil | number weaponDefID
using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

'''Spring.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece

'''Spring.GetProjectileTarget'''
( number projectileID )
Pre 95.0: -> nil | number targetID, string targetTypeStr
Post 95.0: -> nil | [number targetTypeInt, number targetID | table targetPos = {x, y, z}]

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.GetProjectileIntercepted''' {{new|99.0}}
( number projectileID ) -> nil | boolean isBeingIntercepted

'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
{{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons

'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity

'''Spring.GetPieceProjectileParams''' {{new|95.0}}
( number projectileID ) -> nil | number explosionFlags, number spinAngle,
number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
Where explosionFlags use binary flags with the following integer equivalents:
more info [http://springrts.com/wiki/Animation-CobConstants#explode here]
SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 

'''Spring.GetProjectileTimeToLive''' {{new|99.0}}
( number projectileID ) -> nil | number ttl

'''Spring.GetProjectileDirection''' {{new|95.0}}
( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z

'''Spring.GetProjectileSpinAngle''' Deprecated in 95.0
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed''' Deprecated in 95.0
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec''' Deprecated in 95.0
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua:Libarylinks

2015-07-06T10:07:23Z

Picassoct: /* S44 */

[[Category:Lua]]

== Lua libraries ==

Many things you need for springs lua scripting, have been allready implemented and tested by others. It is considered good practice in allmost every software project to not reinvent the wheel.
Other Projects have created lua-Librarys, lua files which you can include after copying (or referencing them on GitHub) into your project:

To use them in lua Units-scripts, download them into the same folder the Unitscript resides in and add
include "LibraryFileName.lua"

The referenced functions are now available. Many Librarys also include a Headerfile of all Functions made available.

If you want to include a Lua-Function into your gadget or widget

VFS.Include("Gamefolder/Relative/Path/ToLibrary/Library.lua

<big> Librarys</big>

=Journeywar =
Quality: Poor

Table and UnitScript Operations

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_TableOp.lua?at=master

Library for Procedural Units and Buildings from Pieces

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_Build.lua?at=master

Miniature Operatings Systems and Statemachines

https://bitbucket.org/PicassoCT/journeywar/src/scripts/lib_OS.lua?at=master

=Zero-K=
Quality: Unknown

https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/constants.lua
https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/pieceControl.lua

=S44=
Quality: Unknown

https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_vector.lua

=BAR=
Quality: Unknown

Lua:Libarylinks

2015-07-06T10:03:09Z

Picassoct: /* Lua libraries */

[[Category:Lua]]

== Lua libraries ==

Many things you need for springs lua scripting, have been allready implemented and tested by others. It is considered good practice in allmost every software project to not reinvent the wheel.
Other Projects have created lua-Librarys, lua files which you can include after copying (or referencing them on GitHub) into your project:

To use them in lua Units-scripts, download them into the same folder the Unitscript resides in and add
include "LibraryFileName.lua"

The referenced functions are now available. Many Librarys also include a Headerfile of all Functions made available.

If you want to include a Lua-Function into your gadget or widget

VFS.Include("Gamefolder/Relative/Path/ToLibrary/Library.lua

<big> Librarys</big>

=Journeywar =
Quality: Poor

Table and UnitScript Operations

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_TableOp.lua?at=master

Library for Procedural Units and Buildings from Pieces

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_Build.lua?at=master

Miniature Operatings Systems and Statemachines

https://bitbucket.org/PicassoCT/journeywar/src/scripts/lib_OS.lua?at=master

=Zero-K=
Quality: Unknown

https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/constants.lua
https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/pieceControl.lua

=S44=
Quality: Unknown

=BAR=
Quality: Unknown

Lua:Libarylinks

2015-07-06T10:01:35Z

Picassoct: /* Zero-K */

== Lua libraries ==
Many things you need for spring-lua scripting,
have been allready implemented and tested by others. It is considered good practice in allmost every software project to not reinvent the wheel.
Other Projects have created lua-Librarys, lua files which you can include after copying (or referencing them on GitHub) into your project:

To use them in lua Units-scripts, download them into the same folder the Unitscript resides in and add
include "LibraryFileName.lua"

The referenced functions are now available. Many Librarys also include a Headerfile of all Functions made available.

If you want to include a Lua-Function into your gadget or widget

VFS.Include("Gamefolder/Relative/Path/ToLibrary/Library.lua

<big> Librarys</big>

=Journeywar =
Quality: Poor

Table and UnitScript Operations

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_TableOp.lua?at=master

Library for Procedural Units and Buildings from Pieces

https://bitbucket.org/PicassoCT/journeywar/src/8cbe713fe3e1027a88f40f9a70f87b788a448048/scripts/lib_Build.lua?at=master

Miniature Operatings Systems and Statemachines

https://bitbucket.org/PicassoCT/journeywar/src/scripts/lib_OS.lua?at=master

=Zero-K=
Quality: Unknown

https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/constants.lua
https://github.com/ZeroK-RTS/Zero-K/blob/c4af9dc6043eb8d0a5d48b34bfe3ad55190b1e73/scripts/pieceControl.lua

=S44=
Quality: Unknown

=BAR=
Quality: Unknown