Spring - User contributions [en]

Mapdev:mapinfo.lua

2018-11-30T17:21:17Z

Jivvz: /* sound */

= mapinfo.lua Reference =
This file is the primary configuration file for maps, list many things including resources, attributes, ad properties.

==Source==
The engine source code which reads this file from the map is viewable here:
* {{sourcelink|file=rts/Map/MapInfo.cpp}}
* {{sourcelink|file=rts/Map/MapParser.cpp}}

== Example ==
Can be found in the [https://github.com/jk3064/Map-Blueprint/archive/master.zip map blueprint]

= File Location =
relative to the root directory of the map
: ./mapinfo.lua

= Formatting =
check [http://www.lua.org/docs.html Lua Documentation] for syntax etc.

In this wiki page, variables are organised as such:
{{tag|name=VariableName|type=type|range=[valid range]|special=Required|default=value
|description=Description}}

== Data Types ==
{{DataTypes}}

= Sections =
== mapinfo ==
<code><pre>local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "1.0",
--mutator = "deployment";
mapfile = "maps/mymap.smf", -- // location of smf/sm3 file
modtype = 3, --// 1=primary, 0=hidden, 3=map
depend = {"Map Helper v1"},
replace = {},

--startpic = "", --// deprecated
--StartMusic = "", --// deprecated

maphardness = 100,
notDeformable = false,
gravity = 130,
tidalStrength = 0,
maxMetal = 0.02,
extractorRadius = 500.0,
voidWater = false,
voidGround = false,
autoShowMetal = true,

smf = {
...
},

sound = {
...
},

resources = {
...
},

splats = {
...
},

atmosphere = {
...
},

grass = {
...
},

lighting = {
...
},

water = {
...
},

teams = {
...
},

terrainTypes = {
...
},

custom = {
...
},
}</pre></code>

{{tag|name=name|type=string|special=Required|default=none
|description=Name of the map}}

{{tag|name=shortname|type=string|special=Required
|description=maps will not show in the map list without a valid shortname(not sure on its requirements)}}

{{tag|name=description|type=string|default=name
|description=The description of the map that shows in the multiplayer battleroom}}

{{tag|name=author|type=string|default=""
|description=Author of the map}}

{{tag|name=version|type=string
|description=version, appended to name}}

{{tag|name=mutator|type=string}}

{{tag|name=mapfile|type=string
|description=location of smf/sm3 file}}

{{tag|name=modtype|type=int|range=[013]|special=Required
|description=1=primary, 0=hidden, 3=map}}

{{tag|name=depend|special=Required}}

{{tag|name=replace}}

{{tag|name=maphardness|type=float|default=100.0
|description=Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)}}

{{tag|name=notDeformable|type=bool|default=false
|description=Setting it to 1 means that no explosions can deform the map.}}

{{tag|name=gravity|type=float|range=[0.001-max]|default=130.0
|description=As you would expect, affects ballistics and how far units fly after an explosion. The force of gravity in units/sec^2}}

{{tag|name=tidalStrength|type=float|range=[0.0-max]|default=0.0
|description=The amount of energy which will be given by tidal generators.}}

{{tag|name=maxMetal|type=float|range=[0.0-max]|default=0.02
|description=How much metal a map square with the maximum metal value gives.}}

{{tag|name=extractorRadius|type=float|range=[0.0-max]|default=500
|description=The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.}}

