Spring - User contributions [en]

Associated Development Groups

2015-04-14T17:36:11Z

8611: /* Lobby Channels */ descriptions

[[Engine_Development|Development]] < {{FULLPAGENAME}}

There are numerous people and groups involved in the Spring project, from development to content creation. This is meant as a cumulative list of associated groups to ease communication between them.

= Websites =
== Games ==
=== Balanced Annhiliation ===
*[http://balancedannihilation.org BalancedAnnihilation.org] - Official website and forum

=== Evolution RTS ===

*[http://www.evolutionrts.info/ www.evolutionrts.info] - Official Website & Forums
*[http://www.wiki.evolutionrts.info/ www.wiki.evolutionrts.info] - Evolution RTS Wiki (Game Manual/How to Play/Unit Guide/Etc)
*[http://gplus.to/EvolutionRTS gplus.to/EvolutionRTS] - Evolution RTS Google+ Page (development updates, twitter style)
*[http://www.source.evolutionrts.info/ www.source.evolutionrts.info] - Evolution RTS Source Code SVN Repository (Google Code)
*[http://www.bugs.evolutionrts.info/ www.bugs.evolutionrts.info] - Evolution RTS Bug Tracker
*[http://www.desura.com/games/evolution-rts www.desura.com/games/evolution-rts] - Evolution RTS on Desura
*[https://www.facebook.com/EvolutionRTS www.facebook.com/EvolutionRTS] - Evolution RTS on Facebook

=== Imperial Winter ===
*[http://www.imperialwinter.com ImperialWinter.com] - Official Website & Forums

=== Spring: 1944 ===
*[http://www.spring1944.net Spring1944.net] - Official Website & Forums

=== Zero-K ===
*[http://www.zero-k.info Zero-K.info] - Official Website & Forums

== Misc ==
*[http://www.moddb.com/engines/spring/ Spring on moddb.com]
*[http://answers.springlobby.info/ Spring Q&A Forum]
*[http://springlobby.info/ SpringLobby's Redmine] - The SpringLobby group is the biggest collaborative lobby client work in the Spring community. This is their project's homepage, containing bug tracker and helpful information on their wiki.
*[http://www.smoth.net/phpBB3/ Smoth's Development Forum] - the forum for the games Gundam RTS, Expand and Exterminate, Kernel Panic.
*[http://www.irit.fr/ProgAndPlay/index_en.php Prog&Play] - AI programming game/class using Spring and [[Kernel_Panic|Kernel Panic]]

= Lobby Channels =
'''#moddev''' - real game developers answer your questions

'''#lua''' - ask for help how to read tutorials

'''#sy''' - check back when the new enine will be released

= YouTube Channels =
A unsorted list of youtube accounts that uploaded at least some spring contest.

The amount, context and quality varies.

http://www.youtube.com/PROrANDY

http://www.youtube.com/SteveZissouSpring

http://www.youtube.com/xtaboi

http://www.youtube.com/ForbodingAngel

http://www.youtube.com/knorker

http://www.youtube.com/playlist?list=PL3C03292C49A62F81&feature=plcp (sabutai replay playlist )

http://www.youtube.com/omnianti0

http://www.youtube.com/user/rattle235/

http://www.youtube.com/user/jazcash

http://www.youtube.com/user/Cuntipede

http://www.youtube.com/user/Ruwetuin

http://www.youtube.com/user/xtaboi

http://www.youtube.com/user/kile4568

http://www.youtube.com/user/Canonfudder

http://www.youtube.com/user/wagonrepairer

http://www.youtube.com/user/xenoargh

http://www.youtube.com/user/smoth7

http://www.youtube.com/user/OpenMachines

http://www.youtube.com/user/XHC#p/ur

http://www.youtube.com/user/Pendrokar#p/u

http://www.youtube.com/user/XtaReplay

http://www.youtube.com/user/Kleaut

http://www.youtube.com/user/kylelck

[http://www.youtube.com/playlist?list=PLOj_JX39U3OMuthcAPhuT9XcbZWoQaswZ Enetheru's channel] - primarily blender related terrain and feature creation.

https://www.youtube.com/user/gajop

[[Category: Development]]

Armordefs.lua

2015-04-14T17:31:12Z

8611: more efficient with Lua

This file sorts units into different armor classes. Weapons can deal different amount of damage to different armor classes.

=Location=
<code>armordefs.lua</code> is a file in the <code>Gamedata/</code> directory of a Spring Game.

=Source=
The engine source code which parses the data from this file is viewable here:

* {{sourcelink|file=rts/Sim/Misc/DamageArrayHandler.cpp}}

=Details=
By default a damage class named "default" exists and every unit is in it.
So if all your weapons only deal "default" damage then this file is not needed.

=Example=
<code><pre>
local armorDefs = {
tanks = {
"supertank",
"megatank",
},

infantry = {
"dude",
},
}

--NOTE: only needed for <95.0 (before engine was expecting a cryptic format)
if not(Game) or not(Game.version) then
for categoryName, categoryTable in pairs(armorDefs) do
local t = {}
for _, unitName in pairs(categoryTable) do
t[unitName] = 1
end
armorDefs[categoryName] = t
end
end

return armorDefs</pre></code>

=Weapon Example=
Goes with above example, a weapon that deals 60 damage to infantry but only 5 damage to tanks:
<code><pre>
...
damage = {
infantry = 60,
tanks = 5,
},
...
</pre></code>

=Shields=
In engine versions =< 96.0 the damage dealt to shields is the weapon's ''default'' value.
This [http://springrts.com/mantis/view.php?id=4450 changed] in v98.0

Putting a shield into an armor class is analogical to units, ie. the armorDefs entry is its weaponDef name:
<code><pre>
armorDefs = {
units = { "shieldbot" },
shields = { "shieldbot_shield" }
}</pre></code>

Then in some damage table:
<code><pre>damage = {
default = 123,
units = 456,
shields = 789
}</pre></code>

=More efficient with Lua=
Spring armor categories are kludgy and messy because they are extremely inefficient. There are a lot of inconsistencies.
In some cases, only the first category listed will be obeyed. At other times in that same list, all will be obeyed.

In other words, do not rely on categories too heavily, because you will end up quite frustrated with the results.

You should look at smoth's armor system code. Evo uses it rather extensively.

=Links to more Examples=
[http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/gamedata/armordefs.lua zero-K] 
Contains scripting to take into account various things like EMP damage.

[http://code.google.com/p/springtutorialgame/source/browse/trunk/SpringTutorialGame.sdd/Gamedata/armordefs.lua|Spring Tutorial Game] 
Uses default damage class, except for one unit that is "armored."

[http://sourceforge.net/p/mwspring/code/899/tree/Gamedata/armordefs.lua MechCommander: Legacy] 
Automatically assigns units to an armor class based on [[Gamedev:UnitDefs|UnitDef]] tags and custom params.

[[Category:gamedata]]

Movedefs.lua

2015-04-14T17:22:34Z

8611: added: check movedefs

=Movedefs.lua=
==Location==
<code>movedefs.lua</code> is a file in the <code>Gamedata/</code> directory of a Spring Game.

==Purpose==
This file defines '''MoveClasses''' which are used to determine pathing for units.

==Source==
The engine source code which parses the data from this file is viewable here:
* {{sourcelink|file=rts/Sim/MoveTypes/MoveDefHandler.cpp}}

==Data Types==
{{DataTypes}}

==Details==
A mobile unit is assigned a '''MoveClass''' using the {{xtaglink|Gamedev:UnitDefs|movementClass}} tag. The engine determines the unit's pathfinding based on the properties of the '''MoveClass''', so analogous properties (e.g. {{xtaglink|Gamedev:UnitDefs|footprintX}}) in the [[Gamedev:UnitDefs|UnitDef]] should be the same for optimal behaviour.

All '''MoveClasses''' must belong to one of four possible types. A '''MoveClass''' is assigned a type simply by including it within the name string e.g. <code>Tank_MyMoveClassName</code>. Types are used in '''[[Mapdev:terraintype|TypeMaps]]''' of Spring maps, which allow mappers to set per-type speed multipliers.

===Types===
* <code>Bot</code> - A ground based '''MoveClass'''. The default type if no matching type string is found.
* <code>Tank</code> - A ground based '''MoveClass'''. Identical to <code>Bot</code> other than interaction with '''TypeMaps'''.
* <code>Ship</code> or <code>Boat</code> - Are synonyms. All ships / boat '''MoveClasses''' must belong to this type to behave as ships.
* <code>Hover</code> - All hovercraft '''MoveClasses''' (traverse any depth of water without speed reduction) must belong to this class, as well as having {{xtaglink|Gamedev:UnitDefs|canHover}} in their [[Gamedev:UnitDefs|UnitDef]] to behave as hovers.

==MoveClass Tags==
{{tag
|name = name
|type = string
|default = ""
|description = The name of the '''MoveClass'''. Usually passed by the sub-table variable name rather than using this tag (See [[#Example]]). Prior to 9.50 this had to contain "tank", "hover", "ship" or "boat" respectively for non-Bot types. This is now set using {{taglink|speedModClass}}.
}}

{{tag
|name = speedModClass
|type = int
|default = 1
|special = {{new|95.0}}
|description = Determines the speed modifier class used (See [[Mapdev:terraintype]]). Accepted values are <code>0</code> = Tank, <code>1</code> = KBot, <code>2</code> = Hover, <code>3</code> = Ship.
}}

{{tag
|name = footprintX
|type = int
|default = 1
|description = How wide the '''MoveClass''' 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|Gamedev:UnitDefs|footprintX}} of its [[Gamedev:UnitDefs|UnitDef]].
}}

{{tag
|name = footprintZ
|type = int
|default = footprintX
|description = How wide the '''MoveClass''' 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|Gamedev:UnitDefs|footprintZ}} of its [[Gamedev:UnitDefs|UnitDef]].
}}

{{tag
|name = crushStrength
|type = float
|default = 10.0
|description = Power of a unit with this '''MoveClass''' to crush features and units. Any features with a {{xtaglink|Gamedev:FeatureDefs|crushResistance}} less than this value will be crushed on contact. Any units with crushing enabled via [[Lua_SyncedCtrl#Unit_Control|Spring.SetUnitBlocking]]), in an impact where collider impulse exceeds collidee impulse and whose {{xtaglink|Gamedev:UnitDefs|crushResistance}} is less than this value will also be crushed.
}}

{{tag
|name = maxSlope
|type = float
|default = 60.0 (15.0 for hover types)
|description = The maximum steepness of slope a unit with this '''MoveClass''' can climb in degrees. For further details see [[#How_slope_is_determined]].}}

{{tag
|name = slopeMod
|type = float
|default = 4.0 / (maxSlope + 0.001)
|description = How much a slope will slow a unit, <code>0</code> means no slowdown.
}}

{{tag
|name = avoidMobilesOnPath
|type = bool
|default = true
|description = Do the units attempt to avoid other mobile units when pathing?
* Pro: groups moving without a ctrl-order clump much less
* Contra: groups moving with a ctrl-order are less organized
}}

{{tag
|name = allowTerrainCollisions
|type = bool
|default = true
|special = {{new|96.0}}
|description = Disable this to improve handling of large (>4 x 4) footprint units (See {{mantis|4217}}).
}}

=== Heat Tags ===
These tags are used in unit avoidance.
{{tag
|name = heatMapping
|type = bool
|default = false
|description = This enables/disables generation and usage of path heats.
}}

{{tag
|name = heatMod
|type = float
|default = 0.0042
|description = The pathfinder cost modifier that is multiplied by the heat of the current square.
}}

{{tag
|name = heatProduced
|type = int
|default = 30
|description = How much heat to place on a square if a path goes through it. <code>heat set = max(currentSquareHeat, heatProduced)</code>.
}}

=== Tank & Bot-Only Tags ===
{{tag
|name = depthMod
|type = float
|default = 0.1
|description = How much water will slow amphibious units. The deeper the water, the slower the movement.Replaced with a subtable in Spring 86.x
}}

{{tag
|name = maxWaterDepth
|type = float
|default = 0.0
|description = The maximum depth of water in [[elmo]]s the unit can wade through.
}}

=== Ship-Only Tags ===
{{tag
|name = minWaterDepth
|type = float
|default = 10.0
|description = The minimum depth of water in [[elmo]]s the ship requires to float in.
}}

{{tag
|name = subMarine
|type = bool
|default = false
|description = Is the ship a submarine; can it move underneath other ships?
}}

==Sub Tables==
===depthModParams===
Only read for <code>Bot</code> and <code>Tank</code> '''MoveClasses''', the depthModParams group contains several sub-tags. Depthmod is a system for changing the speed of units depending on how deep they are underwater.

<code>
new formula is given by
if h < depthModParams.minHeight: 1.0
if h > depthModParams.maxHeight: 0.0
else:
depthScale = MAX(0.01, MIN(depthModParams.maxScale, (a * h * h) + (b * h) + c))
depthMod = 1 / depthScale
where
h = unit's absolute height below water surface
a = depthModParams.quadraticCoeff
b = depthModParams.linearCoeff
c = depthModParams.constantCoeff
</code>

{{tag
|name = minHeight
|type = float
|default = 0.0
|description = The minimum depth where the depthMod curve applies. If the unit is shallower than the minHeight, no change in speed occurs.
}}

{{tag
|name = maxHeight
|type = float
|default = MAX_FLOAT
|description = The maximum depth where the depthMod curve applies. If the unit is deeper than the maxHeight, the unit is immobilized.
}}

The following tags control the behavior of the unit within the active portion of the curve (depth is greater than {{taglink|minHeight}} but less than {{taglink|maxHeight}}). It would be best to simply open up your graphing program of choice and use the provided formula, but if you're scared of graphs you should read the descriptions below:

{{tag
|name = maxScale
|type = float
|default = MAX_FLOAT
|description = This is the cap on how severe the depth effect can be. That is if the value is 2, the slowest the unit will go because of depth is half-speed. 4 = a quarter speed, and so on.
}}

{{tag
|name = quadraticCoeff
|type = float
|default = 0.0
|description = The application of the speed-divider effect is modelled as a quadratic. This is the "depth-squared" component of that. That is, a value set here will be applied exponentially as the unit gets deeper, therefore it is best to use very small numbers for this tag.
}}

{{tag
|name = linearCoeff
|type = float
|default = depthMod
|description = The application of the speed-divider effect is modelled as a quadratic. This component makes divisor increase linearly with the depth of the unit. So with a value of 0.1, for example, a unit would go from 1/2 speed to 1/3 speed and 1/3 speed to 1/4 speed each time it goes 10 units deeper.
}}

{{tag
|name = constantCoeff
|type = float
|default = 1.0
|description = The application of the speed-divider effect is modelled as a quadratic. This is the constant component of the divisor. If you want a gradual decrease of speed and your {{taglink|minHeight|0}} (the waterline) then this value '''must''' be 1. Using less than 1 will cause the unit to go ''faster'' as it hits the water, and using greater than 1 will cause the unit to abruptly slow down the moment it gets its feet wet. If you're not using {{taglink|minHeight|0}}, you'll have to adjust this value accordingly to get a smooth application of the depthMod divider.
}}

===speedModMults===
{{new|86.0}}

These previously hard-coded variables allow control over how the pathfinder (default only, not [[QTPFS]], see [[Modrules.lua]]) calculates the cost for a '''MoveClass''' for squares containing mobile units, if and only if {{taglink|avoidMobilesOnPath|true}}.
{{tag
|name = mobileBusyMult
|type = float
|default = 0.1
|description = The cost multiplier for mobile units which are 'Busy'; Not currently being built and with a non-empty command queue, but not moving on a path. Clamped to values above <code>0.01</code>.}}

{{tag
|name = mobileIdleMult
|type = float
|default = 0.35
|description = The cost multiplier for mobile units which are 'Idle'; Either currently being built or with an empty command queue. Clamped to values above <code>0.01</code>.}}

{{tag
|name = mobileMoveMult
|type = float
|default = 0.65
|description = The cost multiplier for mobile units which are 'Moving'; Trying to follow their own path. Clamped to values above <code>0.01</code>.
}}

==How slope is determined==
Spring doesn't represent terrain slopes in degrees, internally it uses
<code>(1.0 - the terrain normal's y-component)</code> so the slope of vertical faces is <code>1</code> and that of horizontal ones <code>0</code>. A unit's <code>maxSlope</code> value (which is in
degrees in its movedef) is converted so that the "can we go here?" (ie
"<code>maxSlope > terrainSlope</code>?") comparisons are meaningful, the formula
is <code>1.0 - cos(DEG2RAD(maxSlope * 1.5))</code>. If you want to know the terrain angle in degrees, compute <code>RAD2DEG(arccos(1.0 - terrainSlope))</code>. For a bot with a <code>maxSlope</code> of 36 degrees (~0.41221 in "Spring format"), the maximum tolerable terrain angle is approximately

<code>RAD2DEG(arccos(1.0 - 0.41221))</code>

or 54 degrees. If <code>maxSlope</code> was <code>30</code>, the MTTA would be 45, and if it was <code>60</code> (the highest sensible value due to that 1.5 scalar and the absence of overhanging cliffs) the bot could mount any terrain. In other words you do not need the long mathematical derivation, just remember that
<code>maxTerrainAngle = maxSlope * 1.5</code>

--kloot, Thu Jul 31, 2008

==Code to check your movdefs==
{{forumlink|topic=24866|title=A resource to check movedefs}} that game developers have used for years and find it quite useful.

==Example==
===External Examples===
[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/gamedata/movedefs.lua 'Balanced Annihilation' movedefs.lua]

[http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/gamedata/movedefs.lua?&view=markup 'Spring: 1944' movedefs.lua]

[http://code.google.com/p/springtutorialgame/source/browse/trunk/SpringTutorialGame.sdd/Gamedata/movedefs.lua 'Spring Tutorial Game' movedefs.lua]

[http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/gamedata/movedefs.lua 'ZeroK' movedefs.lua]

[[Category:Gamedata]]

User:Knorke/Sandbox3

2015-04-14T17:12:05Z

8611: expanded the part about more advanced scripting

==Interessted in creating a game on the spring engine?==

Honestly, here isn't really the place to ask. The amount of available developers here is 0. We are all working on our own projects.

Sucks, but we are a small community. I would suggest posting on moddb. There are usually people there looking for work.

User:Knorke/Sandbox2

2015-04-14T17:07:30Z

8611: updated for recent advances

This text describes making a gadget.

<code><pre>
"move blah now;" so all your shit happens virtually instantly.
</pre></code>

Lua:Tutorial GettingStarted

2015-04-14T17:03:26Z

8611: edited with better beginner widget

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

<code><pre>

function widget:GetInfo()
return {
name = "Name as shown in widget list",
desc = "",
author = "john doe",
date = "date",
license = "PD",
layer = 0,
experimental = false,
enabled = true
}
end

local stringOfWords = "BLAH BLAH BLAH"
local toggle

function widget:Initialize()
Spring.Echo(stringOfWords .. " I STARTED LOOK AT ME JIM!")
end

function widget:Update(frame)
if(toggle == true) then
Spring.Echo("TOCK")
toggle = false
else
Spring.Echo("TICK")
toggle = true
end
end

</pre></code>
[[category: Lua]]

General Resources

2015-04-14T08:37:11Z

8611: /* Various */ added: Game Development Tutorials & Resources subforum

[[Engine_Development|Development]] < [[Game and Unit development]] < General Resources

=Textures=
[http://springrts.com/phpbb/viewtopic.php?t=7093&start=0 Texture Competition 0001 - Metal] 
[http://springrts.com/phpbb/viewtopic.php?t=7188&start=0 Texture Competition 0002 - Camo] 
[http://springrts.com/phpbb/viewtopic.php?t=7731 Texture Competition 0003 - Stone/Concrete] 
[http://www.cgtextures.com/ CG Textures] 
[http://spring.clan-sy.com/phpbb/viewtopic.php?f=13&t=11009&st=0&sk=t&sd=a Skyboxes] 
[http://springrts.com/phpbb/viewtopic.php?f=13&t=30674 More skyboxes, based on NASA photography]

=Features=
[http://springrts.com/phpbb/viewtopic.php?t=4047 Compilation List of Features for Maps] 
[http://spring1944.com/s44/files/S44%20Trees.rar Trees]

=Models=
[http://planet-wars.eu/ModelBase/Units.aspx Model Base] - models/textures/scripts by the CA/zK team (?), mostly remakes of TA units

[http://springrts.com/phpbb/viewtopic.php?f=9&t=22283 KaiserJ's "Lego" pieces] - easily create units by puzzling together various "Lego pieces", comes with texture.

=Sounds=
[http://freesound.iua.upf.edu/ Freesound] free sounds and samples, distributed under the [http://creativecommons.org/licenses/sampling+/1.0/ Creative Commons License]
[http://www.pdsounds.org/ Public domain sounds] sounds and samples distributed to the public domain

=Code=
[http://springrts.com/phpbb/viewtopic.php?t=7457 GPL Code Repository] 
[http://springrts.com/phpbb/viewtopic.php?t=6569&postdays=0&postorder=asc&start=0 The Millionth Monkey Gets Its Typewriter - Movement Optimization]

=Maps=
[http://cs.selu.edu/~ssmith/spring/GPL/islands_in_war/ Islands in war]

=Games=
[http://spring.jobjol.nl/show_file.php?id=1531 THIS] 
[http://spring.jobjol.nl/show_file.php?id=1070 Fibre] 
[http://spring.jobjol.nl/show_file.php?id=1476 Micro Modules] 
[http://spring.jobjol.nl/show_file.php?id=1079 Under Pressure] 

=Lua=
[[WidgetDatabaseFAQ|Widget-DB]] - you may use this for finding code samples

=Various=
[https://springrts.com/phpbb/viewforum.php?f=67 Game Development Tutorials & Resources] - A cornucopia of valuable resources, since years developers come here for top notch content. Also perfect to get old projects going again.

[http://spring.clan-sy.com/phpbb/viewtopic.php?f=14&t=8573 Various Resources by various people]
- cegs in .tdf format, bos scripts and some 404s ;)

[[CollectionOfStuff|Unsorted list of interesting threads about Spring game development]]

{{forumlink|topic=23961|title= Dario D.'s interface pack}} - contains textures and sounds, useable to make an interface

[[Category:Game Dev]]

Sounds.lua

2015-04-13T12:22:49Z

8611: /* Example */ add PitchMod explosion examples. untested if that still works/is needed but the idea itself is good example. http://springrts.com/phpbb/viewtopic.php?t&t=28819

==Location==
<code>sounds.lua</code> is a file in the <code>Gamedata/</code> directory of a Spring Game.

==Purpose==
The file is used to define '''SoundItems'''. Beside simply "linking" to an audio file, '''SoundItems''' can use various tags to alter the playback of the file.

==Source==
The engine source code which parses the data from this file is viewable here:

* {{sourcelink|file=rts/System/Sound/SoundItem.cpp}}

==Data Types==
{{DataTypes}}

==Details==
Wherever a sound is played in Spring, be it associated with a [[Gamedev:UnitDefs|UnitDef]], [[Gamedev:WeaponDefs|WeaponDef]] or via the [[Lua_UnsyncedCtrl#Sounds|lua API]], a '''SoundItem''' is used. If you access a raw sound file, a '''SoundItem''' with the defaults is created for you.

Additionally, multiple '''SoundItems''' can use one single file with different settings, this is very efficient, as they only use 1 shared buffer.

{{new|89.0}}: All item names are treated in lowercase.

==Tips==
You can update & reload your sounddefs at runtime via Spring.LoadSoundDef("gamedata/sounds.lua").

===Reserved SoundItems===
The following '''SoundItems''' are reserved for specific engine sounds:

* <code>IncomingChat</code> - Is played when a chat message is received.
* <code>MultiSelect</code> - Is played when multiple units are selected simultaneously.
* <code>MapPoint</code> - Is played when a map point is placed by the player or an ally.
* <code>FailedCommand</code> - Is played when a unit fails to execute a command. e.g. When a unit cannot reach it's destination etc.
* <code>default</code> - Used for all sounds that aren't listed in <code>sounds.lua</code>.

===SoundItem Properties===

{{tag
|name = gain
|type = float
|default = 1.0
|description = This varies the loudness, > <code>1.0</code> is louder, < <code>1.0</code> is quieter. <code>0.0</code> is silent.}}

{{tag
|name = gainmod
|type = float
|default = 0.0
|description = If > <code>0.0</code> then this adds a random amount to {{taglink|gain}} each time the sound is played. Clamped between <code>0.0</code> and <code>1.0</code>. The result is in the range '''['''({{taglink|gain}} * (1 + {{taglink|gainMod}}))''',''' ({{taglink|gain}} * (1 - {{taglink|gainMod}}))''']'''.}}

{{tag
|name = pitch
|type = float
|default = 1.0
|description = Varies the pitch of the sound, > <code>1.0</code> is higher pitched, < <code>1.0</code> is lower.}}

{{tag
|name = pitchmod
|type = float
|default = 0.0
|description = If > <code>0.0</code> then this adds a random amount to {{taglink|pitch}} each time the sound is played. Clamped between <code>0.0</code> and <code>1.0</code>. The result is in the range '''['''({{taglink|pitch}} * (1 + {{taglink|pitchMod}}))''',''' ({{taglink|pitch}} * (1 - {{taglink|pitchMod}}))''']'''.}}

{{tag
|name = dopplerscale
|type = float
|default = 1.0
|description = How unit and camera speed affects the pitch of the sound, to exaggerate it, use values > <code>1.0</code>. Use <code>0.0</code> to completely disable the effect.}}

{{tag
|name = priority
|type = int
|default = 0
|description = When lots of sounds are played, sounds with lower {{taglink|priority}} are more likely to get cut off. A {{taglink|priority}} > <code>0</code> will never be cut of (priorities can be negative).}}

{{tag
|name = maxconcurrent
|type = int
|default = 16
|description = How many copies of this sound can be played at once?}}

{{tag
|name = maxdist
|type = float
|default = MAX_FLOAT
|description = The cut-off distance (in [[elmo]]s) at which this sound will no longer be played.}}

{{tag
|name = rolloff
|type = float
|default = 1.0
|description = How fast the sound becomes quieter with distance. <code>0.0</code> means always the same loudness regardless of distance.}}

{{tag
|name = in3d
|type = bool
|default = true
|description = Non-3d sounds always came out of the front-speakers (or the centre one). 3d sounds are, well, in 3d.}}

{{tag
|name = looptime
|type = int
|default = 0
|description = The time in milliseconds the sound should loop for.}}

==Examples==
===default sounds===
The following is the default <code>sounds.lua</code> supplied in the base content [[springcontent.sdz]] archive, with some of the comments removed (As the information is presented here).
<code><pre>
local Sounds = {
SoundItems = {
IncomingChat = {
--- always play on the front speaker(s)
file = "sounds/beep4.wav",
in3d = "false",
},
MultiSelect = {
--- always play on the front speaker(s)
file = "sounds/button9.wav",
in3d = "false",
},
MapPoint = {
--- respect where the point was set, but don't attenuate in distance
--- also, when moving the camera, don't pitch it
file = "sounds/beep6.wav",
rolloff = 0,
dopplerscale = 0,
},
ExampleSound = {
--- some things you can do with this file
--- can be either ogg or wav
file = "somedir/subdir/soundfile.ogg",
gain = 1,
pitch = 1,
dopplerscale = 1,
priority = 0,
maxconcurrent = 16,
maxdist = 20000,
rolloff = 1,
in3d = true,
looptime = 0,
},

-- new since 89.0
default = {
gainmod = 0.35,
pitchmod = 0.3,
pitch = 0.7,
in3d = true,
},
},
}

return Sounds
</pre></code>

===Using PitchMod to prevent loud explosions====
Taken from this thread by jK: {{forumlink|topic=28819|title=Use PitchMod in sounds.lua to prevent loud explosions}}

Explosions can sound louder than intended when they are started in the same simFrame and so are played in sync -> resonance. PitchMod now changes the playback time (e.g. with 0.3 the sounds should have a playback time of 100-130%) and so there isn't a resonance anymore even when the sound is started multiple times in the same simframe.

<code><pre>
local files = VFS.DirList("sounds/explosions/")
local t = Sounds.SoundItems
for i=1,#files do
local fileName = files[i]
t[fileName] = {
file = fileName;
pitchmod = 0.3;
gainmod = 0.2;
maxconcurrent = 8;
}
end
</pre></code>

===External Examples===
{{sourcelink|file=cont/base/springcontent/gamedata/sounds.lua}} - The original default <code>sounds.lua</code>

[http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/gamedata/sounds.lua ZeroK sounds.lua]

==Further Reading==
{{forumlink|topic=17647&start=25|title=Information about sounds.lua}}
{{forumlink|topic=20685|title=Information about gainMod and pitchMod}}
[[Category:gamedata]]

Lua:Callins

2015-04-13T10:24:31Z

8611: /* Drawing */ none->dt

= 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].

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
|params =
|return = none
|description = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|params =
|return = none
|description = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|params = type, id
|return = number cmdID
|description = 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 unitID or featureID respectively.
}}

{{LuaCallin
|name = CommandNotify
|params = cmdID, cmdParams, cmdOptions
|return = bool removeCmd
|description = Called when a command is issued. Returning <code>true</code> deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = WorldTooltip
|params = ttType, data1, data2, data3
|return = string newTooltip
|description = The parameters can be <code>"unit"</code>, <code>unitID</code>; <code>"feature"</code>, <code>featureID</code>; <code>"ground"</code>, <code>posX</code>, <code>posY</code>, <code>posZ</code> or <code>"selection"</code>.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|params = ???
|return = none
|description = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|params = serverFrameNum
|return = none
|description = 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
|params = state, ready, playerStates
|return = bool success, bool newReady
|description = ???
}}

{{LuaCallin
|name = SunChanged
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = AddConsoleLine
|params = msg, priority
|return = none
|description = Called when text is entered into the console (e.g. Spring.Echo).
}}

{{LuaCallin
|name = RecvSkirmishAIMessage
|params = aiTeam, dataStr
|return = ???
|description = ???
}}

{{LuaCallin
|name = RecvFromSynced
|params = ...
|return = none
|description = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|params = zip
|return = none
|description = 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
|params = message, replaceLastLine
|return = none
|description = Only available to LuaIntro.
}}

{{LuaCallin
|name = GroupChanged
|params = groupID
|return = none
|description = Called when a unit is added to or removed from a control group. Currently implemented for widgets only.
}}

{{LuaCallin
|name = ConfigureLayout
|params = ???
|return = ???
|description = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|params = x, y
|return = bool isAbove
|description = Called every Update. Must return <code>true</code> for <code>Mouse*</code> events and <code>GetToolTip</code> to be called.
}}

{{LuaCallin
|name = GetTooltip
|params = x, y
|return = string tooltip
|description = Called when <code>IsAbove</code> returns true.
}}

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = none
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value.
}}

{{LuaCallin
|name = KeyRelease
|params = key
|return = none
|description = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|params = utf8char
|return = none
|description = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = MousePress
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is pressed. The <code>button</code> parameter supports up to 7 buttons. Must return <code>true</code> for <code>MouseRelease</code> and other functions to be called.
}}

{{LuaCallin
|name = MouseRelease
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is released. Please note that in order to have Spring call <code>MouseRelease</code>, you need to have a <code>MousePress</code> call-in in the same addon that returns <code>true</code>.
}}

{{LuaCallin
|name = MouseWheel
|params = up, value
|return = none
|description = Called when the mouse wheel is moved. The parameters indicate the direction and amount of travel.
}}

{{LuaCallin
|name = MouseMove
|params = x, y, dx, dy, button
|return = none
|description = Called when the mouse is moved. The <code>dx</code> and <code>dy</code> parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|params = playerID
|return = none
|description = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|params = playerID
|return = none
|description = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|params = playerID, reason
|return = none
|description = Called whenever a player is removed from the game.
}}

=== Drawing ===

{{LuaCallin
|name = ViewResize
|params = viewSizeX, viewSizeY
|return = none
|description = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|params = dt
|return = none
|description = 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
|params =
|return = none
|description = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

{{LuaCallin
|name = DrawWorldPreUnit
|params =
|return = none
|description = Spring draws units, features, some water types, cloaked units, and the sun.
}}

{{LuaCallin
|name = DrawWorld
|params =
|return = none
|description = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreen
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|params = vsx, vsy
|return = none
|description = Where <code>vsx</code>, <code>vsy</code> are screen coordinates.
}}

{{LuaCallin
|name = DrawLoadScreen
|params =
|return = none
|description = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls <code>drawMode</code> can be one of the following, <code>notDrawing = 0</code>, <code>normalDraw = 1</code>, <code>shadowDraw = 2</code>, <code>reflectionDraw = 3</code>, <code>refractionDraw = 4</code>.

{{LuaCallin
|name = DrawUnit
|params = unitID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of units, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawFeature
|params = unitID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of features, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

{{LuaCallin
|name = DrawShield
|params = unitID, weaponID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of [[Gamedev:WeaponDefs#Shield_(WeaponType)|shields]].
}}

{{LuaCallin
|name = DrawProjectile
|params = projectileID, drawMode
|return = bool suppressEngineDraw
|description = For custom rendering of weapon (& other) projectiles.
}}

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|params = msg, player
|return = none
|description = Called when a player issues a UI command e.g. types <code>/foo</code> or <code>/luarules foo</code>.
}}

=== Game ===

{{LuaCallin
|name = GameID
|params = gameID
|return = none
|description = Called once to deliver the gameID.
}}

{{LuaCallin
|name = GamePaused
|params =
|return = none
|description = Called when the game is paused.
}}

{{LuaCallin
|name = GameOver
|params = winningAllyTeams
|return = none
|description = The parameter is a list of winning allyTeams, if empty the game result was undecided (like when dropping from an host).
}}

{{LuaCallin
|name = GameFrame
|params = frame
|return = none
|description = Called for every game simulation frame (30 per second).
}}

{{LuaCallin
|name = GamePreload
|params =
|return = none
|description = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|params =
|return = none
|description = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|params = teamID
|return = none
|description = ???
}}

{{LuaCallin
|name = TeamDied
|params = teamID
|return = none
|description = Called when a team dies (see [[Lua_SyncedCtrl#Game_End|Spring.KillTeam]]).
}}

=== Units ===
{{LuaCallin
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|return = none
|description = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|return = none
|description = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is damaged (after <code>UnitPreDamaged</code>).
}}

{{LuaCallin
|name = UnitDestroyed
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is destroyed.
}}

{{LuaCallin
|name = UnitUnitCollision
|params = colliderID, collideeID
|return = none
|description = Called when two units collide. Both units must be registered with [[Lua_System#Synced|Script.SetWatchUnit]].
}}

{{LuaCallin
|name = UnitFeatureCollision
|params = colliderID, collideeID
|return = none
|description = 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
|params = unitID, unitDefID, teamID, cmdID, cmdParams, cmdOptions
|return = none
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}

{{LuaCallin
|name = UnitCmdDone
|params = unitID, unitDefID, unitTeam, cmdID, cmdTag, cmdParams, cmdOpts
|return = none
|description = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|return = none
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = StockpileChanged
|params = unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount
|return = none
|description = Called when a units stockpile of weapons increases or decreases. See {{xtaglink|Gamedev:WeaponDefs|stockpile}}.
}}

{{LuaCallin
|name = UnitEnteredLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitSeismicPing
|params = x, y, z, strength, allyTeam, unitID, unitDefID
|return = none
|description = Called when a unit emits a seismic ping. See {{xtaglink|Gamedev:UnitDefs|seismicSignature}}.
}}

=== Features ===
{{LuaCallin
|name = FeatureCreated
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is created.
}}

{{LuaCallin
|name = FeatureDamaged
|params = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a feature is damaged.
}}

{{LuaCallin
|name = FeatureDestroyed
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|params = ???
|return = none
|description = ???
}}

=== Projectiles ===
The following Callins are only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].

{{LuaCallin
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|return = none
|description = Called when the projectile is created.
}}

{{LuaCallin
|name = ProjectileDestroyed
|params = proID
|return = none
|description = Called when the projectile is destroyed.
}}

== Synced Only ==
{{LuaCallin
|name = CommandFallback
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag
|return = bool used, bool finished
|description = Called when the unit reaches an unknown command in its queue (i.e. one not handled by the engine). If no addon returns <code>used</code> as <code>true</code> the command is dropped, if an addon returns <code>true, true</code> the command is removed because it's done, with <code>true, false</code> it's kept in the queue and <code>CommandFallback</code> gets called again on the next slowupdate.
}}

{{LuaCallin
|name = AllowCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = bool allow
|description = 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
|params = unitDefID, builderID, builderTeam, x, y, z, facing
|return = bool allow
|description = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|params = unitID, unitDefID, oldTeam, newTeam, capture
|return = bool allow
|description = 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
|params = builderID, builderTeam, unitID, unitDefID, part
|return = bool allow
|description = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

{{LuaCallin
|name = AllowFeatureCreation
|params = featureDefID, teamID, x, y, z
|return = bool allow
|description = Called just before feature is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowFeatureBuildStep
|params = builderID, builderTeam, featureID, featureDefID, part
|return = bool allow
|description = 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
|params = teamID, res, level
|return = bool allow
|description = 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
|params = oldTeamID, newTeamID, res, amount
|return = bool allow
|description = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|params = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = bool allow
|description = <code>clamped</code> are the coordinates clamped into start-boxes, <code>raw</code> is where player tried to place their marker. The <code>readyState</code> can be any one of
* <code>0</code> - player picked a position,
* <code>1</code> - player clicked ready,
* <code>2</code> - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* <code>3</code> - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or <code>(0,0,0)</code> if they do not have a startbox.
}}

{{LuaCallin
|name = AllowDirectUnitControl
|params = unitID, unitDefID, unitTeam, playerID
|return = bool allow
|description = Determines if this unit can be controlled directly in FPS view.
}}

{{LuaCallin
|name = AllowWeaponTargetCheck
|params = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = bool allow
|description = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag.
}}

{{LuaCallin
|name = AllowWeaponTarget
|params = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = bool allowed, number newPriority
|description = 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 defPriority). Lower priority targets are targeted first.
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|params = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = bool allowed
|description = 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 weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

{{LuaCallin
|name = AllowBuilderHoldFire
|params = unitID, unitDefID, action
|return = bool actionAllowed
|description = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}} Called when a construction unit wants to "use his nano beams". <code>action</code> is one of following:
* <code>-1</code> Build
* <code>CMD.REPAIR</code> Repair
* <code>CMD.RECLAIM</code> Reclaim
* <code>CMD.RESTORE</code> Restore
* <code>CMD.RESURRECT</code> Resurrect
* <code>CMD.CAPTURE</code> Capture
}}

{{LuaCallin
|name = Explosion
|params = weaponDefID, px, py, pz, AttackerID
|return = bool noGfx
|description = Called when an explosion occurs. If it returns <code>true</code> then no graphical effects are drawn by the engine for this explosion.
}}

{{LuaCallin
|name = TerraformComplete
|params = unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam
|return = bool stop
|description = Called when pre-building terrain levelling terraforms are completed (c.f. {{xtaglink|Gamedev:UnitDefs|levelGround}}). If the return value is <code>true</code> the current build order is terminated.
}}

{{LuaCallin
|name = MoveCtrlNotify
|params = unitID, unitDefID, unitTeam, data
|return = bool moveCtrlComplete
|description = 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 <code>1</code> ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled (<code>false</code>) or return to engine controlled movement (<code>true</code>).
}}

{{LuaCallin
|name = RecvLuaMsg
|params = msg, playerID
|return = none
|description = Receives messages from unsynced sent via [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaRulesMsg]].
}}

{{LuaCallin
|name = Load
|params = zip
|return = none
|description = Called after <code>GamePreload</code> and before <code>GameStart</code>. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

=== Damage Controllers ===
For the following callins, in addition to being a regular weapon, <code>weaponDefID</code> may be one of the following:
* <code>-1</code> - debris collision, also default of [[Lua_SyncedCtrl#Unit_Control|Spring.AddUnitDamage]]
* <code>-2</code> - ground collision
* <code>-3</code> - object collision
* <code>-4</code> - fire damage
* <code>-5</code> - water damage
* <code>-6</code> - kill damage
* <code>-7</code> - crush damage

{{LuaCallin
|name = UnitPreDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = number newDamage, number impulseMult
|description = 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
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = bool handleCollision
|description = Called before any engine shield-vs-projectile logic executes. If the return value is <code>true</code> the gadget handles the collision event and the engine does not remove the projectile.
}}

{{LuaCallin
|name = FeaturePreDamaged
|params = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = number newDamage, number impulseMult
|description = 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]]

XTA

2015-03-10T17:31:42Z

8611: /* Download */ nobody was updating the links..think auto-dl is okay

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost
[loganberry]Autohost
[durian]Autohost
[elderberry]Autohost
</pre>

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
pick a random "good" map: <code>!map</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-03-10T17:19:59Z

8611: /* Important Autohost Commands */ commented out helium (its gone), updated a bit

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==

The latest XTA can be found from http://packages.springrts.com/builds or from springfiles: search for XTA (at the time of writing this page, the current version is http://springfiles.com/spring/games/xta-35).

The XTA section on the official forum usually also contains the latest release: http://springrts.com/phpbb/viewforum.php?f=48

You can also download it by using [http://springrts.com/wiki/Download_Systems rapid system].
----

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost
[loganberry]Autohost
[durian]Autohost
[elderberry]Autohost
</pre>

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
pick a random "good" map: <code>!map</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

CEG:Defs

2015-03-09T23:16:42Z

8611: add:CSmokeProjectile & CSmokeProjectile2. someone check or something

= CEG Definitions =

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

* {{sourcelink|file=rts/Sim/Projectiles/}}
* {{sourcelink|file=rts/Sim/Projectiles/Unsynced/}}
* {{sourcelink|file=rts/Rendering/GroundFlash.cpp}}

== Data Types ==
CEGs use the following data types:
{{DataTypes}}

You can use [[CEG:Operators]] to define floats that are not fixed.

== CEG Textures ==

* Textures on CEG definitions are referenced by name.
* The list of available textures and their names should be in [[resources.lua]]
* Texture definitions to be used in projectile classes should be placed within the <code>projectiletextures</code> category and textures to be used with [[#CSimpleGroundFlash]] class should be placed within the <code>groundfx</code> category.
* Texture images are usually placed in the "bitmaps" subfolder.

== Overall Format ==

A CEG file contains one or more CEGs. Each CEG follows this format:

<code><pre>
return {
["ceg_name"] = {
-- EXPLOSION LEVEL
useDefaultExplosions = false,

spawner1_name = {
-- SPAWNER LEVEL
class = "CClassName",
count = 1,
air = true,
ground = true,
water = true,
properties = {
-- CLASS LEVEL
},
},
},
spawner2_name = {
-- SPAWNER LEVEL
-- each spawner follows the above format
},
groundflash = {
-- groundflash is a special spawner name; it always generates a CStandardGroundFlash
-- CStandardGroundFlash properties
},
},
}
</pre></code>

== Explosion Level Tags ==
{{tag
|name = useDefaultExplosions
|type = bool
|default = false
|description = If this is set, the CEG will use the default explosion (based on damage and area of effect) in addition to any spawners you define. The default explosions are sometimes very performance heavy, especially for large damage values (leading to higher particle counts).
}}

== Spawner Level Tags ==
A CEG can contain any number of spawners. The name of the spawners don't really matter, as long as it's not <code>groundflash</code>, which has a special meaning. You can think of each spawner as being one component of the overall explosion.

{{tag
|name = class
|type = string
|default = spawner_name
|description = Each spawner has a class that determines what kind of graphical effect it creates. Spring has a number of standard classes that you can choose from. Currently available classes are:
* [[#CExpGenSpawner|CExpGenSpawner]]
* [[#CBitmapMuzzleFlame|CBitmapMuzzleFlame]]
* [[#CExploSpikeProjectile|CExploSpikeProjectile]]
* [[#CHeatCloudProjectile|CHeatCloudProjectile]]
* [[#CSimpleParticleSystem|CSimpleParticleSystem]]
* [[#CSpherePartSpawner|CSpherePartSpawner]]
* [[#CSimpleGroundFlash|CSimpleGroundFlash]]
* [[#CStandardGroundFlash|CStandardGroundFlash]]
}}

{{tag
|name = count
|type = int
|default = 1
|description = The count determines the number of times the spawner will run.
}}

=== Visibility Conditions ===
These determine under what conditions the spawner will run. If you set the condition to true, the spawner will run if the explosion takes place under that condition. If you set more than one condition, the spawner will run if ''any'' of them are true. If you want a spawner to run only if two or more conditions are ''all'' true, you have to do a little trick with the [[#CExpGenSpawner]] class as explained in "suggested use".

{{tag
|name = air
|type = bool
|default = false
|description = The CEG will run if at least 20 [[elmo]]s above ground/sea level.
}}

{{tag
|name = water
|type = bool
|default = false
|description = The CEG will run if in water to a depth of -5 [[elmo]]s.
}}

{{tag
|name = underwater
|type = bool
|default = false
|description = The CEG will run if under water deeper than 5 [[elmo]]s.
}}

{{tag
|name = ground
|type = bool
|default = false
|description = The CEG will run if less than 20 [[elmo]]s above ground.
}}

{{tag
|name = unit
|type = bool
|default = false
|description = The CEG will run if the weapon hits a unit.
}}

{{tag
|name = nounit
|type = bool
|default = false
|description = The CEG will run if the weapon does not hit a unit.
}}

== Class Level Tags ==
=== Common Properties ===
All classes have the following properties, although not all of them use them:

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If true, the spawner is always visible, ignoring LoS. Note that prior to 98.0 this did not work correctly.
}}

{{tag
|name = useAirLos
|type = bool
|default = false
|description = Whether the spawner uses air LoS to determine if it is visible. This may allow the spawner to be seen from a further distance than normal.
}}

{{tag
|name = pos
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial position vector of the spawner.
}}

{{tag
|name = speed
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial speed vector of the spawner.
}}

{{tag
|name = dir
|type = float[3]
|description = The initial direction vector of the spawner.
}}

=== CExpGenSpawner ===
This is the closest thing CEG has to a function call. Instead of creating a graphical effect on its own, it creates another CEG.

==== Suggested Use ====
* If you use a spawner a lot of times, you may want to make it a separate CEG to avoid having to copy-paste many times.
* This is the only way to truly delay a graphical effect.
* The spawned CEG still checks conditions, so if you want to, say, spawn an effect only if it is in water ''and'' doesn't hit a unit, you can give the CExpGenSpawner <code>nounit = 1;</code> and the spawned <code>CEG water = 1;</code>.
* This allows you to give a set of spawners the same (and possibly random) direction.
* You can animate an explosion flip-book style using delays and several bitmaps.

==== Properties ====

{{tag
|name = delay
|type = int
|default = 1
|description = How long to wait (in frames?) before spawning the CEG.
}}

{{tag
|name = damage
|type = float
|default = 0.0
|description = The CEG will be called with this damage. The CEG doesn't actually deal any damage, but you can use this as a parameter and read it using the [[CEG:Operators#Damage_.28.27d.27.29|'d' operator]].
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of the CEG you want to spawn.
}}

=== CBitmapMuzzleFlame ===
This creates three rectangular textures at right angles to each other. The {{taglink|frontTexture}} has {{taglink|dir}} as its normal.

==== Suggested Use ====
*Muzzle flames, obviously.
*You can use an upward-pointing CBitmapMuzzleFlame as a simple splash of water or dirt.
*Railgun trails.
*This is the only class that both obeys perspective and allows for a custom texture.

==== Properties ====

{{tag
|name = sideTexture
|type = string
|default = ""
|description = Texture as viewed from the side.
}}

{{tag
|name = frontTexture
|type = string
|default = ""
|description = Texture as viewed from the front.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = The initial width of the muzzle flame.
}}

{{tag
|name = length
|type = float
|default = 0.0
|description = The initial length of the muzzle flame.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = By the end of its life, the muzzle flame grows to <code>1 + sizeGrowth</code> times its initial {{taglink|size}} and {{taglink|length}}. The flame grows quickly at first and more slowly toward the end.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = How long the muzzle flame lasts.
}}

{{tag
|name = frontOffset
|type = float
|default = 0.0
|description = Where the frontTexture is along the length of the muzzle flame. <code>0</code> means it is in the back, <code>1</code> is in the front.
}}

=== CExploSpikeProjectile ===

This creates a glowy spike. Note that the spike is two sided, i.e., symmetric about the position of the spawner.

==== Suggested Use ====
* Anything glowy.
* For large, slow missiles, you can try using this as an extended engine flame. Set the width to something fairly large.
* Long and thin spikes will look spiky; meanwhile, shorter and wider spikes look more blobby.
* The colors of spikes add together, so if you have several spikes and all three color channels are non-zero, it will be white in the center.
* The length growth of the spike depends on the norm of the dir vector. The spike does not grow in width.

==== Properties ====
{{tag
|name = length
|type = float
|default = 0.0
|description = The initial length of (half) of the spike (multiplied by {{taglink|dir}}).
}}

{{tag
|name = lengthGrowth
|type = float
|default = dir.Length() * (0.5 + RandFloat() * 0.4)
|description = How much the length increases by per update.
}}

{{tag
|name = width
|type = float
|default = 0.0
|description = Half the initial width of of the spike. This is an absolute value.
}}

{{tag
|name = alpha
|type = float
|default = 0.0
|description = The starting alpha of the spike.
}}

{{tag
|name = alphaDecay
|type = float
|default = 0.0
|description = How quickly the alpha of the spike decreases.
}}

{{tag
|name = color
|type = rgb
|default = {1.0, 0.8, 0.5}
|description = The color of the spike.
}}

=== CHeatCloudProjectile ===

Creates an expanding sprite. Simple but effective.

==== Suggested Use ====
* As the main background to an explosion.

==== Properties ====
{{tag
|name = heat
|type = float
|default = 0.0
|description = Used in alpha calculations. See {{taglink|heatFalloff}}.
}}

{{tag
|name = maxheat
|type = float
|default = 0.0
|description = Used in alpha calculations. See {{taglink|heatFalloff}}.
}}

{{tag
|name = heatFalloff
|type = float
|default = 0.0
|description = This is really confusing way of representing alpha and alphaDecay. Basically <code>alpha = </code>{{taglink|heat}}<code>/</code>{{taglink|maxheat}}, and <code>alphaDecay = </code>{{taglink|heatFalloff}}<code>/</code>{{taglink|maxHeat}}.
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = The initial radius of the heatcloud.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = The heatcloud grows by this amount every frame.
}}

{{tag
|name = sizeMod
|type = float
|default = 0.0
|description = The size of the heatcloud is multiplied by <code>1 - sizeMod</code>.
}}

{{tag
|name = sizeModMod
|type = float
|default = 0.0
|description = Each frame, {{taglink|sizeMod}} is multiplied by {{taglink|sizeModMod}}.
}}

{{tag
|name = texture
|type = string
|default = "heatcloud" as referenced in [[resources.lua]]
|description = The texture used for the heatcloud.
}}

=== CSimpleParticleSystem ===

Creates a sprite that can undergo complex motion. Probably the most versatile class.

==== Suggested Use ====
* Anything moving that is not doing so at constant velocity.
* If you want something that expands (or shrinks) to some size then stops, set {{taglink|sizeMod}} to something less than <code>1</code>, and {{taglink|sizeGrowth}} to something positive. The particle will grow to a size equal to <code>sizeGrowth / (1 - sizeMod)</code> and stop. The smaller {{taglink|sizeMod}} is, the faster it will reach this size.

==== Properties ====
===== Initial Velocity Properties =====
{{tag
|name = emitVector
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial direction vector in which the particle is emitted. When spawning CEGs via EmitSfx you can make the particles go into the direction of the emiting piece with {{taglink|emitvector|dir}}. This is useful for e.g. fire coming out of a gun barrel.
}}

{{tag
|name = emitRot
|type = float
|default = 0.0
|description = At what angle to emit the particle relative to {{taglink|emitVector}}. <code>0</code> means that the particle will be emitted in {{taglink|emitVector}}'s direction; <code>180</code> will emit the particle in the opposite direction. <code>90</code> will emit the particle in a random direction perpendicular to {{taglink|emitVector}}, which is good for creating rings.
}}

{{tag
|name = emitRotSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|emitRotSpread}} is added to the {{taglink|emitRot}}.
}}

{{tag
|name = emitMul
|type = float[3]
|default = {1.0, 1.0, 1.0}
|description = Scales the initial particle velocity; for this property, +y is considered to be in the direction of {{taglink|emitVector}}. Good if you want to create an egg-shaped explosion.
}}

{{tag
|name = particleSpeed
|type = float
|default = 0.0
|description = The particle's initial speed.
}}

{{tag
|name = particleSpeedSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleSpeedSpread}} is added to the {{taglink|particleSpeed}}.
}}

===== Movement Properties =====

{{tag
|name = gravity
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = This will be added to the particle's velocity every frame.
}}

{{tag
|name = airdrag
|type = float
|default = 0.0
|description = The particle's velocity is multiplied by this every frame.
}}

===== Size Properties =====

{{tag
|name = particleSize
|type = float
|default = 0.0
|description = The initial size of the particle.
}}

{{tag
|name = particleSizeSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleSizeSpread}} is added to the {{taglink|particleSize}}.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = How much the particle grows each frame.
}}

{{tag
|name = sizeMod
|type = float
|default = 0.0
|description = The size of the particle is multiplied by this each frame.
}}

===== Visual Properties =====

{{tag
|name = directional
|type = bool
|default = false
|description = If true, the particle will point in the direction it is moving.
}}

{{tag
|name = texture
|type = string
|default = ""
|description = The texture to use for the particle.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

===== Life Properties =====

{{tag
|name = numParticles
|type = int
|default = 0
|description = How many particles to create. This is not the same as <code>count</code>; if you spawn multiple particles using <code>count</code>, any [[CEG:Operators]] will be re-evaluated for each particle, whereas if you use {{taglink|numParticles}} they will not be. However, the spread properties are evaluated separately for each particle regardless of which one you use.
}}

{{tag
|name = particleLife
|type = float
|default = 0.0
|description = How long each particle lasts.
}}

{{tag
|name = particleLifeSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleLifeSpread}} is added to the {{taglink|particleLife}}.
}}

=== CSpherePartSpawner ===

Draws an expanding sphere.

==== Suggested Use ====
*Looks like a shockwave.

==== Properties ====

{{tag
|name = alpha
|type = float
|default = 0.0
|description = The alpha of the sphere.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = Time to live, in frames(?).
}}

{{tag
|name = expansionSpeed
|type = float
|default = 0.0
|description = How quickly the sphere expands.
}}

{{tag
|name = color
|type = rgb
|default = {0.0, 0.0, 0.0}
|description = The color of the sphere.
}}

=== CSimpleGroundFlash ===

Draws an expanding ground texture.

==== Suggested Use ====
* A short groundflash (~8 frames) is good for any explosion that gives off light. You can also use a longer groundflash to suggest the ground is glowing from heat.

==== Properties ====

{{tag
|name = size
|type = float
|default = 0.0
|description = The radius of the particle.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = How much the particle grows each frame.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = Time to live, in frames(?).
}}

{{tag
|name = texture
|type = string
|default = ""
|description = The texture to use for the particle.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

=== CStandardGroundFlash ===
If you name a spawner "groundflash," it will always generate a standard groundflash.

==== Suggested Use ====
A short groundflash (~8 frames) is good for any explosion that gives off light. You can also use a longer groundflash to suggest the ground is glowing from heat.

==== Properties ====

{{tag
|name = flashSize
|type = float
|default = 0.0
|description = The radius of the groundflash.
}}

{{tag
|name = flashAlpha
|type = float
|range = [0, 1]
|default = 0.0
|description = How transparent the groundflash is. Generally the higher the brighter.
}}

{{tag
|name = circleGrowth
|type = float
|default = 0.0
|description = A groundflash can have an additional circle that expands outwards. This controls how fast the circle grows.
}}

{{tag
|name = circleAlpha
|type = float
|range = [0, 1]
|default = 0.0
|description = How transparent the circle is.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = How long the groundflash lasts.
}}

{{tag
|name = color
|type = rgb
|default = {1.0, 1.0, 0.8}
|description = The color of the groundflash.
}}

=== CSmokeProjectile2 ===
( {{FIXME}} newly added to wiki. someone cross-check then remove this note )

Particles that begin with a hard-coded yellow-red colorfade and then fade to monochrom. (shades of grey)

Movement is influenced by the random wind.
Finer details of visual and position update are best explained by looking at the formulas in <code>CSmokeProjectile2::Update() & CSmokeProjectile2::Draw()</code>

==== Suggested Use ====
Smoke. Smokestacks, rocket exhaust, burning wreckage,...

For a nicer stream of smoke spawn it frequently over multiple frames, otherwise it looks rather bland.

==== Properties ====
{{tag
|name = color
|type = float
|default = 0.5
|description = How dark the final monochrom color of a particle is. 0 is black.
(Use >1 for slightly bugged funnies, like slightly non-monochrome colors or interessting black/white changes.)
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = Size of a particle.
}}

{{tag
|name = ageSpeed
|type = float
|default = 0.5
|description = How fast the particle ages. Every frame: <code>age += ageSpeed</code> The particle is deleted at <code>if (age > 1)</code>
}}

{{tag
|name = glowFalloff
|type = float
|default = 0.0
|description = How fast the particle fades to monochrom.
}}

{{tag
|name = wantedPos
|type = float3
|default = "0,0,0"
|description = In which direction the smoke tends to drift. Less effective in y-coordinate and influenced by random wind.
}}

{{tag
|name = speed
|type = float3
|default = "0,0,0"
|description = <code>wantedPos += speed;</code> How fast and in which vector the particles move.
}}

{{tag
|name = texture
|type = hardcoded
|default = randomly chosen.
|description = Particles randomly pick one of the smoke textures (bitmaps\smoke) and remain with it until death.
}}

=== CSmokeProjectile ===
Monochrome particles that fade out.
A more "primitive" version of CSmokeProjectile2.
No hardcoded red-yellow start but it misses wantedPos to tweak the look a bit more detailed.

==== Suggested Use ====
Smoke.
For a nicer stream of smoke spawn it frequently over multiple frames, otherwise it looks rather bland.

==== Properties ====
{{tag
|name = color
|type = float
|default = 0.5
|description = Brightness of the particle. 0 is black.
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = Size of a particle
}}

{{tag
|name = ageSpeed
|type = float
|default = 0.5
|description = How fast the particle ages. Every frame: <code>age += ageSpeed</code> The particle is deleted at <code>if (age > 1)</code>
}}

{{tag
|name = speed
|type = float3
|default = "0,0,0"
|description = <code>pos += speed;</code> How fast and in which vector the particles move.
}}

{{tag
|name = texture
|type = hardcoded
|default = randomly chosen.
|description = Particles randomly pick one of the smoke textures (bitmaps\smoke) and remain with it until death.
}}

==Examples==


[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/gamedata/explosions 'Balanced Annihilation' CEGs] (TDF format)

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Fgamedata%2Fexplosions 'Conflict Terra' CEGs]

[https://github.com/EvolutionRTS/Evolution-RTS/tree/master/Gamedata/explosions 'Evolution RTS' CEGs]

[https://github.com/imperialwinter/swiw.sdd/tree/master/gamedata/explosions 'Imperial Winter' CEGs] (TDF format)

[http://code.google.com/p/journeywar/source/browse/#svn%2Ftrunk%2Fgamedata%2Fexplosions 'Journeywar' CEGs]

[http://sourceforge.net/p/mwspring/code/HEAD/tree/effects/ 'MechCommander: Legacy' CEGs] (TDF format)

[https://github.com/spring1944/spring1944/tree/master/effects 'Spring: 1944' CEGs] (TDF format)

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FGamedata%2Fexplosions 'Spring Tutorial Game' CEGs]

[http://code.google.com/p/xta-springrts/source/browse/#svn%2Ftrunk%2Fgamedata%2Fexplosions 'XTA' CEGs] (TDF format)

[https://github.com/ZeroK-RTS/Zero-K/tree/master/effects 'ZeroK' CEGs]

[[Category:CEG]]

CEG:Defs

2015-02-27T02:41:04Z

8611: /* Visibility Conditions */ the 'trick' imo refers to using diff. conditions in CExpGenSpawner & spawned CEG

= CEG Definitions =

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

* {{sourcelink|file=rts/Sim/Projectiles/}}
* {{sourcelink|file=rts/Sim/Projectiles/Unsynced/}}
* {{sourcelink|file=rts/Rendering/GroundFlash.cpp}}

== Data Types ==
CEGs use the following data types:
{{DataTypes}}

You can use [[CEG:Operators]] to define floats that are not fixed.

== CEG Textures ==

* Textures on CEG definitions are referenced by name.
* The list of available textures and their names should be in [[resources.lua]]
* Texture definitions to be used in projectile classes should be placed within the <code>projectiletextures</code> category and textures to be used with [[#CSimpleGroundFlash]] class should be placed within the <code>groundfx</code> category.
* Texture images are usually placed in the "bitmaps" subfolder.

== Overall Format ==

A CEG file contains one or more CEGs. Each CEG follows this format:

<code><pre>
return {
["ceg_name"] = {
-- EXPLOSION LEVEL
useDefaultExplosions = false,

spawner1_name = {
-- SPAWNER LEVEL
class = "CClassName",
count = 1,
air = true,
ground = true,
water = true,
properties = {
-- CLASS LEVEL
},
},
},
spawner2_name = {
-- SPAWNER LEVEL
-- each spawner follows the above format
},
groundflash = {
-- groundflash is a special spawner name; it always generates a CStandardGroundFlash
-- CStandardGroundFlash properties
},
},
}
</pre></code>

== Explosion Level Tags ==
{{tag
|name = useDefaultExplosions
|type = bool
|default = false
|description = If this is set, the CEG will use the default explosion (based on damage and area of effect) in addition to any spawners you define. The default explosions are sometimes very performance heavy, especially for large damage values (leading to higher particle counts).
}}

== Spawner Level Tags ==
A CEG can contain any number of spawners. The name of the spawners don't really matter, as long as it's not <code>groundflash</code>, which has a special meaning. You can think of each spawner as being one component of the overall explosion.

{{tag
|name = class
|type = string
|default = spawner_name
|description = Each spawner has a class that determines what kind of graphical effect it creates. Spring has a number of standard classes that you can choose from. Currently available classes are:
* [[#CExpGenSpawner|CExpGenSpawner]]
* [[#CBitmapMuzzleFlame|CBitmapMuzzleFlame]]
* [[#CExploSpikeProjectile|CExploSpikeProjectile]]
* [[#CHeatCloudProjectile|CHeatCloudProjectile]]
* [[#CSimpleParticleSystem|CSimpleParticleSystem]]
* [[#CSpherePartSpawner|CSpherePartSpawner]]
* [[#CSimpleGroundFlash|CSimpleGroundFlash]]
* [[#CStandardGroundFlash|CStandardGroundFlash]]
}}

{{tag
|name = count
|type = int
|default = 1
|description = The count determines the number of times the spawner will run.
}}

=== Visibility Conditions ===
These determine under what conditions the spawner will run. If you set the condition to true, the spawner will run if the explosion takes place under that condition. If you set more than one condition, the spawner will run if ''any'' of them are true. If you want a spawner to run only if two or more conditions are ''all'' true, you have to do a little trick with the [[#CExpGenSpawner]] class as explained in "suggested use".

{{tag
|name = air
|type = bool
|default = false
|description = The CEG will run if at least 20 [[elmo]]s above ground/sea level.
}}

{{tag
|name = water
|type = bool
|default = false
|description = The CEG will run if in water to a depth of -5 [[elmo]]s.
}}

{{tag
|name = underwater
|type = bool
|default = false
|description = The CEG will run if under water deeper than 5 [[elmo]]s.
}}

{{tag
|name = ground
|type = bool
|default = false
|description = The CEG will run if less than 20 [[elmo]]s above ground.
}}

{{tag
|name = unit
|type = bool
|default = false
|description = The CEG will run if the weapon hits a unit.
}}

{{tag
|name = nounit
|type = bool
|default = false
|description = The CEG will run if the weapon does not hit a unit.
}}

== Class Level Tags ==
=== Common Properties ===
All classes have the following properties, although not all of them use them:

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If true, the spawner is always visible, ignoring LoS. Note that prior to 98.0 this did not work correctly.
}}

{{tag
|name = useAirLos
|type = bool
|default = false
|description = Whether the spawner uses air LoS to determine if it is visible. This may allow the spawner to be seen from a further distance than normal.
}}

{{tag
|name = pos
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial position vector of the spawner.
}}

{{tag
|name = speed
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial speed vector of the spawner.
}}

{{tag
|name = dir
|type = float[3]
|description = The initial direction vector of the spawner.
}}

=== CExpGenSpawner ===
This is the closest thing CEG has to a function call. Instead of creating a graphical effect on its own, it creates another CEG.

==== Suggested Use ====
* If you use a spawner a lot of times, you may want to make it a separate CEG to avoid having to copy-paste many times.
* This is the only way to truly delay a graphical effect.
* The spawned CEG still checks conditions, so if you want to, say, spawn an effect only if it is in water ''and'' doesn't hit a unit, you can give the CExpGenSpawner <code>nounit = 1;</code> and the spawned <code>CEG water = 1;</code>.
* This allows you to give a set of spawners the same (and possibly random) direction.
* You can animate an explosion flip-book style using delays and several bitmaps.

==== Properties ====

{{tag
|name = delay
|type = int
|default = 1
|description = How long to wait (in frames?) before spawning the CEG.
}}

{{tag
|name = damage
|type = float
|default = 0.0
|description = The CEG will be called with this damage. The CEG doesn't actually deal any damage, but you can use this as a parameter and read it using the [[CEG:Operators#Damage_.28.27d.27.29|'d' operator]].
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of the CEG you want to spawn.
}}

=== CBitmapMuzzleFlame ===
This creates three rectangular textures at right angles to each other. The {{taglink|frontTexture}} has {{taglink|dir}} as its normal.

==== Suggested Use ====
*Muzzle flames, obviously.
*You can use an upward-pointing CBitmapMuzzleFlame as a simple splash of water or dirt.
*Railgun trails.
*This is the only class that both obeys perspective and allows for a custom texture.

==== Properties ====

{{tag
|name = sideTexture
|type = string
|default = ""
|description = Texture as viewed from the side.
}}

{{tag
|name = frontTexture
|type = string
|default = ""
|description = Texture as viewed from the front.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = The initial width of the muzzle flame.
}}

{{tag
|name = length
|type = float
|default = 0.0
|description = The initial length of the muzzle flame.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = By the end of its life, the muzzle flame grows to <code>1 + sizeGrowth</code> times its initial {{taglink|size}} and {{taglink|length}}. The flame grows quickly at first and more slowly toward the end.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = How long the muzzle flame lasts.
}}

{{tag
|name = frontOffset
|type = float
|default = 0.0
|description = Where the frontTexture is along the length of the muzzle flame. <code>0</code> means it is in the back, <code>1</code> is in the front.
}}

=== CExploSpikeProjectile ===

This creates a glowy spike. Note that the spike is two sided, i.e., symmetric about the position of the spawner.

==== Suggested Use ====
* Anything glowy.
* For large, slow missiles, you can try using this as an extended engine flame. Set the width to something fairly large.
* Long and thin spikes will look spiky; meanwhile, shorter and wider spikes look more blobby.
* The colors of spikes add together, so if you have several spikes and all three color channels are non-zero, it will be white in the center.
* The length growth of the spike depends on the norm of the dir vector. The spike does not grow in width.

==== Properties ====
{{tag
|name = length
|type = float
|default = 0.0
|description = The initial length of (half) of the spike (multiplied by {{taglink|dir}}).
}}

{{tag
|name = lengthGrowth
|type = float
|default = dir.Length() * (0.5 + RandFloat() * 0.4)
|description = How much the length increases by per update.
}}

{{tag
|name = width
|type = float
|default = 0.0
|description = Half the initial width of of the spike. This is an absolute value.
}}

{{tag
|name = alpha
|type = float
|default = 0.0
|description = The starting alpha of the spike.
}}

{{tag
|name = alphaDecay
|type = float
|default = 0.0
|description = How quickly the alpha of the spike decreases.
}}

{{tag
|name = color
|type = rgb
|default = {1.0, 0.8, 0.5}
|description = The color of the spike.
}}

=== CHeatCloudProjectile ===

Creates an expanding sprite. Simple but effective.

==== Suggested Use ====
* As the main background to an explosion.

==== Properties ====
{{tag
|name = heat
|type = float
|default = 0.0
|description = Used in alpha calculations. See {{taglink|heatFalloff}}.
}}

{{tag
|name = maxheat
|type = float
|default = 0.0
|description = Used in alpha calculations. See {{taglink|heatFalloff}}.
}}

{{tag
|name = heatFalloff
|type = float
|default = 0.0
|description = This is really confusing way of representing alpha and alphaDecay. Basically <code>alpha = </code>{{taglink|heat}}<code>/</code>{{taglink|maxheat}}, and <code>alphaDecay = </code>{{taglink|heatFalloff}}<code>/</code>{{taglink|maxHeat}}.
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = The initial radius of the heatcloud.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = The heatcloud grows by this amount every frame.
}}

{{tag
|name = sizeMod
|type = float
|default = 0.0
|description = The size of the heatcloud is multiplied by <code>1 - sizeMod</code>.
}}

{{tag
|name = sizeModMod
|type = float
|default = 0.0
|description = Each frame, {{taglink|sizeMod}} is multiplied by {{taglink|sizeModMod}}.
}}

{{tag
|name = texture
|type = string
|default = "heatcloud" as referenced in [[resources.lua]]
|description = The texture used for the heatcloud.
}}

=== CSimpleParticleSystem ===

Creates a sprite that can undergo complex motion. Probably the most versatile class.

==== Suggested Use ====
* Anything moving that is not doing so at constant velocity.
* If you want something that expands (or shrinks) to some size then stops, set {{taglink|sizeMod}} to something less than <code>1</code>, and {{taglink|sizeGrowth}} to something positive. The particle will grow to a size equal to <code>sizeGrowth / (1 - sizeMod)</code> and stop. The smaller {{taglink|sizeMod}} is, the faster it will reach this size.

==== Properties ====
===== Initial Velocity Properties =====
{{tag
|name = emitVector
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial direction vector in which the particle is emitted. When spawning CEGs via EmitSfx you can make the particles go into the direction of the emiting piece with {{taglink|emitvector|dir}}. This is useful for e.g. fire coming out of a gun barrel.
}}

{{tag
|name = emitRot
|type = float
|default = 0.0
|description = At what angle to emit the particle relative to {{taglink|emitVector}}. <code>0</code> means that the particle will be emitted in {{taglink|emitVector}}'s direction; <code>180</code> will emit the particle in the opposite direction. <code>90</code> will emit the particle in a random direction perpendicular to {{taglink|emitVector}}, which is good for creating rings.
}}

{{tag
|name = emitRotSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|emitRotSpread}} is added to the {{taglink|emitRot}}.
}}

{{tag
|name = emitMul
|type = float[3]
|default = {1.0, 1.0, 1.0}
|description = Scales the initial particle velocity; for this property, +y is considered to be in the direction of {{taglink|emitVector}}. Good if you want to create an egg-shaped explosion.
}}

{{tag
|name = particleSpeed
|type = float
|default = 0.0
|description = The particle's initial speed.
}}

{{tag
|name = particleSpeedSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleSpeedSpread}} is added to the {{taglink|particleSpeed}}.
}}

===== Movement Properties =====

{{tag
|name = gravity
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = This will be added to the particle's velocity every frame.
}}

{{tag
|name = airdrag
|type = float
|default = 0.0
|description = The particle's velocity is multiplied by this every frame.
}}

===== Size Properties =====

{{tag
|name = particleSize
|type = float
|default = 0.0
|description = The initial size of the particle.
}}

{{tag
|name = particleSizeSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleSizeSpread}} is added to the {{taglink|particleSize}}.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = How much the particle grows each frame.
}}

{{tag
|name = sizeMod
|type = float
|default = 0.0
|description = The size of the particle is multiplied by this each frame.
}}

===== Visual Properties =====

{{tag
|name = directional
|type = bool
|default = false
|description = If true, the particle will point in the direction it is moving.
}}

{{tag
|name = texture
|type = string
|default = ""
|description = The texture to use for the particle.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

===== Life Properties =====

{{tag
|name = numParticles
|type = int
|default = 0
|description = How many particles to create. This is not the same as <code>count</code>; if you spawn multiple particles using <code>count</code>, any [[CEG:Operators]] will be re-evaluated for each particle, whereas if you use {{taglink|numParticles}} they will not be. However, the spread properties are evaluated separately for each particle regardless of which one you use.
}}

{{tag
|name = particleLife
|type = float
|default = 0.0
|description = How long each particle lasts.
}}

{{tag
|name = particleLifeSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleLifeSpread}} is added to the {{taglink|particleLife}}.
}}

=== CSpherePartSpawner ===

Draws an expanding sphere.

==== Suggested Use ====
*Looks like a shockwave.

==== Properties ====

{{tag
|name = alpha
|type = float
|default = 0.0
|description = The alpha of the sphere.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = Time to live, in frames(?).
}}

{{tag
|name = expansionSpeed
|type = float
|default = 0.0
|description = How quickly the sphere expands.
}}

{{tag
|name = color
|type = rgb
|default = {0.0, 0.0, 0.0}
|description = The color of the sphere.
}}

=== CSimpleGroundFlash ===

Draws an expanding ground texture.

==== Suggested Use ====
* A short groundflash (~8 frames) is good for any explosion that gives off light. You can also use a longer groundflash to suggest the ground is glowing from heat.

==== Properties ====

{{tag
|name = size
|type = float
|default = 0.0
|description = The radius of the particle.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = How much the particle grows each frame.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = Time to live, in frames(?).
}}

{{tag
|name = texture
|type = string
|default = ""
|description = The texture to use for the particle.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

=== CStandardGroundFlash ===
If you name a spawner "groundflash," it will always generate a standard groundflash.

==== Suggested Use ====
A short groundflash (~8 frames) is good for any explosion that gives off light. You can also use a longer groundflash to suggest the ground is glowing from heat.

==== Properties ====

{{tag
|name = flashSize
|type = float
|default = 0.0
|description = The radius of the groundflash.
}}

{{tag
|name = flashAlpha
|type = float
|range = [0, 1]
|default = 0.0
|description = How transparent the groundflash is. Generally the higher the brighter.
}}

{{tag
|name = circleGrowth
|type = float
|default = 0.0
|description = A groundflash can have an additional circle that expands outwards. This controls how fast the circle grows.
}}

{{tag
|name = circleAlpha
|type = float
|range = [0, 1]
|default = 0.0
|description = How transparent the circle is.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = How long the groundflash lasts.
}}

{{tag
|name = color
|type = rgb
|default = {1.0, 1.0, 0.8}
|description = The color of the groundflash.
}}

==Examples==


[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/gamedata/explosions 'Balanced Annihilation' CEGs] (TDF format)

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Fgamedata%2Fexplosions 'Conflict Terra' CEGs]

[https://github.com/EvolutionRTS/Evolution-RTS/tree/master/Gamedata/explosions 'Evolution RTS' CEGs]

[https://github.com/imperialwinter/swiw.sdd/tree/master/gamedata/explosions 'Imperial Winter' CEGs] (TDF format)

[http://code.google.com/p/journeywar/source/browse/#svn%2Ftrunk%2Fgamedata%2Fexplosions 'Journeywar' CEGs]

[http://sourceforge.net/p/mwspring/code/HEAD/tree/effects/ 'MechCommander: Legacy' CEGs] (TDF format)

[https://github.com/spring1944/spring1944/tree/master/effects 'Spring: 1944' CEGs] (TDF format)

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FGamedata%2Fexplosions 'Spring Tutorial Game' CEGs]

[http://code.google.com/p/xta-springrts/source/browse/#svn%2Ftrunk%2Fgamedata%2Fexplosions 'XTA' CEGs] (TDF format)

[https://github.com/ZeroK-RTS/Zero-K/tree/master/effects 'ZeroK' CEGs]

[[Category:CEG]]

User:8611

2015-02-27T00:41:17Z

8611: test

test

Script.txt

2015-02-26T23:48:01Z

8611: added: minimum script, generating scripts

= Script.txt =
Start script file for Spring Engine.

Lobbies create it for spring, usually found in <code>~/.spring/script.txt</code> on Linux/MacOSX.

On Windows it can be found mostly in <code>My Documents\My Games\Spring\script.txt</code> or next to spring.exe.

== Structure ==
See {{sourcelink|file=doc/StartScriptFormat.txt}} for a more detailed example.

Spring 97.0 added <code>GAME/MUTATOR{0..9}</code> so you can load arbitrary mutator archives before the game. Addtionally since 97.0 <code>GAME/GameID</code> is the only seed of the synced random generator, so you can define the <code>GameID</code> in a luaAI battle startscript and you will always get a syncing match.

<code><pre>[GAME]
{
// game attributes
[MUTATOR0]
{
// mutator attributes
}
[AI0]
{
// AI attributes
}
[PLAYER0]
{
// player attributes
}
[TEAM0]
{
// team attributes
}
[ALLYTEAM0]
{
// ally team attributes
}
[RESTRICT]
{
// restrictions
}
[MODOPTIONS]
{
// values for the options defined in Modoptions.lua
}
[MAPOPTIONS]
{
// values for the options defined in Mapoptions.lua
}
}</pre></code>

= Examples =
== minimal functional startscript ==
Based on {{forumlink|topic=32893&p=566971#p566953|title=these two posts:}}
<code><pre>
[GAME]
{
MapName=DeltaSiegeDry;
GameType=Balanced Annihilation V8.10;
IsHost=1;
[PLAYER0]
{
Team=0;
}
[TEAM0]
{
TeamLeader=0;
AllyTeam=0;
}
[ALLYTEAM0]
{
}
}
</pre></code>

== More examples ==
startscripts used for pre-defined offline matches vs AI in different team configurations -
https://code.google.com/p/springtanks/source/browse/#svn%2Ftrunk%2FMissions

= Generating startscripts =
It is possible to use for example Springlobby to setup a game via the Singleplayer tab.

The temporary file that gets generated can be copied for further use.

== Converting Lua tables to script.txt format ==

{{forumlink|topic=t=32643|title=lua table -> script.txt generator}} - thread with two examples

[[Category:Development]]

CEG:Miscellaneous

2015-02-01T09:14:18Z

8611: /* Performance */ cegTag every 0.1 seconds

= CEG Miscellaneous =

A collection of miscellaneous things to consider when making a CEG.

== Blending ==

CEGs use the blending mode <code>GL_ONE, GL_ONE_MINUS_SRC_ALPHA</code>. This is in contrast to the default <code>GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA</code>. This means that the alpha determines how much of whatever is behind the particle will show through, but doesn't affect how the particle itself looks. If you want default blending, you'll have to scale the color components by the alpha by hand if the class you're using doesn't do it for you (most classes don't). Note that an alpha of 0 will cause the CEG not to be displayed at all.

== Z-Fighting ==

A related problem is Z-fighting. If you have several high-alpha particles moving through each other, you may get an undesirable flickering effect as one particle is drawn at first, then the other. To solve this, reduce the alpha.

== Randomness ==

Always put a little randomness in your CEGs. CEGs are more interesting if they happen a little differently every time, especially if your CEG gets called more than once at the same time on the same screen.

== Realism ==

While it's important to make sure a CEG doesn't look completely implausible, don't get too hung up on realism. In almost any RTS, concessions are made for gameplay at the cost of a bit of realism; likewise with CEGs, you'll need to make some concessions for looking cool.

== Gameplay ==

As well as looking cool, CEGs are an important part of gameplay. They let players know when things are happening and where they are happening. CEGs should give clues as to what is happening in the mechanics of the game. A powerful weapon should have a powerful-looking CEG; a blast that affects a large area should have a large CEG. Use the alwaysVisisble and useAirLos tags where appropriate. Hopefully we will eventually have a radius operator so CEGs can automatically be scaled to the radius of the weapon.

At the same time, you don't want to obstruct players' views of the game. A CEG should look cool for a moment, and then get out of the way.

== Performance ==

Bascially, try not to use more particles than necessary, and try not to use them longer than necessary. Be aware of how often you expect your CEG to run; if it's a commander death or a nuclear missile, you can afford to spend some extra particles, but if it's a machine gun or a cegtag (which is called every 0.1 seconds), you'll want to keep it down.

[[Category:CEG]]

CEG:Calls

2015-02-01T09:13:28Z

8611: /* Weapon CEGs */ cegTag every 0.1 seconds

= CEG Calls =
== Overview ==
There are four places where you can call a CEG: weapons, COB or LUS unit scripts, flying piece projectiles and synced Lua gadgets.

== Weapon CEGs ==

There are three weapon tags that can spawn CEGs:

*{{xtaglink|Gamedev:WeaponDefs|cegTag}} - Spawns the CEG every 0.1 seconds at the weapon projectile's position and direction.
*{{xtaglink|Gamedev:WeaponDefs|explosionGenerator}} - Spawns the CEG when the weapon hits its target.
*{{xtaglink|Gamedev:WeaponDefs|bounceExplosionGenerator}} - For bouncing weapons only. Spawns the CEG when the weapon bounces.

== Calling CEGs from unit scripts ==

Calling a CEG from unit scripts requires two steps. First, in the unit's definition, you need to '''define the order of the effects:'''

For a .fbi unitdef use:
<code><pre>
[sfxtypes] {
explosiongenerator0 = custom:ExplosionGeneratorName0;
explosiongenerator1 = custom:ExplosionGeneratorName1;
//and so on...
}
</pre></code>

For a .lua unitdef use:

<code><pre>
sfxtypes = {
explosiongenerators = {
"custom:ExplosionGeneratorName0",
"custom:ExplosionGeneratorName1",
--and so on...
},
},
</pre></code>
(See [[Gamedev:UnitDefs#SFXTypes]])

=== COB ===
To actually generate the explosion in a COB, you need to call [[Animation-CobConstants#emit-sfx|emit-sfx]]:

<code><pre>emit-sfx 1024 + ceg_num from pieceName;</pre></code>

Where ceg_num is the number of the explosion generator in the unit definition (the first one is 0, the next is 1, and so on). The CEG will have the position and direction of the piece you emit it from. For syntactic sugar you can use:

<code><pre>#define MY_FIRST_AWESOME_CEG 1024 + 0
emit-sfx MY_FIRST_AWESOME_CEG from pieceName;</pre></code>

In a COB script, you can call:

<code><pre>set CEG_DAMAGE damage_value</pre></code>

Any <code>emit-sfx</code> instructions will then use that value for the "damage" (use the '[[CEG:Operators#Damage_.28.27d.27.29|'d' operator]] to access this value).

=== LUS ===
In a Lua unit script you generate the explosion using [[Animation-LuaCallouts#Effects|Spring.UnitScript.EmitSfx]] e.g.:

<code><pre>EmitSfx(pieceName, SFX.CEG + ceg_num)</pre></code>

Where ceg_num is the number of the explosion generator in the unit definition as before.

== Piece Projectiles ==
CEGs can be attached to piece projectiles which are created when a unit script calls [[Animation-CobConstants#explode|explode]] (COB) or [[Animation-LuaCallouts#Effects|Explode]] (lua) with an argument of <code>COB.FALL</code>. See [[Gamedev:UnitDefs#pieceExplosionGenerators]].

== Synced Lua Gadget CEGs ==
The only method that lets you directly call a CEG by name, anywhere on the map.
See [[Lua_SyncedCtrl#Other|Spring.SpawnCEG]]. Note that the damage parameter does not apply damage, but is used to set the [[CEG:Operators#Damage_.28.27d.27.29|'d' operator]].

[[Category:CEG]]

Gamedev:WeaponDefs

2015-02-01T09:12:39Z

8611: /* Visuals */ cegTag every 0.1 seconds

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

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

{{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 = 0 (See description)
|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. The defaults are as follows:
* <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 = The radius used in collision calculations. For <strike>non-instant-hit</strike> [https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 hitscan] weapons which do not use a 3D {{taglink|model}}.}}

====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
|description = The amount 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 = 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}} for every round in a burst (<code>true</code>) or only once for each salvo (<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 every 0.1 seconds.
}}

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

{{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|repulsor|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]]