{{tag|name=voidWater|type=bool|default=false
|description=Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check [http://springrts.com/phpbb/viewtopic.php?f=13&t=20684&hilit=apophis Apophis_v2]}}. Additionally for this to work, the <code>mapinfo.water.planeColor</code> variable must not be specified in the mapinfo.lua file, delete or comment it out if it exists.

{{tag|name=voidGround|type=bool|default=false
|special=New in 92.0
|description=Allows portions of the ground to be invisible if the map was compiled with a diffuse image that has an alpha channel. The terrain still exists, its just transparent.}}.

{{tag|name=autoShowMetal|type=bool|default=true
|description=Defines whether the metal map (F4 mode) is shown automatically when a mex is queued for placement.}}

== smf ==
<code><pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre></code>
{{tag|name=minHeight|type=float|default=0.0
|description=Overrides the minimum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=maxHeight|type=float|default=0.0
|description=Overrides the maximum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=minimapTex|type=string
|special=New in 99.0
| description=Overrides the minimap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=metalmapTex|type=string
|special=New in 99.0
| description=Overrides the metalmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=typemapTex|type=string
|special=New in 99.0
| description=Overrides the typemap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=grassmapTex|type=string
|special=New in 99.0
| description=Overrides the grassmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=smtFileName[N]|type=string}}

== sound ==
<code><pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

reverb = {
...
},
},
...
}</pre></code>

{{tag|name=preset|type=string|default="default"
|description=Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: [https://github.com/spring/spring/blob/master/rts/System/Sound/OpenAL/EFXPresets.cpp EFXPresets.cpp]}}

{{Tip|You can change the preset at runtime via:
* /tset UseEFX [1|0]
* /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
* /tset snd_filter %gainlf %gainhf (may " " " " " " " " )}}

=== passfilter ===
Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them.
<code><pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre></code>

{{tag|name=gainlf|type=float}}

{{tag|name=gainhf|type=float}}

=== reverb ===
Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document.
<code><pre>local mapinfo = {
...
sound = {
...
reverb = {
--density
--diffusion
--gain
--gainhf
--gainlf
--decaytime
--decayhflimit
--decayhfratio
--decaylfratio
--reflectionsgain
--reflectionsdelay
--reflectionspan
--latereverbgain
--latereverbdelay
--latereverbpan
--echotime
--echodepth
--modtime
--moddepth
--airabsorptiongainhf
--hfreference
--lfreference
--roomrollofffactor
},
},
...
}</pre></code>

== resources ==
<code><pre>local mapinfo = {
...
resources = {
grassBladeTex = "",
grassShadingTex = "",
detailTex = "",
specularTex = "",
splatDetailTex = "",
splatDistrTex = "",
skyReflectModTex = "",
detailNormalTex = "",
lightEmissionTex = "",
parallaxHeightTex = "",
},
...
}</pre></code>

{{tag|name=grassBladeTex|type=string
|description=Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture. More Information: [[Mapdev:grass]]}}

{{tag|name=grassShadingTex|type=string
|description=Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color. More Information: [[Mapdev:grass]]}}

{{tag|name=detailTex|type=string
|description=Specifies the detail texture for the map. More Information: [[Mapdev:detail]]}}

{{tag|name=specularTex|type=string
|description=More Information: [[Mapdev:specular]]}}

{{tag|name=splatDetailTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=splatDistrTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=skyReflectModTex|type=string
|description=More Information: [[Mapdev:skyreflectmod]]}}

{{tag|name=detailNormalTex|type=string
|description=More Information: [[Mapdev:normal]]}}

{{tag|name=lightEmissionTex|type=string
|description=More Information: [[Mapdev:lightemission]]}}

{{tag|name=parallaxHeightTex|type=string
|description=More Information: [[Mapdev:parallax]]}}

== splats ==
<code><pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre></code>
{{tag|name=texScales|type=float[4]
|default={0.2, 0.2, 0.2, 0.2}|description=Scale value for the splat texture in the RGBA channels respectively.}}

{{tag|name=texMults|type=float[4]
|default={1.0, 1.0, 1.0, 1.0}|description=Value for the splat texture in the RGBA channels respectively.}}

== atmosphere ==
<code><pre>local mapinfo = {
...
atmosphere = {
minWind = 5.0,
maxWind = 25.0,

fogStart = 0.1,
fogEnd = 1.0,
fogColor = {0.7, 0.7, 0.8},

sunColor = {1.0, 1.0, 1.0},
skyColor = {0.1, 0.15, 0.7},
skyDir = {0.0, 0.0, -1.0},
skyBox = "",

cloudDensity = 0.5,
cloudColor = {1.0, 1.0, 1.0},
},
...
}</pre></code>

{{tag|name=minWind|type=float|range=[0.0-max]|default=5.0|
description=The minimum amount of energy the wind on the map will give. is clamped to maxwind}}

{{tag|name=maxWind|type=float|range=[0.0-max]|default=25.0
|description=The maximum amount of energy the wind on the map will give}}

{{tag|name=fogStart|type=float|default=0.1
|description=The distance from the camera at which the fog will start. <code>viewRange * fogStart</code>}}

{{tag|name=fogEnd|type=float|default=1.0
|description=The distance from the camera that fog is opaque. <code>viewRange * fogEnd</code> }}}

{{tag|name=fogColor|type=rgb|default={0.7, 0.7, 0.8}
|description=The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker}}

{{tag|name=sunColor|type=rgb|default={1.0, 1.0, 1.0}
|description=The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true}}

{{tag|name=skyColor|type=rgb|default={0.1, 0.15, 0.7}
|description=The color of the sky itself. The values are in the order Red, Green, Blue}}

{{tag|name=skyDir|type=float[3]|default={0.0, 0.0, -1.0}
|description=Is normalised vector}}

{{tag|name=skyBox|type=string
|description=Specify a .dds skybox (also called skycube) for examples and resources see this [http://springrts.com/phpbb/viewtopic.php?f=56&t=11009 thread]}}

{{tag|name=cloudDensity|type=float|range=[0.0-max]|default=0.5
|description=The amount of clouds in the sky}}

{{tag|name=cloudColor|type=rgb
|default={1.0, 1.0, 1.0}|description=The color of the clouds}}

== grass ==
<code><pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
},
...
}</pre></code>
{{tag|name=bladeWaveScale|type=float|default=1.0
|description=Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation}}

{{tag|name=bladeWidth|type=float|default=0.32
|description=Specifies the width of each blade of grass}}

{{tag|name=bladeHeight|type=float|default=4.0
|description=Specifies the length of each blade of grass}}

{{tag|name=bladeAngle|type=float|default=1.57
|description=Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass}}

{{tag|name=bladeColor|type=rgb|default={0.59, 0.81, 0.57}
|description=does nothing when `grassBladeTex` is set}}

== Lighting ==
<code><pre>local mapinfo = {
...
lighting = {
--// dynsun
sunStartAngle = 0.0,
sunOrbitTime = 1440.0,
sunDir = {0.0, 1.0, 2.0, 1e9},

--// unit & ground lighting
groundAmbientColor = {0.5, 0.5, 0.5},
groundDiffuseColor = {0.5, 0.5, 0.5},
groundSpecularColor = {0.1, 0.1, 0.1},
groundShadowDensity = 0.8,
unitAmbientColor = {0.4, 0.4, 0.4},
unitDiffuseColor = {0.7, 0.7, 0.7},
unitSpecularColor = {0.7, 0.7, 0.7},
unitShadowDensity = 0.8,

specularExponent = 100.0,
},
...
}</pre></code>
{{tag|name=sunStartAngle|type=float|default=0.0}}

{{tag|name=sunOrbitTime|type=float|default=1440.0}}

{{tag|name=sunDir|type=float[3]|default={0.0, 1.0, 2.0}
|description=The direction of the sun, which is normalized by Spring. The Y-axis is up}}

{{tag|name=groundAmbientColor|type=rgb|default={0.5, 0.5, 0.5}
|description=The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue}}

{{tag|name=groundDiffuseColor|type=rgb|default={0.5, 05, 0.5}
|description=The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue}}

{{tag|name=groundSpecularColor|type=rgb|default={0.1, 0.1, 0.1}
|description=and its effect when a specular map is present?}}

{{tag|name=groundShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go.}}

{{tag|name=unitAmbientColor|type=float|default={0.4, 0.4, 0.4}
|description=The ambient (non-sun-lit) color of units and corpses}}

{{tag|name=unitDiffuseColor|type=rgb|default={0.7, 0.7, 0.7}
|description=The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor)}}

{{tag|name=unitSpecularColor|type=rgb|default=unitDiffuseColor}}

{{tag|name=unitShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go}}

{{tag|name=specularExponent|type=float|default=100}}

== water ==
<code><pre>local mapinfo = {
...
water = {
damage = 0.0,

repeatX = 0.0,
repeatY = 0.0,

absorb = {0.0, 0.0, 0.0},
baseColor = {0.0, 0.0, 0.0},
minColor = {0.0, 0.0, 0.0},

ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.0,

planeColor = {0.0, 0.4, 0.0},

surfaceColor = {0.75, 0.8, 0.85},
surfaceAlpha = 0.55,
diffuseColor = {1.0, 1.0, 1.0},
specularColor = {0.5, 0.5, 0.5},

fresnelMin = 0.2,
fresnelMax = 0.8,
fresnelPower = 4.0,

reflectionDistortion = 1.0,

blurBase = 2.0,
blurExponent = 1.5,

perlinStartFreq = 8.0,
perlinLacunarity = 3.0,
perlinAmplitude = 0.9,
windSpeed = 1.0, --// does nothing yet

shoreWaves = true,
forceRendering = false,

--// undefined == load them from resources.lua!
--texture = "",
--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},

},
...
}</pre></code>
{{tag|name=damage|type=float|default=0.0
|description=Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water. As of 95.0 by default damage is also applied to hovercraft units. i wonder if this can be made to give life...?}}

{{tag|name=repeatX|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=repeatY|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=absorb|type=rgb|default={0.0, 0.0, 0.0}
|description=How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel}}

{{tag|name=baseColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue}}

{{tag|name=minColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The smallest values the water will go down to due to WaterAbsorb}}

{{tag|name=ambientFactor|type=float|default=1.0}}

{{tag|name=diffuseFactor|type=float|default=1.0}}

{{tag|name=specularFactor|type=float|default=1.0}}

{{tag|name=specularPower|type=float|default=20.0}}

{{tag|name=planeColor|type=rgb|default={0.0, 0.4, 0.0}
|description=This sets the color of the groundplane under the water outside the map boundaries}}

{{tag|name=surfaceColor|type=rgb|default={0.75, 0.8, 0.85}
|description=The color of the water surface. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!}}

{{tag|name=surfaceAlpha|type=float|default=0.55
|description= Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections)}}

{{tag|name=diffuseColor|type=rgb|default=value
|description=This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid}}

{{tag|name=specularColor|type=rgb|default=lighting.groundDiffuseColor}}

{{tag|name=fresnelMin|type=float|default=0.2}}

{{tag|name=fresnelMax|type=float|default=0.8}}

{{tag|name=fresnelPower|type=float|default=4.0}}

{{tag|name=reflectionDistortion|type=float|default=1.0
|description=How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20}}

{{tag|name=blurBase|type=float|default=2.0
|description=Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10}}

{{tag|name=blurExponent|type=float|default=1.5
|description=How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption}}

{{tag|name=perlinStartFreq|type=float|default=8.0
|description=Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)}}

{{tag|name=perlinLacunarity|type=float|default=3.0
|description=Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)}}

{{tag|name=perlinAmplitude|type=float|default=0.9
|description=Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0}}

{{tag|name=windSpeed|type=float|default=1.0
|description=does nothing yet}}

{{tag|name=shoreWaves|type=bool|default=true}}

{{tag|name=forceRendering|type=bool|default=true}}

will have to ask about those undefined tags

== teams ==
<code><pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 2033, z = 852}},
[1] = {startPos = {x = 10134, z = 852}},
[2] = {startPos = {x = 0, z = 0}},
[3] = {startPos = {x = 0, z = 0}},
...
},
...
}</pre></code>
Holds an array of start positions

== terrainTypes ==
<code><pre>local mapinfo = {
...
terrainTypes = {
[0] = {
name = "Default",
hardness = 1.0,
receiveTracks = true,
moveSpeeds = {
tank = 1.0,
kbot = 1.0,
hover = 1.0,
ship = 1.0,
},
},
[1] = {
...
},
...
},
...
}</pre></code>
Holds an array of start types where each element contains:

{{tag|name=name|type=string
|description=A label for the terrain type}}

{{tag|name=hardness|type=float|range=[0.001-max]|default=1.0
|description=Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard}}

{{tag|name=receiveTracks|type=bool|default=true
|description= Effects whether track decals will be placed on the ground from moving vehicles}}

{{tag|name=moveSpeeds.tank|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for tanks when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.kbot|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for kbots when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.hover|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.ship|type=float|range=[0.0-max]|default=1
|description= Speed multiplier for ships when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

== custom ==
<code><pre>local mapinfo = {
...
custom = {
fog = {
color = {0.26, 0.30, 0.41},
height = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
fogatten = 0.003,
},
precipitation = {
density = 30000,
size = 1.5,
speed = 50,
windscale = 1.2,
texture = 'LuaGaia/effects/snowflake.png',
},

},
...
}</pre></code>

[[Category:Map Dev]]

Mapdev:mapinfo.lua

2018-11-30T17:20:10Z

Jivvz: /* sound */

= mapinfo.lua Reference =
This file is the primary configuration file for maps, list many things including resources, attributes, ad properties.

==Source==
The engine source code which reads this file from the map is viewable here:
* {{sourcelink|file=rts/Map/MapInfo.cpp}}
* {{sourcelink|file=rts/Map/MapParser.cpp}}

== Example ==
Can be found in the [https://github.com/jk3064/Map-Blueprint/archive/master.zip map blueprint]

= File Location =
relative to the root directory of the map
: ./mapinfo.lua

= Formatting =
check [http://www.lua.org/docs.html Lua Documentation] for syntax etc.

In this wiki page, variables are organised as such:
{{tag|name=VariableName|type=type|range=[valid range]|special=Required|default=value
|description=Description}}

== Data Types ==
{{DataTypes}}

= Sections =
== mapinfo ==
<code><pre>local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "1.0",
--mutator = "deployment";
mapfile = "maps/mymap.smf", -- // location of smf/sm3 file
modtype = 3, --// 1=primary, 0=hidden, 3=map
depend = {"Map Helper v1"},
replace = {},

--startpic = "", --// deprecated
--StartMusic = "", --// deprecated

maphardness = 100,
notDeformable = false,
gravity = 130,
tidalStrength = 0,
maxMetal = 0.02,
extractorRadius = 500.0,
voidWater = false,
voidGround = false,
autoShowMetal = true,

smf = {
...
},

sound = {
...
},

resources = {
...
},

splats = {
...
},

atmosphere = {
...
},

grass = {
...
},

lighting = {
...
},

water = {
...
},

teams = {
...
},

terrainTypes = {
...
},

custom = {
...
},
}</pre></code>

{{tag|name=name|type=string|special=Required|default=none
|description=Name of the map}}

{{tag|name=shortname|type=string|special=Required
|description=maps will not show in the map list without a valid shortname(not sure on its requirements)}}

{{tag|name=description|type=string|default=name
|description=The description of the map that shows in the multiplayer battleroom}}

{{tag|name=author|type=string|default=""
|description=Author of the map}}

{{tag|name=version|type=string
|description=version, appended to name}}

{{tag|name=mutator|type=string}}

{{tag|name=mapfile|type=string
|description=location of smf/sm3 file}}

{{tag|name=modtype|type=int|range=[013]|special=Required
|description=1=primary, 0=hidden, 3=map}}

{{tag|name=depend|special=Required}}

{{tag|name=replace}}

{{tag|name=maphardness|type=float|default=100.0
|description=Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)}}

{{tag|name=notDeformable|type=bool|default=false
|description=Setting it to 1 means that no explosions can deform the map.}}

{{tag|name=gravity|type=float|range=[0.001-max]|default=130.0
|description=As you would expect, affects ballistics and how far units fly after an explosion. The force of gravity in units/sec^2}}

{{tag|name=tidalStrength|type=float|range=[0.0-max]|default=0.0
|description=The amount of energy which will be given by tidal generators.}}

{{tag|name=maxMetal|type=float|range=[0.0-max]|default=0.02
|description=How much metal a map square with the maximum metal value gives.}}

{{tag|name=extractorRadius|type=float|range=[0.0-max]|default=500
|description=The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.}}

{{tag|name=voidWater|type=bool|default=false
|description=Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check [http://springrts.com/phpbb/viewtopic.php?f=13&t=20684&hilit=apophis Apophis_v2]}}. Additionally for this to work, the <code>mapinfo.water.planeColor</code> variable must not be specified in the mapinfo.lua file, delete or comment it out if it exists.

{{tag|name=voidGround|type=bool|default=false
|special=New in 92.0
|description=Allows portions of the ground to be invisible if the map was compiled with a diffuse image that has an alpha channel. The terrain still exists, its just transparent.}}.

{{tag|name=autoShowMetal|type=bool|default=true
|description=Defines whether the metal map (F4 mode) is shown automatically when a mex is queued for placement.}}

== smf ==
<code><pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre></code>
{{tag|name=minHeight|type=float|default=0.0
|description=Overrides the minimum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=maxHeight|type=float|default=0.0
|description=Overrides the maximum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=minimapTex|type=string
|special=New in 99.0
| description=Overrides the minimap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=metalmapTex|type=string
|special=New in 99.0
| description=Overrides the metalmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=typemapTex|type=string
|special=New in 99.0
| description=Overrides the typemap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=grassmapTex|type=string
|special=New in 99.0
| description=Overrides the grassmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=smtFileName[N]|type=string}}

== sound ==
<code><pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

reverb = {
...
},
},
...
}</pre></code>

{{tag|name=preset|type=string|default="default"
|description=Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: [https://github.com/spring/spring/blob/master/rts/System/Sound/OpenAL/EFXPresets.cpp]}}

{{Tip|You can change the preset at runtime via:
* /tset UseEFX [1|0]
* /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
* /tset snd_filter %gainlf %gainhf (may " " " " " " " " )}}

=== passfilter ===
Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them.
<code><pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre></code>

{{tag|name=gainlf|type=float}}

{{tag|name=gainhf|type=float}}

=== reverb ===
Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document.
<code><pre>local mapinfo = {
...
sound = {
...
reverb = {
--density
--diffusion
--gain
--gainhf
--gainlf
--decaytime
--decayhflimit
--decayhfratio
--decaylfratio
--reflectionsgain
--reflectionsdelay
--reflectionspan
--latereverbgain
--latereverbdelay
--latereverbpan
--echotime
--echodepth
--modtime
--moddepth
--airabsorptiongainhf
--hfreference
--lfreference
--roomrollofffactor
},
},
...
}</pre></code>

== resources ==
<code><pre>local mapinfo = {
...
resources = {
grassBladeTex = "",
grassShadingTex = "",
detailTex = "",
specularTex = "",
splatDetailTex = "",
splatDistrTex = "",
skyReflectModTex = "",
detailNormalTex = "",
lightEmissionTex = "",
parallaxHeightTex = "",
},
...
}</pre></code>

{{tag|name=grassBladeTex|type=string
|description=Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture. More Information: [[Mapdev:grass]]}}

{{tag|name=grassShadingTex|type=string
|description=Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color. More Information: [[Mapdev:grass]]}}

{{tag|name=detailTex|type=string
|description=Specifies the detail texture for the map. More Information: [[Mapdev:detail]]}}

{{tag|name=specularTex|type=string
|description=More Information: [[Mapdev:specular]]}}

{{tag|name=splatDetailTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=splatDistrTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=skyReflectModTex|type=string
|description=More Information: [[Mapdev:skyreflectmod]]}}

{{tag|name=detailNormalTex|type=string
|description=More Information: [[Mapdev:normal]]}}

{{tag|name=lightEmissionTex|type=string
|description=More Information: [[Mapdev:lightemission]]}}

{{tag|name=parallaxHeightTex|type=string
|description=More Information: [[Mapdev:parallax]]}}

== splats ==
<code><pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre></code>
{{tag|name=texScales|type=float[4]
|default={0.2, 0.2, 0.2, 0.2}|description=Scale value for the splat texture in the RGBA channels respectively.}}

{{tag|name=texMults|type=float[4]
|default={1.0, 1.0, 1.0, 1.0}|description=Value for the splat texture in the RGBA channels respectively.}}

== atmosphere ==
<code><pre>local mapinfo = {
...
atmosphere = {
minWind = 5.0,
maxWind = 25.0,

fogStart = 0.1,
fogEnd = 1.0,
fogColor = {0.7, 0.7, 0.8},

sunColor = {1.0, 1.0, 1.0},
skyColor = {0.1, 0.15, 0.7},
skyDir = {0.0, 0.0, -1.0},
skyBox = "",

cloudDensity = 0.5,
cloudColor = {1.0, 1.0, 1.0},
},
...
}</pre></code>

{{tag|name=minWind|type=float|range=[0.0-max]|default=5.0|
description=The minimum amount of energy the wind on the map will give. is clamped to maxwind}}

{{tag|name=maxWind|type=float|range=[0.0-max]|default=25.0
|description=The maximum amount of energy the wind on the map will give}}

{{tag|name=fogStart|type=float|default=0.1
|description=The distance from the camera at which the fog will start. <code>viewRange * fogStart</code>}}

{{tag|name=fogEnd|type=float|default=1.0
|description=The distance from the camera that fog is opaque. <code>viewRange * fogEnd</code> }}}

{{tag|name=fogColor|type=rgb|default={0.7, 0.7, 0.8}
|description=The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker}}

{{tag|name=sunColor|type=rgb|default={1.0, 1.0, 1.0}
|description=The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true}}

{{tag|name=skyColor|type=rgb|default={0.1, 0.15, 0.7}
|description=The color of the sky itself. The values are in the order Red, Green, Blue}}

{{tag|name=skyDir|type=float[3]|default={0.0, 0.0, -1.0}
|description=Is normalised vector}}

{{tag|name=skyBox|type=string
|description=Specify a .dds skybox (also called skycube) for examples and resources see this [http://springrts.com/phpbb/viewtopic.php?f=56&t=11009 thread]}}

{{tag|name=cloudDensity|type=float|range=[0.0-max]|default=0.5
|description=The amount of clouds in the sky}}

{{tag|name=cloudColor|type=rgb
|default={1.0, 1.0, 1.0}|description=The color of the clouds}}

== grass ==
<code><pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
},
...
}</pre></code>
{{tag|name=bladeWaveScale|type=float|default=1.0
|description=Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation}}

{{tag|name=bladeWidth|type=float|default=0.32
|description=Specifies the width of each blade of grass}}

{{tag|name=bladeHeight|type=float|default=4.0
|description=Specifies the length of each blade of grass}}

{{tag|name=bladeAngle|type=float|default=1.57
|description=Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass}}

{{tag|name=bladeColor|type=rgb|default={0.59, 0.81, 0.57}
|description=does nothing when `grassBladeTex` is set}}

== Lighting ==
<code><pre>local mapinfo = {
...
lighting = {
--// dynsun
sunStartAngle = 0.0,
sunOrbitTime = 1440.0,
sunDir = {0.0, 1.0, 2.0, 1e9},

--// unit & ground lighting
groundAmbientColor = {0.5, 0.5, 0.5},
groundDiffuseColor = {0.5, 0.5, 0.5},
groundSpecularColor = {0.1, 0.1, 0.1},
groundShadowDensity = 0.8,
unitAmbientColor = {0.4, 0.4, 0.4},
unitDiffuseColor = {0.7, 0.7, 0.7},
unitSpecularColor = {0.7, 0.7, 0.7},
unitShadowDensity = 0.8,

specularExponent = 100.0,
},
...
}</pre></code>
{{tag|name=sunStartAngle|type=float|default=0.0}}

{{tag|name=sunOrbitTime|type=float|default=1440.0}}

{{tag|name=sunDir|type=float[3]|default={0.0, 1.0, 2.0}
|description=The direction of the sun, which is normalized by Spring. The Y-axis is up}}

{{tag|name=groundAmbientColor|type=rgb|default={0.5, 0.5, 0.5}
|description=The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue}}

{{tag|name=groundDiffuseColor|type=rgb|default={0.5, 05, 0.5}
|description=The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue}}

{{tag|name=groundSpecularColor|type=rgb|default={0.1, 0.1, 0.1}
|description=and its effect when a specular map is present?}}

{{tag|name=groundShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go.}}

{{tag|name=unitAmbientColor|type=float|default={0.4, 0.4, 0.4}
|description=The ambient (non-sun-lit) color of units and corpses}}

{{tag|name=unitDiffuseColor|type=rgb|default={0.7, 0.7, 0.7}
|description=The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor)}}

{{tag|name=unitSpecularColor|type=rgb|default=unitDiffuseColor}}

{{tag|name=unitShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go}}

{{tag|name=specularExponent|type=float|default=100}}

== water ==
<code><pre>local mapinfo = {
...
water = {
damage = 0.0,

repeatX = 0.0,
repeatY = 0.0,

absorb = {0.0, 0.0, 0.0},
baseColor = {0.0, 0.0, 0.0},
minColor = {0.0, 0.0, 0.0},

ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.0,

planeColor = {0.0, 0.4, 0.0},

surfaceColor = {0.75, 0.8, 0.85},
surfaceAlpha = 0.55,
diffuseColor = {1.0, 1.0, 1.0},
specularColor = {0.5, 0.5, 0.5},

fresnelMin = 0.2,
fresnelMax = 0.8,
fresnelPower = 4.0,

reflectionDistortion = 1.0,

blurBase = 2.0,
blurExponent = 1.5,

perlinStartFreq = 8.0,
perlinLacunarity = 3.0,
perlinAmplitude = 0.9,
windSpeed = 1.0, --// does nothing yet

shoreWaves = true,
forceRendering = false,

--// undefined == load them from resources.lua!
--texture = "",
--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},

},
...
}</pre></code>
{{tag|name=damage|type=float|default=0.0
|description=Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water. As of 95.0 by default damage is also applied to hovercraft units. i wonder if this can be made to give life...?}}

{{tag|name=repeatX|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=repeatY|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=absorb|type=rgb|default={0.0, 0.0, 0.0}
|description=How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel}}

{{tag|name=baseColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue}}

{{tag|name=minColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The smallest values the water will go down to due to WaterAbsorb}}

{{tag|name=ambientFactor|type=float|default=1.0}}

{{tag|name=diffuseFactor|type=float|default=1.0}}

{{tag|name=specularFactor|type=float|default=1.0}}

{{tag|name=specularPower|type=float|default=20.0}}

{{tag|name=planeColor|type=rgb|default={0.0, 0.4, 0.0}
|description=This sets the color of the groundplane under the water outside the map boundaries}}

{{tag|name=surfaceColor|type=rgb|default={0.75, 0.8, 0.85}
|description=The color of the water surface. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!}}

{{tag|name=surfaceAlpha|type=float|default=0.55
|description= Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections)}}

{{tag|name=diffuseColor|type=rgb|default=value
|description=This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid}}

{{tag|name=specularColor|type=rgb|default=lighting.groundDiffuseColor}}

{{tag|name=fresnelMin|type=float|default=0.2}}

{{tag|name=fresnelMax|type=float|default=0.8}}

{{tag|name=fresnelPower|type=float|default=4.0}}

{{tag|name=reflectionDistortion|type=float|default=1.0
|description=How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20}}

{{tag|name=blurBase|type=float|default=2.0
|description=Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10}}

{{tag|name=blurExponent|type=float|default=1.5
|description=How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption}}

{{tag|name=perlinStartFreq|type=float|default=8.0
|description=Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)}}

{{tag|name=perlinLacunarity|type=float|default=3.0
|description=Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)}}

{{tag|name=perlinAmplitude|type=float|default=0.9
|description=Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0}}

{{tag|name=windSpeed|type=float|default=1.0
|description=does nothing yet}}

{{tag|name=shoreWaves|type=bool|default=true}}

{{tag|name=forceRendering|type=bool|default=true}}

will have to ask about those undefined tags

== teams ==
<code><pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 2033, z = 852}},
[1] = {startPos = {x = 10134, z = 852}},
[2] = {startPos = {x = 0, z = 0}},
[3] = {startPos = {x = 0, z = 0}},
...
},
...
}</pre></code>
Holds an array of start positions

== terrainTypes ==
<code><pre>local mapinfo = {
...
terrainTypes = {
[0] = {
name = "Default",
hardness = 1.0,
receiveTracks = true,
moveSpeeds = {
tank = 1.0,
kbot = 1.0,
hover = 1.0,
ship = 1.0,
},
},
[1] = {
...
},
...
},
...
}</pre></code>
Holds an array of start types where each element contains:

{{tag|name=name|type=string
|description=A label for the terrain type}}

{{tag|name=hardness|type=float|range=[0.001-max]|default=1.0
|description=Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard}}

{{tag|name=receiveTracks|type=bool|default=true
|description= Effects whether track decals will be placed on the ground from moving vehicles}}

{{tag|name=moveSpeeds.tank|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for tanks when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.kbot|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for kbots when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.hover|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.ship|type=float|range=[0.0-max]|default=1
|description= Speed multiplier for ships when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

== custom ==
<code><pre>local mapinfo = {
...
custom = {
fog = {
color = {0.26, 0.30, 0.41},
height = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
fogatten = 0.003,
},
precipitation = {
density = 30000,
size = 1.5,
speed = 50,
windscale = 1.2,
texture = 'LuaGaia/effects/snowflake.png',
},

},
...
}</pre></code>

[[Category:Map Dev]]

Lua:Callins

2018-03-23T20:05:47Z

Jivvz: /* Input */ added link to key code lookup

= Lua Callins =
This page is future looking to unified widget/gadget (aka "addon") handler, which may yet be some way off, c.f. the [https://github.com/spring/spring/blob/ebb704e008f6ea645947d07be1cfcc272af0428f/doc/changelog.txt#L71 changelog].

Related Sourcecode :
[https://github.com/spring/spring/blob/d9b3927a528a876b9ab4042771e82b050267572a/rts/Lua/LuaHandle.cpp https://github.com/spring/spring/rts/Lua/LuaHandle.cpp]

For now, to use these addons in a widget, replace addon with widget and, for a gadget, replace addon with gadget. For example,
<code><pre>
function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)
...
end
</pre></code>

Some functions may differ between (synced) gadget and widgets; those are in the [[#Synced_-_Unsynced_Shared]] section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.

== Common ==
{{LuaCallin
|name = Initialize
|info = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|info = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|args = type, id
|return = {{type|number}} cmdID
|info = Used to set the default command when a unit is selected. First parameter is the type of the object pointed at (either "unit or "feature") and the second is its {{var|unitID}} or {{var|featureID}} respectively.
}}

{{LuaCallin
|name = CommandNotify
|args = cmdID, cmdParams, cmdOptions
|return = {{type|bool}} removeCmd
|info = Called when a command is issued. Returning {{value|true}} deletes the command and does not send it through the network.
}}

{{LuaCallin
|name = CommandsChanged
|args = None
|return = ?
|info = Called when the command descriptions changed, e.g. when selecting or deselecting a unit.
}}

{{LuaCallin
|name = WorldTooltip
|args = ttType, data1, data2, data3
|return = {{type|string}} newTooltip
|info = The parameters can be {{value|"unit"}}, {{var|unitID}}; {{value|"feature"}}, {{var|featureID}}; {{value|"ground"}}, {{var|posX}}, {{var|posY}}, {{var|posZ}} or {{value|"selection"}}.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|args = ???
|info = Called when the unsynced copy of the height-map is altered.
}}

{{LuaCallin
|name = GameProgress
|args = serverFrameNum
|info = Called every 60 frames, calculating delta between GameFrame and GameProgress. Can give an ETA about catching up with simulation for mid-game join players.
}}

{{LuaCallin
|name = GameSetup
|args = state, ready, playerStates
|return = {{type|bool}} success, {{type|bool}} newReady
|info = ???
}}

{{LuaCallin
|name = SunChanged
|args = ???
|info = ???
}}

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

{{LuaCallin
|name = RecvSkirmishAIMessage
|args = aiTeam, dataStr
|return = ???
|info = ???
}}

{{LuaCallin
|name = RecvFromSynced
|args = ...
|info = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

{{LuaCallin
|name = Save
|args = zip
|info = Called when a chat command '/save' or '/savegame' is received. The single argument is a userdatum representing the savegame zip file. See [[Lua_SaveLoad#Save_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

{{LuaCallin
|name = LoadProgress
|args = message, replaceLastLine
|info = Only available to LuaIntro.
}}

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

{{LuaCallin
|name = ConfigureLayout
|args = ???
|return = ???
|info = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|args = x, y
|return = {{type|bool}} isAbove
|info = Called every Update. Must return {{value|true}} for {{name|Mouse*}} events and {{name|GetToolTip}} to be called.
}}

{{LuaCallin
|name = GetTooltip
|args = x, y
|return = {{type|string}} tooltip
|info = Called when {{name|IsAbove}} returns {{value|true}}.
}}

{{LuaCallin
|name = KeyPress
|args = key, mods, isRepeat
|return = {{type|bool}} becomeOwner
|info = Called repeatedly when a key is pressed down. If you want an action to occur only once check for {{var|1=isRepeat == {{value|false}}}}. The {{var|mods}} parameter is a {{type|table}}, with keys {{value|"alt"}}, {{value|"ctrl"}}, {{value|"meta"}} and {{value|"shift"}} each having a boolean value. Return {{value|true}} if you don't want other callins or the engine to also receive this keypress. A list of key codes can be seen at the [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{LuaCallin
|name = KeyRelease
|args = key
|return = {{type|bool}}
|info = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|args = utf8char
|info = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|args = ???
|info = ???
}}

{{LuaCallin
|name = MousePress
|args = x, y, button
|return = {{type|bool}} becomeMouseOwner
|info = Called when a mouse button is pressed. The {{var|button}} parameter supports up to 7 buttons. Must return {{value|true}} for {{name|MouseRelease}} and other functions to be called.
}}

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

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

{{LuaCallin
|name = MouseMove
|args = x, y, dx, dy, button
|info = Called when the mouse is moved. The {{var|dx}} and {{var|dy}} parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|args = playerID
|info = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|args = playerID
|info = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|args = playerID, reason
|info = Called whenever a player is removed from the game.
}}

=== Downloads ===

{{LuaCallin
|name = DownloadStarted
|args = id
|info = Called when a [[Pr-downloader]] download is started via [[Lua_VFS#Archives|VFS.DownloadArchive]].
}}

{{LuaCallin
|name = DownloadFinished
|args = id
|info = Called when a [[Pr-downloader]] download finishes successfully.
}}

{{LuaCallin
|name = DownloadFailed
|args = id, errorID
|info = Called when a [[Pr-downloader]] download fails to complete.
}}

{{LuaCallin
|name = DownloadProgress
|args = id, downloaded, total
|info = Called incrementally during a [[Pr-downloader]] download.
}}

=== Drawing ===
{{LuaCallin
|name = ViewResize
|args = viewSizeX, viewSizeY
|info = Called whenever the window is resized.
}}

{{LuaCallin
|name = Update
|args = dt
|info = Called for every draw frame. The parameter is the time since the last update. Perform calculations in here and only drawing in Draw* callins.}}

Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

{{LuaCallin
|name = DrawGenesis
|info = Doesn't render to screen! Use this callin to update textures, shaders, etc. Also available to LuaMenu.
}}

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

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

{{LuaCallin
|name = DrawWorld
|info = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|info = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|info = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|info = ???
}}

{{LuaCallin
|name = DrawGroundPreForward
|info = Runs at the start of the forward pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPreDeferred
|info = Runs at the start of the deferred pass when a custom map shader has been assigned via [[Lua_UnsyncedCtrl#Map|{{name|Spring.SetMapShader}}]] (convenient for setting uniforms).
}}

{{LuaCallin
|name = DrawGroundPostDeferred
|info = This runs at the end of its respective deferred pass and allows proper frame compositing (with ground flashes/decals/foliage/etc, which are drawn between it and [[#API:DrawWorldPreUnit|{{name|DrawWorldPreUnit}}]]) via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]].
}}

{{LuaCallin
|name = DrawUnitsPostDeferred
|info = Runs at the end of the unit deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawFeaturesPostDeferred
|info = Runs at the end of the feature deferred pass to inform Lua code it should make use of the {{value|$model_gbuffer_*}} textures before another pass overwrites them (and to allow proper blending with e.g. cloaked objects which are drawn between these events and [[#API:DrawWorld|{{name|DrawWorld}}]] via [[Lua_OpenGL_Api#Textures|{{name|gl.CopyToTexture}}]]). N.B. The *PostDeferred events are only sent (and only have a real purpose) if forward drawing is disabled.
}}

{{LuaCallin
|name = DrawScreen
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

{{LuaCallin
|name = DrawScreenEffects
|args = vsx, vsy
|info = Where {{var|vsx}}, {{var|vsy}} are screen coordinates.
}}

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{LuaCallin
|name = DrawLoadScreen
|info = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|args = sx, sy
|info = Where {{var|sx}}, {{var|sy}} are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls {{var|drawMode}} can be one of the following, {{var|1=notDrawing = {{value|0}}}}, {{var|1=normalDraw = {{value|1}}}}, {{var|1=shadowDraw = {{value|2}}}}, {{var|1=reflectionDraw = {{value|3}}}}, {{var|1=refractionDraw = {{value|4}}}}, and finally {{var|1=gameDeferredDraw = {{value|5}}}} which was added in 102.0.

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

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

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

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

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|args = msg, player
|info = Called when a player issues a UI command e.g. types {{var|/foo}} or {{var|/luarules foo}}.
}}

=== Game ===

{{LuaCallin
|name = GameID
|args = gameID
|info = Called once to deliver the {{var|gameID}}. As of 101.0+ the string is encoded in hex.
}}

{{LuaCallin
|name = GamePaused
|info = Called when the game is paused.
}}

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

{{LuaCallin
|name = GameFrame
|args = frame
|info = Called for every game simulation frame (30 per second). Starts at frame {{value|0}} in 101.0+ and {{value|1}} in previous versions.
}}

{{LuaCallin
|name = GamePreload
|info = Called before the 0 gameframe. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|args = teamID
|info = ???
}}

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

=== Units ===
{{LuaCallin
|name = UnitCreated
|args = unitID, unitDefID, unitTeam, builderID
|info = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|args = unitID, unitDefID, unitTeam
|info = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|args = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|info = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitReverseBuilt
|args = unitID, unitDefID, unitTeam
|info = Called when a living unit becomes a nanoframe again.
}}

{{LuaCallin
|name = UnitGiven
|args = unitID, unitDefID, newTeam, oldTeam
|info = Called when a unit is transferred between teams. This is called after {{name|UnitTaken}} and in that moment unit is assigned to the '''newTeam'''.
}}

{{LuaCallin
|name = UnitTaken
|args = unitID, unitDefID, oldTeam, newTeam
|info = Called when a unit is transferred between teams. This is called before {{name|UnitGiven}} and in that moment unit is still assigned to the '''oldTeam'''.
}}

{{LuaCallin
|name = UnitDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is damaged (after {{name|UnitPreDamaged}}).
}}

{{LuaCallin
|name = UnitDestroyed
|args = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|info = Called when a unit is destroyed.
}}

{{LuaCallin
|name = RenderUnitDestroyed
|args = unitID, unitDefID, unitTeam
|info = Called just before a unit is invalid, after it finishes its death animation. {{new|101.0}}
}}

{{LuaCallin
|name = UnitStunned
|args = unitID, unitDefID, unitTeam, stunned
|info = Called when a unit changes its stun status. {{new|99.0}}
}}

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

{{LuaCallin
|name = UnitFeatureCollision
|args = colliderID, collideeID
|info = Called when a unit collides with a feature. The unit must be registered with [[Lua_System#Synced|Script.SetWatchUnit]] and the feature registered with [[Lua_System#Synced|Script.SetWatchFeature]].
}}

{{LuaCallin
|name = UnitCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called after when a unit accepts a command, after {{name|AllowCommand}} returns {{value|true}}.
}}

{{LuaCallin
|name = UnitCmdDone
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|info = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|args = unitID, unitDefID, unitTeam, transportID, transportTeam
|info = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|args = unitID, unitDefID, unitTeam, experience, oldExperience
|info = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{LuaCallin
|name = UnitIdle
|args = unitID, unitDefID, unitTeam
|info = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|args = unitID, unitDefID, unitTeam
|info = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|args = ???
|info = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|args = ???
|info = ??? Not implemented in base handler
}}

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

{{LuaCallin
|name = UnitEnteredLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|args = ???
|info = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|args = ???
|info = ??? Not implemented by base handler
}}

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

=== Features ===
{{LuaCallin
|name = FeatureCreated
|args = featureID, allyTeamID
|info = Called when a feature is created.
}}

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

{{LuaCallin
|name = FeatureDestroyed
|args = featureID, allyTeamID
|info = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|args = ???
|info = ???
}}

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

{{LuaCallin
|name = ProjectileCreated
|args = proID, proOwnerID, weaponDefID
|info = Called when the projectile is created. Note that {{var|weaponDefID}} is missing if the projectile is spawned as part of a burst, but [[Lua_SyncedRead#Projectiles|Spring.GetProjectileDefID]] and [[Lua_SyncedRead#Projectiles|Spring.GetProjectileName]] still work in callin scope using {{var|proID}}.
}}

{{LuaCallin
|name = ProjectileDestroyed
|args = proID
|info = Called when the projectile is destroyed.
}}

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

{{LuaCallin
|name = AllowCommand
|args = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced
|return = {{type|bool}} allow
|info = Called when the command is given, before the unit's queue is altered. The return value is whether it should be let into the queue. The queue remains untouched when a command is blocked, whether it would be queued or replace the queue.
}}

{{LuaCallin
|name = AllowUnitCreation
|args = unitDefID, builderID, builderTeam, x, y, z, facing
|return = {{type|bool}} allow
|info = Called just before unit is created, the boolean return value determines whether or not the creation is permitted.
}}

{{LuaCallin
|name = AllowUnitTransfer
|args = unitID, unitDefID, oldTeam, newTeam, capture
|return = {{type|bool}} allow
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowUnitBuildStep
|args = builderID, builderTeam, unitID, unitDefID, part
|return = {{type|bool}} allow
|info = Called just before a unit progresses its build percentage, the boolean return value determines whether or not the build makes progress.
}}

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

{{LuaCallin
|name = AllowFeatureBuildStep
|args = builderID, builderTeam, featureID, featureDefID, part
|return = {{type|bool}} allow
|info = Called just before a feature progresses its build percentage, the boolean return value determines whether or not the progress change is permitted.
}}

{{LuaCallin
|name = AllowResourceLevel
|args = teamID, res, level
|return = {{type|bool}} allow
|info = Called when a team sets the sharing level of a resource, the boolean return value determines whether or not the sharing level is permitted.
}}

{{LuaCallin
|name = AllowResourceTransfer
|args = oldTeamID, newTeamID, res, amount
|return = {{type|bool}} allow
|info = Called just before resources are transferred between players, the boolean return value determines whether or not the transfer is permitted.
}}

{{LuaCallin
|name = AllowStartPosition
|args = playerID, teamID, readyState, clampedX, clampedY, clampedZ, rawX, rawY, rawZ
|return = {{type|bool}} allow
|info = {{var|clamped{X,Y,Z}}} are the coordinates clamped into start-boxes, {{var|raw}} is where player tried to place their marker. The {{var|readyState}} can be any one of
* {{value|0}} - player picked a position,
* {{value|1}} - player clicked ready,
* {{value|2}} - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* {{value|3}} - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or (0,0,0) if they do not have a startbox.
NB: The order of the parameters changed with the addition of {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

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

{{LuaCallin
|name = AllowWeaponTargetCheck
|args = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = {{type|bool}} allowCheck, {{type|bool}} ignoreCheck
|info = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag. The {{var|ignoreCheck}} return value was added in 99.0 to allow ignoring the callin i.e. running normal engine check for this weapon.
}}

{{LuaCallin
|name = AllowWeaponTarget
|args = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = {{type|bool}} allowed, {{type|number}} newPriority
|info = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value is the new priority for this target (if you don't want to change it, return {{var|defPriority}}). Lower priority targets are targeted first.
}}

{{LuaCallin
|name = AllowWeaponInterceptTarget
|args = interceptorUnitID, interceptorWeaponID, targetProjectileID
|return = {{type|bool}} allowed
|info = Controls blocking of a specific intercept target from being considered during an {{xtaglink|Gamedev:WeaponDefs|interceptor}} weapon's periodic auto-targeting sweep. Only called for {{var|weaponDefIDs}} registered via [[Lua_System#Synced|Script.SetWatchWeapon]].
}}

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

{{LuaCallin
|name = Explosion
|args = weaponDefID, px, py, pz, AttackerID, ProjectileID
|return = {{type|bool}} noGfx
|info = Called when an explosion occurs. If it returns {{value|true}} then no graphical effects are drawn by the engine for this explosion.
}}

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

{{LuaCallin
|name = MoveCtrlNotify
|args = unitID, unitDefID, unitTeam, data
|return = {{type|bool}} moveCtrlComplete
|info = Enable both [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetCollideStop]] and [[Lua_MoveCtrl#Options|Spring.MoveCtrl.SetTrackGround]] to enable this call-in, data was supposed to indicate the type of notification but currently never has a value other than {{value|1}} ("unit hit the ground"). The return value determines whether or not the unit should remain script-controlled ({{value|false}}) or return to engine controlled movement ({{value|true}}).
}}

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

{{LuaCallin
|name = Load
|args = zip
|info = Called after {{name|GamePreload}} and before {{name|GameStart}}. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

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

{{LuaCallin
|name = UnitPreDamaged
|args = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the unit, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

{{LuaCallin
|name = ShieldPreDamaged
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|return = {{type|bool}} handleCollision
|info = Called before any engine shield-vs-projectile logic executes. If the return value is {{value|true}} the gadget handles the collision event and the engine does not remove the projectile. If the weapon is a hitscan type ([[Gamedev:WeaponDefs#Tag:weaponType|BeamLaser]] or [[Gamedev:WeaponDefs#Tag:weaponType|LightningCanon]]) then {{var|proID}} is {{value|nil}} and {{var|beamEmitterWeaponNum}} and {{var|beamEmitterUnitID}} are populated instead. The start and hit position arguments are provided from 104.0 onwards.
}}

{{LuaCallin
|name = FeaturePreDamaged
|args = featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = {{type|number}} newDamage, {{type|number}} impulseMult
|info = Called before damage is applied to the feature, allows fine control over how much damage and [http://en.wikipedia.org/wiki/Impulse_(physics) impulse] is applied.
}}

[[Category: Lua]]

User:Jivvz

2018-03-23T20:00:42Z

Jivvz: Blanked the page

User:Jivvz

2018-03-23T19:58:52Z

Jivvz: Created page with "aka his_face"

aka his_face

RapidTools

2017-03-04T20:18:56Z

Jivvz: /* Compile */

RapidTools are for managing a [[rapid]] game/archive repository.

Made by det

=Source=
https://github.com/spring/RapidTools

=Bugs=
https://github.com/spring/RapidTools/issues

=Compile=
to compile it on ubuntu:
<code><pre>
git clone https://github.com/spring/RapidTools.git --recursive
sudo apt-get install liblua5.1-0-dev libzip-dev zlib1g-dev cmake libssl-dev
cmake .
make
</pre></code>

=Tool description=
==AddZip==

takes a .zip and adds it to the repo with user specified tags:

Usage:
<code><pre>
AddZip <Store Path> <Zip Path> [Tag1] ...
</pre></code>

==BuildGit==

adds a git path to the repo and generates the tags automatically from the commit message, it also optimizes for incremental updates

Usage:
<code><pre>
BuildGit <Git Path> <Mod Root> <Modinfo> <Store Path> <Git Hash> <Prefix>
</pre></code>

==Streamer==

is a cgi program to serve some specific files of a .sdp. This is the fastest and official way to fetch a rapid archive.

at client side you have to http POST:
http://packages.springrts.com/streamer.cgi?<hash of sdp>

post data is binary 0/1 if a file of the specified sdp is needed or not.

streamer.cgi then returns all files in a single stream in the same order than in the sdp. it has to be in the root of a [[rapid]] file structure.

<code><pre>
Usage: ./Streamer
Expects environment variables DOCUMENT_ROOT and QUERY_STRING
Expects a gziped bitarray as stdin
</pre></code>

for details see the source-code:
https://github.com/spring/RapidTools/blob/master/Tools/Streamer.cpp#L68

==MakeZip==

can create a zip from a .sdp

<code><pre>
MakeZip ~/.spring ba:stable ba.zip
</pre></code>

===Notes===

If you get this error:
<code><pre>
Error on unknown tag lookup
</pre></code>

MakeZip doesn't find the tag specified in (for example) ~/.spring/versions.gz. To fix, copy the required versions.gz:

<code><pre>
cp ~/.spring/rapid/packages.springrts.com/versions.gz ~/.spring/
</pre></code>

[[Category: Download Systems]]

Rapid

2017-02-21T08:40:23Z

Jivvz: /* creating a release */

"Rapid" is a concept for storing "archives" for spring. It consists of multiple indexes:

* index of all known rapid repos: http://repos.springrts.com/repos.gz
* index of all known archives in a repo: http://packages.springrts.com/versions.gz, http://zk.repo.springrts.com/versions.gz, ...
* index of a single game/map/content archive: .sdp which lists all files inside the "pool" directory

spring can directly read .sdp and the pool directory which contains the real files of an archive. multiple .sdp can share the same files in a pool which makes "rapid" so efficient in storage.

Serverside [[RapidTools]] are used to manage the repository of all games.

=Using rapid as Gamedev=
If a Gamedev wants to use rapid, he needs to use a git repository for his game where the game archive is in the .sdd format stored:

The git repository needs to contains a folder which is in the structre of a .sdd. in modinfo.lua version has to be
<code><pre>
version = '$VERSION',
</pre></code>
$VERSION later on will be replaced by the git commit number or, when a release is made, the version number of the release.

==Creating a release==
When the git repository is connected to rapid, a release can be made by making a git-commit with a commit message in the format:
<code><pre>
VERSION{x.xx}
</pre></code>

Where everything in the brackets will replace $VERSION in modinfo.lua.

This will create a tag :stable for this commit and create an archive at http://''gamename''.repo.springrts.com/builds/, i.e. http://i18n.repo.springrts.com/builds/ which can be distributed/uploaded to different sites if needed.
It is also automatically published to upq at http://api.springfiles.com/ which all current download systems have access to; you can validate what happened there, too.

===Adding your game to the rapid download system===
Please create a new issue at https://github.com/spring/RapidTools/issues and report the location of your git repository and the wanted rapid tag.

To download you can use one of the [[Rapid_Tags]].

=Files structures=

file structure of rapid is:

<code><pre>
/versions.gz
/repos.gz
/packages/
/pool/
</pre></code>

==list of rapid repositories: repos.gz==
gziped text file which has a list of all rapid repositories.

<code><pre>
main,http://packages.springrts.com,,
</pre></code>

for springrts it is:
http://repos.springrts.com/repos.gz

==list of archives on a mirror: versions.gz==
gziped text file which has a list of all sdp archives in this repository.
<code>
<pre>
ba-tronic:version:7.12-tronic1,baafb4fb215c60873e7d10e7ec600dc5,Balanced Annihilation V7.12,Balanced Annihilation V7.12-tronic1
</pre>
</code>

the md5 hash is the filename of the sdp of the archive. so for example:

http://packages.springrts.com/packages/baafb4fb215c60873e7d10e7ec600dc5.sdp

==folder with index archives: /packages/==
this folder contains all available packages (~games) in the rapid file structure.

==an index archive: .sdp==
gziped index file with a list of all files in this archive. this is for example a game.

Format of the .sdp (index) files:
* There is one entry per indexed file. These are repeated until EOF.
* The format of one such entry:
** 1 byte real file name length
** real file name
** 16 byte MD5 digest
** 4 byte CRC32
** 4 byte file size
* The 16 bytes MD5 digest is the reference to the 32 Hex char file name
* under pool, which contains the content.

filename of the .sdp is:

md5(md5(filename1) + md5(content of file1) + md5(filename2) + md5(content of file2) ...)

see also void PoolArchiveT::load(DigestT const & Digest):

https://github.com/spring/RapidTools/blob/master/Rapid/PoolArchive.cpp#L35

or

https://github.com/spring/spring/blob/master/rts/System/FileSystem/Archives/PoolArchive.h

==the pool folder==
this folder contains all files referenced by the .sdp's in gzipped form. the filename is the md5 of the file. this way files which are used by multiple archives can be shared.

The pool system uses two directories, to be found in the root of a spring
data directory, pool and packages. They may look as follows:
<code><pre>
/pool/00/00756ec29fe8fc9d3da9b711e76bc9.gz
/pool/00/3427d26f419dabe74eaf7b865407b8.gz
...
/pool/01/
/pool/02/
...
/pool/ff/
</pre></code>

basicly its in this form:

<code><pre>
/pool/<first 2 hex chars>/<last 30 hex chars>.gz
</pre></code>

The splitting up into the 00 till ff sub-dirs is only to prevent possible
problems with file-system limits for maximum files per directory (eg. FAT32).

[[Category: Download Systems]]

RapidTools

2017-02-20T21:39:35Z

Jivvz: /* Compile */

RapidTools are for managing a [[rapid]] game/archive repository.

Made by det

=Source=
https://github.com/spring/RapidTools

=Bugs=
https://github.com/spring/RapidTools/issues

=Compile=
to compile it on ubuntu:
<code><pre>
git clone https://github.com/spring/RapidTools.git --recursive
sudo apt-get install liblua5.1-0-dev libzip-dev zlib1g-dev cmake
cmake .
make
</pre></code>

=Tool description=
==AddZip==

takes a .zip and adds it to the repo with user specified tags:

Usage:
<code><pre>
AddZip <Store Path> <Zip Path> [Tag1] ...
</pre></code>

==BuildGit==

adds a git path to the repo and generates the tags automatically from the commit message, it also optimizes for incremental updates

Usage:
<code><pre>
BuildGit <Git Path> <Mod Root> <Modinfo> <Store Path> <Git Hash> <Prefix>
</pre></code>

==Streamer==

is a cgi program to serve some specific files of a .sdp. This is the fastest and official way to fetch a rapid archive.

at client side you have to http POST:
http://packages.springrts.com/streamer.cgi?<hash of sdp>

post data is binary 0/1 if a file of the specified sdp is needed or not.

streamer.cgi then returns all files in a single stream in the same order than in the sdp. it has to be in the root of a [[rapid]] file structure.

<code><pre>
Usage: ./Streamer
Expects environment variables DOCUMENT_ROOT and QUERY_STRING
Expects a gziped bitarray as stdin
</pre></code>

for details see the source-code:
https://github.com/spring/RapidTools/blob/master/Tools/Streamer.cpp#L68

==MakeZip==

can create a zip from a .sdp

<code><pre>
MakeZip ~/.spring ba:stable ba.zip
</pre></code>

===Notes===

If you get this error:
<code><pre>
Error on unknown tag lookup
</pre></code>

MakeZip doesn't find the tag specified in (for example) ~/.spring/versions.gz. To fix, copy the required versions.gz:

<code><pre>
cp ~/.spring/rapid/packages.springrts.com/versions.gz ~/.spring/
</pre></code>

[[Category: Download Systems]]

RapidTools

2017-02-20T21:34:43Z

Jivvz: /* Compile */

RapidTools are for managing a [[rapid]] game/archive repository.

Made by det

=Source=
https://github.com/spring/RapidTools

=Bugs=
https://github.com/spring/RapidTools/issues

=Compile=
to compile it on ubuntu:
<code><pre>
git clone https://github.com/spring/RapidTools.git
sudo apt-get install liblua5.1-0-dev libzip-dev zlib1g-dev cmake
cmake .
make
</pre></code>

=Tool description=
==AddZip==

takes a .zip and adds it to the repo with user specified tags:

Usage:
<code><pre>
AddZip <Store Path> <Zip Path> [Tag1] ...
</pre></code>

==BuildGit==

adds a git path to the repo and generates the tags automatically from the commit message, it also optimizes for incremental updates

Usage:
<code><pre>
BuildGit <Git Path> <Mod Root> <Modinfo> <Store Path> <Git Hash> <Prefix>
</pre></code>

==Streamer==

is a cgi program to serve some specific files of a .sdp. This is the fastest and official way to fetch a rapid archive.

at client side you have to http POST:
http://packages.springrts.com/streamer.cgi?<hash of sdp>

post data is binary 0/1 if a file of the specified sdp is needed or not.

streamer.cgi then returns all files in a single stream in the same order than in the sdp. it has to be in the root of a [[rapid]] file structure.

<code><pre>
Usage: ./Streamer
Expects environment variables DOCUMENT_ROOT and QUERY_STRING
Expects a gziped bitarray as stdin
</pre></code>

for details see the source-code:
https://github.com/spring/RapidTools/blob/master/Tools/Streamer.cpp#L68

==MakeZip==

can create a zip from a .sdp

<code><pre>
MakeZip ~/.spring ba:stable ba.zip
</pre></code>

===Notes===

If you get this error:
<code><pre>
Error on unknown tag lookup
</pre></code>

MakeZip doesn't find the tag specified in (for example) ~/.spring/versions.gz. To fix, copy the required versions.gz:

<code><pre>
cp ~/.spring/rapid/packages.springrts.com/versions.gz ~/.spring/
</pre></code>

[[Category: Download Systems]]

Gamedev:UnitDefs

2017-02-08T22:19:16Z

Jivvz: character case

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

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

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

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = maxRepairSpeed
|type = float
|default = 1e20
|description = The maximum cumulative speed at which this unit can be repaired.}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = fireState
|type = int
|default = -1 for units with {{taglink|noAutoFire|false}}, 2 otherwise
|description = The initial firing state for the unit. Can be <code>-1</code> - Inherits from factory, <code>0</code> - Hold Fire, <code>1</code> - Return Fire or <code>2</code> - Fire At Will.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = frontToSpeed
|type = float
|default = 0.1
|description = Fudge factor for lining up speed and front of plane.
}}

{{tag
|name = speedToFront
|type = float
|default = 0.07
|description = Fudge factor for lining up speed and front of plane.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

===Collision Volumes===
For a deeper explanation of these tags, see [[Gamedev:CollisionVolumes]]. Note that all collision checks first do a pre-check with the unit ''radius'' before doing the colvol checks. Ergo the unit ''radius'' must be larger or equal to the colvol!
{{tag
|name = modelCenterOffset
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = Removed in 89.0 (Now set via lua)
|description = How far from the model's defined centre should the centre of the unit be?}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Sub Tables==

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

The following additional tags are associated with this subtable:

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

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

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

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

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

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

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

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

There are no additional tags specific to this subtable.

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

====explosionGenerators====

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

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

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

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

===sounds===

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

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

Sounds can be defined in one of three ways:

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

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

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

====sounds Example====

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

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

====sounds Events====

The events called by the engine are as follows:

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

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

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

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

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

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

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

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

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

There are no additional tags specific to this subtable

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

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

[[Category: Game Dev]]

Map development

2009-07-09T08:49:05Z

Jivvz: there -> their

=Map making SM3=

SM3 (Spring Mapformat 3) is getting allong nicely and maps using this format can be made. The following is documented so far.

*[[SM3_Map_Format|jcnossen's brief description on how this mapformat works.]]
*[[SM3_FAQ|The first FAQ for the new mapformat.]]

[[Image:sm3-minimap-thumb.jpg]]

'''''NOTE:''''' SM3 format is broken at the moment, do not use it. It only renders at all if sm3 shaders are disabled in springsettings, and even then with very low fps. Software rendering is corrupted on nvidia cards, but not on ati.

=Map making, SMF=
Maps, are a complex mixture of heightmaps and textures.
Fortunately, there are several people who share their knowledge with us.
Their few tutorials will make your life as mapper a lot better.

=Skyboxes=
*[[Skyboxcreation|Notes about skyboxes]] notes on a prerendered sky box or cube map.

== Full Guides For Map Making ==

*[[Create_maps|aGorm's map creating Guide]]
*[[Map_Making_Guide|aGorms Ultimate Map Making Guide(unfinished)]]
*[[IceXuick_Map_Design_Help|IceXuicks Map creating Guide]]
*[http://taspring.clan-sy.com/phpbb/viewtopic.php?t=3941 Forboding Angel's map creating Tutorial]
*[[Maps:Tutorial|Another tutorial from a designing point of view]]
*[[A_Complete_Map_Making_Tutorial|A Complete Map Making Tutorial (under construction)]]
*[[Runecrafter|Runecrafter's Map Tutorial]]
*[http://modinfo.adune.nl/map_making_guide.php Simple map making guide]

== Specific Guides ==

*[[Quanto_OTAMAP_Guide|Quanto's Guide to OTA Porting and Small Maps]]
*[[Maps:SMD|Everything about .SMD]]
*[[Maps:Compiling|Everything about Compiling your map]]
*[[MapsBalance|Some things about map balance]]
*[[MapSizes|Map sizes in pixels]] and memory information about map sizes
*[[Height Map Tutorial|RogerN's height map tutorial]]
*[[Create_map_texture_with_povray|Basic howto: create map texture with Povray]]

Features. Stones, rocks, trees, for your map can be found in [http://taspring.clan-sy.com/phpbb/viewtopic.php?t=4047 This thread] 

== Tools ==

*[http://taspring.clan-sy.com/phpbb/viewtopic.php?t=2420 Maelstrom's SMD Generator]
*[http://www.fileuniverse.com/?p=show&a=it&id=1507 Mother's Mapconv]
*[http://user.supradigital.org/jcnossen/FeaturePlacer.zip Jnossen's SM3 feature placer]
*[[Maps:Map Designer]] Hugh's 3D map designer. Splatting, heightmap editing, splat painting, SM3
*[http://modinfo.unknown-files.net/coord/mapcoords.php Online starting position creator(dead link)]
: You can always find out which x/y coordinates are good while starting spring and having a look at the mouse cursor coordinates.
*[[http://springrts.com/phpbb/viewtopic.php?f=13&t=16341]] Frostregen's SpringMapEdit. 3D editing, Compiles SM2 directly. Beginner friendly but still powerful.

== Mappers Clan ==
[[Map Making Guild]]: That weird fish aGorm set up a clan for poor mappers that can't get into a clan on there gaming merit... (Mainly for himself therefor...)

== Reference and FAQs ==

* [[Maps:Noob Mistakes]]
* [[Water Height: Mapconv vs. Heightmap]]

----
TIPS:

A useful tip, on almost every map in a 1v1 you will start opposite your opponent unless you choose your position. this is because random order simply randomly distributes players at the default start points which in almost every map are opposite each other. One exception that I know of is flooded desert where you both start on the left hand island.
----
Make sure that your map's ideas and game-play is sound before you release it for good. Do a lot of beta testing and learn about good level design! You can learn about what makes a good map by playing on good maps, so play often and map well. -url00
----

''' [[Main_Page|<- Back to Main page]]'''

[[Category:Map development]]