Spring - User contributions [en]

Mapdev:Tutorial Finalizing

2021-01-10T16:33:07Z

Gajop: /* Compiling the smf and smt files */

= Finalizing =
This page describes how to compile some of the texture files into the smf smt files, test your map, archive the map using 7zip and upload to springfiles.com

= Review =
Following stage one of the beginners tutorial you will have some intermediary files ready to convert into the SMF and SMT map format:
* heightmap.png
* metalmap.png
* diffuse.png
* mini.bmp
* grassmap.png

There is also the [[Mapdev:terraintype|terrain type]] map but thats not covered in these tutorials

= Compiling the smf and smt files =
{| class="wikitable"
! springMapConvNG (Windows/Linux)
| <ol>
<li>Open up the terminal and navigate to your working directory
<li>Generate the mymapname.smf and mymapname.smt files by runing mapconv with these options:
<pre>springMapConvNG -t diffuse.png -h heightmap.png -m metalmap.png
-v grassmap.png -minimap mini.bmp -ct 1 -o mymapname</pre>
<li>Copy the smf and smt files to the ./mymapname.sdd/maps/ directory (Do not rename!)
</ol>
|-
! smf_tools (Windows/Linux)
| <ol>
<li>Open up the terminal and navigate to your working directory
<li>Generate the mymapname.smt and mymapname.smt.csv (tilemap) with this command:
<pre>smt_convert -vf --smt -o mymapname.smt --tilesize 32x32 diffuse.png</pre>
<li>Generate the mymapname.smf file with this command:
<pre>smf_cc -vf --height height.png --metal metal.png --map mymapname.smt.csv --grassmap grassmap.png --minimap minimap.png mymapname.smt</pre>
<li>Copy the smf and smt files to the ./mymapname.sdd/maps/ directory (Do not rename!)
</ol>
|-
! MapConv (Windows)
| <ol>
<li>In mapconv directory: right click, new file, mymapname.bat
<li>Edit in text editor, put in these options:
<pre>MapConv -i -c 0 -x 256 -n 10 -o mymapname.smf -t diffuse.png -a
heightmap.png -m metalmap.png -v grassmap.png</pre>
<li>Depending on the desired quality add:
<pre>Fastest compile, lowest quality:

-z "nvdxt.exe -dxt1a -nmips 4 -quick -file"

Medium speed, good quality: (CUDA version, requires nvidia 8 or higher series gfx card)

-q

Slow, great quality: (Nothing)

Slower, best possible quality:

-z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file"</pre>

<li>Make sure mini.bmp is in the same directory as the mymapname.bat
<li>Generate the mymapname.smf and mymapname.smt files by executing mymapname.bat file
<li>Copy the smf and smt files to the ./mymapname.sdd/maps/ directory (Do not rename!)
</ol>
|-
! Mac
|{{FIXME}}
|}

= Testing the map =
Copying the sdd directory to your spring maps folder will allow spring to recognise it as a map, this way you can tweak parameters and test things before archiving it for distribution.

= Archiving =
Archiving the map creates a single file with smaller overall size for easy distribution.
<ol>
<li>Create a new 7zip archive containing the contents of the sdd folder.(see below for platform specific instructions)
<li>Copy the archive to maps folder to test
</ol>
{{Caution|Make sure that you have not created the archive with the "solid archive" option, or spring will not recognise it.}}
{| class="wikitable" width="100%"
! Linux
|
# Open a terminal and navigate to your sdd directory
# Run the following command:
: <code>7z a -ms=off mymapname.sd7 *</code>
|-
!Windows
|[[File:Examplearchivewith7zip.jpg|512px]]
|-
!Mac
|{{FIXME}}
|}

= Uploading to springfiles.com =
<ol>
<li>Head on over to [http://www.springfiles.com springfiles.com] and create an account
<li>Select upload from the main horizontal menu
<li>Fill out as much as you can
<li>Post to [http://springrts.com/phpbb/viewforum.php?f=13 map creation] subforum with something like "[new map]" in the subject line so as to increase visibiity.
</ol>
= Congratulations =
Your map is set free into the wilds of the internet. We sincerely hope its well loved.

Please browse the [[Mapdev:Main|Map Development]] wiki pages for more ways to make awesome maps. Please help us make this wiki as comprehensive as possible, if you see something missing don't hesitate to jump in and add it.

Additionally, now you have gotten into maps, perhaps other areas of spring development may interest you. Check out the [[Game_and_Unit_development|Game development]] pages.

For help and discussions please visit the [http://springrts.com/phpbb/viewforum.php?f=13 forums]

Good Luck.

[[Category:Map Dev]]

Spring on ARM

2020-09-20T12:06:39Z

Gajop:

'''Note: currently it doesn't compile at many places. some of them can maybe fixed by changing compiler flags. Also the emulation is horrible slow, so better get a real arm computer.
'''

==Setting up a virtualized environment for arm on ubuntu==

see https://wiki.ubuntu.com/ARM/RootfsFromScratch
<pre>
sudo apt-get install qemu-system rootstock
sudo rootstock \
--fqdn ubuntu \
--login ubuntu \
--password ubuntu \
--imagesize 3G \
--seed openssh-server,linux-image-omap \
--notarball

mv qemu-armel-*.img qemu-armel.img
mkdir tmp
sudo mount -o loop qemu-armel.img tmp
echo "auto eth0
iface eth0 inet dhcp" >> tmp/etc/network/interfaces
sudo umount tmp
rmdir tmp
wget http://ports.ubuntu.com/ubuntu-ports/dists/lucid/main/installer-armel/current/images/versatile/netboot/vmlinuz
</pre>

start with:
<pre>
qemu-system-arm -M versatilepb -cpu cortex-a8 -kernel ./vmlinuz \
-hda qemu-armel.img -m 256 -append "root=/dev/sda" \
-net nic -net user,hostfwd=tcp::2222-:22
</pre>

login with ubuntu:ubuntu

or with
<pre>
ssh ubuntu@localhost -p 22222
</pre>

==install required build tools==

<pre>
sudo apt-get install build-essentials cmake
sudo apt-get install libglew1.6-dev libsdl1.2-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread1.46-dev libboost-regex1.46-dev libboost-system1.46-dev \
libboost-program-options1.46-dev libboost-signals1.46-dev
</pre>

since here it should be possible to follow the [[Building_Spring_on_Linux#Ubuntu|linux build instructions]].

[[Category:Engine Dev]]

Mapdev:metal

2020-09-16T14:08:41Z

Gajop: /* mapinfo.lua */

= Metal =
Metal maps are used for the built in resourcing scheme (Metal/Energy), they define metal areas on a battlefield based upon the values in the red channel of the metal map.

{{Caution|There are several games for Spring which use their own resourcing system. If you are creating a map for one of those games a metal map may not be necessary, however it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.}}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-metal.png|256px]] || [[File:Mapdev-metal-example.png]]
|-
! Example Metal Map !! Ingame Result
|}</center>

= Specification =
== mapinfo.lua ==
* [[Mapdev:mapinfo.lua|mapinfo.lua]]
<pre>mapinfo ={
...
maxMetal = 0.02,
extractorRadius = 500.0,
autoShowMetal = true,
...
smf = {
....
metalmapTex = "",
....
},
...
}</pre>

== Image File ==
* The red value of pixel corresponds to the metal value.
{| class="wikitable" width="100%"
! width="15%" | File Location
| The metal map is an intermediary file compiled into the SMF file using [[MapConv]] or [[MapConvNG]], it can also be specified in the mapinfo.lua.
|-
! File Format
| Any that the Mapconv programs support
|-
! Colour Depth
| 8bpp
|-
! Channels
| Greyscale
|-
! Resolution
| <center>
{| class="wikitable" style="text-align: center;"
!Spring Map Size*
!pixels = Spring Map Size * 32
|-
| 2
| 64
|-
| 4
| 128
|-
| 6
| 256
|-
| ...
| ...
|-
| 32
| 1024
|-
| style="text-align: left;font-style:italic" colspan=2 | * must be multiples of 2
|}</center>
|}

= Additional Information =
== Patch Technique ==
If you do want perfect metal patches, use a 6x6 pixel pencil in your image editor with a red value of 255. This combined with setting the "MaxMetal" tag in the definitions to 1, will result in a perfect 2.0 metal generation per patch (using Balanaced Annihilation values). The game use isn't the point however. The fact is that if you can predict how much each spot will output (typically), using the "MaxMetal" parameter, you can easily scale the values up and down. As an example of another extreme, Evolution RTS dictates that all metal patches will output 0.5 metal regardless of the map settings. So whether you need to put a lot of thought into your metal map values depends entirely upon the game for which you are creating the map.

[[Category:Map Dev]]

Mapdev:water

2020-05-13T16:35:34Z

Gajop:

= Water =
The 'water' engine feature can be used for more than just water, it can be Lava, Slime, and completely invisible for maps in space.

Water is always at zero elevation, the terrain is positioned above and below the water using the <code>minHeight</code> and <code>maxHeight</code> values(see [[Mapdev:height]]).

Shading of the water is split into two parts; the surface of the water and the surface of the ground under the water

Water has five different rendering modes which can be set ingame by the command:
<pre>/water</pre>
<ol start=0>
<li> basic
<li> reflective
<li> dynamic
<li> reflective&refractive
<li> bumpmapped
</ol>

The relevant soure code [https://github.com/spring/spring/tree/bfc21aada48a6a606b039819ba55017fe3d4f29d/rts/Rendering/Env files]

= Specifications =
Now because of the various graphical modes, and some options being shared, I've split this into sections.

==Data Types==
{{DataTypes}}

== Options that are always relevant ==
<pre>local mapinfo = {
...
tidalStrength = 0,
voidWater = false,
...
water = {
damage = 0.0,

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

forceRendering = false,

planeColor = {0.0, 0.4, 0.0},
},
...
}</pre>

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

{{tag|name=voidWater|default=false|type=bool|description=If true, the water will not be drawn. Also the terrain under the water will not be drawn.}}

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

{{tag|name=absorb|type=float3|description=Used to calculate the colour of the terrain under the water, see below.}}

{{tag|name=baseCcolor|type=float3|description=Used to calculate the colour of the terrain under the water, see below.}}

{{tag|name=minColor|type=float3|description=Used to calculate the colour of the terrain under the water, see below.}}

The absorb, baseColor and minColor variables are used to alter the colour of the terrain under the water as defined in a glsl shader, see [https://github.com/spring/spring/blob/a71c17d710cc387c484e876971881837ecb0ff10/cont/base/springcontent/shaders/GLSL/SMFFragProg.glsl line 163].

{{tag|name=forceRendering|default=false|type=bool|description=If false, and the minimum height of the terrain is above 1.0, then the water will not be drawn.}}

{{tag|name=planeColor|default={0.0, 0.4, 0.0}|type=float3|description=sets the colour of the horizon water plane, to prevent it from being drawn at all you must comment out this line.}}

== Basic ==
<center>
{| class="wikitable"
|+ Example
| [[File:Water basic example.jpg|400px]]
|}</center>
<pre>local mapinfo = {
...
water = {
repeatX = 0.0,
repeatY = 0.0,

--texture = "",
},
...
}</pre>

{{tag|name=repeatX|type=float|default=0|description=control the texture repetition}}

{{tag|name=repeatY|type=float|default=0|description=control the texture repetition}}

{{tag|name=texture|type=string|default=0|description=the texture image to use, searches the ./maps/ directory of the map archive.}}

== Reflective ==
<center>
{| class="wikitable"
|+ Example
| {{FIXME}}need to place an image here
|}</center>
<pre>local mapinfo = {
...
water = {
surfaceColor = {0.75, 0.8, 0.85},
},
...
}</pre>

{{FIXME}}?

{{tag|name=surfaceColor|type=float3f|default={0.0, 0.0, 0.0}|description=Effects the reflected colour.}}

== Dynamic ==
<center>
{| class="wikitable"
|+ Example
| [[file:water_dynamic_example.jpg|400px]]
|}</center>
<pre>local mapinfo = {
...
water = {
surfaceColor = {0.75, 0.8, 0.85},
--foamTexture = "",
},
...
}</pre>

{{tag|name=surfaceColor|type=float3f|default={0.0, 0.0, 0.0}|description=Effects the reflected colour.}}

{{FIXME}}?

== Reflective and Refractive ==
From what i can tell, this mode is basically the same as the reflective mode, except that it distorts(refracts the light) of objects under the surface.
<center>
{| class="wikitable"
|+ Example
| [[file:water_refractive_example.jpg|400px]]
|}</center>
<pre>local mapinfo = {
...
water = {
surfaceColor = {0.75, 0.8, 0.85},
},
...
}</pre>

{{tag|name=surfaceColor|type=float3f|default={0.0, 0.0, 0.0}|description=Effects the reflected colour.}}

== Bump Mapped ==
<center>
{| class="wikitable"
|+ Example
| {{FIXME}}need to place an image here
|}</center>
<pre>local mapinfo = {
...
water = {
ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.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,

--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},
numTiles = 1,
hasWaterPlane = true,

},
...
}</pre>

{{FIXME}}?

= Forum Discussions =
* [http://springrts.com/phpbb/viewtopic.php?f=13&t=28264 chockolate rain] map discussion apparrently has soemthing in it i wanted to keep for later.. cant remember though...
* [[Water_Height:_Mapconv_vs._Heightmap|water height]]

[[Category:Map Dev]]

Mapdev:grass

2020-05-06T04:03:04Z

Gajop: /* mapinfo.lua */

= Grass =
Grass is entirely optional, but can be customized via map parameters and adds a nice touch to your map.
{| class="wikitable" style="text-align: center;" width="100%"
| [[File:Mapdev-grass.png]] || [[File:Mapdev-grass-example.png|451px]]
|-
! Example Grass Disribution
! In Game Result
|}

= Specification =
== mapinfo.lua ==
<pre>local mapinfo = {
...
smf = {
....
grassmapTex = "",
....
},
...
resources = {
...
grassBladeTex = "",
grassShadingTex = "",
...
},
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
},
...
}</pre>
=== Blade Wave Scale ===
Defaults to 1. It specifies how much the blades will wave in the wind. Higher makes them wave more.

=== Blade Height ===
Default is 4. Defines the length of the blade of grass in elmos.

=== Blade Angle ===
Default is pi/4. It defines how much each blade of grass curves.

=== Blade Color ===
does nothing when blade texture is set.

== Distribution Image ==
Formerly [[Mapdev:features|Feature]] Map. Grass distribution is defined by blue pixels, the more blue the pixel is (the closer to blue 255 it is), the thicker grass will be at that location.
{| class="wikitable" width="100%"
! width="15%" | File Location
| The distribution map is an intermediary file compiled into the SMF/SMT files using [[MapConv]] or [[MapConvNG]], it can also be specified in the mapinfo.lua
|-
! File Format
| Any that Mapconv programs support
|-
! Colour Depth
| 8bpp
|-
! Channels
| Greyscale
|-
! Resolution
| <center>
{| class="wikitable" style="text-align: center;"
!Spring Map Size*
!pixels = Spring Map Size * 16
|-
| 2
| 32
|-
| 4
| 64
|-
| 6
| 96
|-
| ...
| ...
|-
| 32
| 512
|-
| style="text-align: left;font-style:italic" colspan=2 | * must be multiples of 2
|}</center>
|}

== Shading Image ==
* If a shading image is not present, the minimap will be used in its place.
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGB
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain.
|}
<center>
{| class="wikitable"
| [[File:Grassmap_Map_example.jpegâ€Ž]] || [[File:Grassmap_Map_ingame.jpg|512px|â€Ž]]
|-
! Example !! Result
|}</center>

== Blade Texture ==
Specify a texture for the individual grass blades. The grass blades go from top to bottom, vertically.
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGB (alpha does nothing here)
|-
! Resolution
| Any
|}

<center>
{| class="wikitable" style="text-align: center;"
| https://springrts.com/mediawiki/images/3/36/Grass_blade_tex_testing.png || https://springrts.com/mediawiki/images/9/9f/Grass_blade_tex_ingame.PNG
|-
! Example !! Result
|}</center>

= Forum Discussions =
* [http://springrts.com/phpbb/viewtopic.php?f=13&t=27585 Try to keep perspective]

[[Category:Map Dev]]

Mapdev:set.lua

2020-05-06T03:33:48Z

Gajop: /* setcfg */

= set.lua Reference =
This file lists all the units, buildings and features that belong to the gaia team, their locations and orientation.

==Source==
The engine source code which reads this file from the map is viewable here:
* ???
== 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
: ./mapconfig/featureplacer/set.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 =
== setcfg ==
<pre>
----------------------------------------------------------
-- AutoCreated by FeaturePlacer (by smoth)

local setcfg = {
unitlist = {
...
{ name = 'name', x = 0 , z = 0 , rot = "0"},
...
},
buildinglist = {
...
{ name = 'name', x = 0 , z = 0 , rot = "0"},
...
},
objectlist = {
...
{ name = 'name', x = 0 , z = 0 , rot = "0"},
...
},
}
return setcfg</pre>

{{tag|name=name|type=string
|description=name of the unit, feature, or building owned by the gaia team}}

{{tag|name=x|type=integer
|description=x position on the map}}

{{tag|name=z|type=integer
|description=z position on the map}}

{{tag|name=rot|type=string
|description=a number which specifies the rotation of the object}}

[[Category:Map Dev]]

Mapdev:mapinfo.lua

2020-05-06T03:33:04Z

Gajop: remove <code> tags

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

{{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=voidAlphaMin|type=float|default=0.9
|description=Controls what alpha level the transparency trigger.}}.

{{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 ==
<pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre>
{{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 ==
<pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

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

{{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.
<pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre>

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

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

{{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 ==
<pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre>
{{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 ==
<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>

{{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 ==
The shader for grass color at https://github.com/spring/spring/blob/266b51ad4c0301103e269a13f8e72f9c26511b4e/cont/base/springcontent/shaders/GLSL/GrassFragProg.glsl#L48 samples grassBladeTex, and multiplies it with grassShadingTex (which defaults to minimap)

<pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
maxStrawsPerTurf = 150,
},
...
}</pre>
{{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=maxStrawsPerTurf|type=int|default=150
|description=The maximum number of grass blades per 'turf', A turf is approximately 32x32 elmos. }}

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

== Lighting ==
<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>
{{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 ==
<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>
{{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 ==
<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>
Holds an array of start positions

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

[[Category:Map Dev]]

Lua Fonts

2020-04-12T01:00:18Z

Gajop: /* Inlined ColorCodes */

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

=Load/Delete=
'''gl.LoadFont'''
( string fontfilename, number size = 14,
number outlineWidth = 2, number outlineWeight = 15 ) -> userdata font
'''gl.DeleteFont'''
( userdata font ) -> nil

=Userdata Functions=
'''font:Print'''
(string "text", number x, number y [, number size [, string "options"] ] ) -> nil

options are:
horizontal alignment:
'c' = center
'r' = right
vertical alignment:
'a' = ascender (is a font specific value)
't' = top (depends on text)
'v' = vertical center
'x' = baseline
'b' = bottom
'd' = descender
decorations:
'o' = black outline
'O' = white outline
's' = shadow
other:
'n' = don't round vertex coords to nearest integer (font may get blurry)

http://home.arcor.de/jkei/fontlines.png

'''font:SetTextColor'''
( number r, number g, number b [, number a ] ) -> nil
( {r,g,b,a} ) -> nil
'''font:SetOutlineColor'''
( number r, number g, number b [, number a ] ) -> nil
( {r,g,b,a} ) -> nil
'''font:SetAutoOutlineColor'''
( boolean enable ) -> nil

'''font:GetTextWidth'''
(string "text") -> number width (in pixels, with a font size of 1.0)
'''font:GetTextHeight'''
( string "text" ) -> nil | number height, number descender, number numlines
(height & descender in pixels, with a font size of 1.0)
further descriptions here: [[GetTextHeight]]

'''font:WrapText'''
( string "text", number max_width [, number max_height [, number size ] ])
-> nil | string wrappedText, number lines

'''font:BindTexture'''
( ) -> nil

If you have multiple font:Print calls, then you can bunch them between a font:Begin() and font:End() to speedup the rendering. 
'''font:Begin'''
( ) -> nil
'''font:End'''
( ) -> nil

=Userdata Properties (ReadOnly)=
string '''font.path''' 
string '''font.family''' 
string '''font.style''' 
number '''font.size''' 
number '''font.height''' a.k.a. '''font.lineheight''' 
number '''font.descender''' 
number '''font.outlinewidth''' 
number '''font.outlineweight''' 
number '''font.texturewidth''' 
number '''font.textureheight'''

=Inlined ColorCodes=
 Whole Spring FontRendering supports `inlined colorcodes`, there are 2 special chars to indicate those '<code>\255\$r\$g\$b</code>' & '<code>\b</code>':
<pre>
local black = "\255\001\001\001"
local blue = "\255\001\001\255"
local reset = "\b " -- !space after "\b " is necessary if you put it at the end of the string you want to print, otherwise the parsing will break
font:Print(blue .. "bluetext" .. black .. "blacktext" .. reset .. blue .. "bluetext again" .. reset, 0, 0)
</pre>

From 98.0 onwards inlined colorcodes reuse the currently set alpha value.

[[category: Lua]]

Admin:Rapid

2019-07-27T08:00:47Z

Gajop: /* How to add a rapid repository */

==How to add a rapid repository==

<pre>
cd /home/packages/git
git clone git://github.com/ZeroK-RTS/Zero-K.git zk
</pre>
(git:// should be prefered as it uses less resources when its updated)

<pre>
vi forceupdate.sh
</pre>

adjust the line "for REPO in /home/packages/git/zk ;" to the path which was added, run it:
<pre>
./forceupdate.sh
</pre>

this should create the folder /home/packages/www/zk.

then repos.gz must be updated:
<pre>
cd /home/packages/www/repos.springrts.com
./update-repos.py
</pre>

[[Category:Administration]]
[[Category:Download Systems]]

Admin:Rapid

2019-07-27T07:46:47Z

Gajop:

==How to add a rapid repository==

<pre>
cd /home/packages/git
git clone git://github.com/ZeroK-RTS/Zero-K.git zk
</pre>
(git:// should be prefered as it uses less resources when its updated)

<pre>
vi forceupdate.sh
</pre>

adjust the line "for REPO in /home/packages/git/zk ;" to the path which was added, run it:
<pre>
./forceupdate.sh
</pre>

this should create the folder /home/packages/www/zk.

then repos.gz must be updated:
<pre>
/home/packages/www/repos.springrts.com
./update-repos.py
</pre>

[[Category:Administration]]
[[Category:Download Systems]]

Lua VFS

2019-04-21T04:00:11Z

Gajop: Add two additional functions that exist in develop/maintenance branches.

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

= Modes =
'''VFS.RAW'''

'''VFS.MOD''' {{new|104.0}}

'''VFS.MAP''' {{new|104.0}}

'''VFS.BASE''' {{new|104.0}}

'''VFS.MENU''' {{new|104.0}}

'''VFS.ZIP'''

'''VFS.RAW_FIRST'''

'''VFS.ZIP_FIRST'''

'''VFS.RAW_ONLY''' (same as VFS.RAW)

'''VFS.ZIP_ONLY''' (same as VFS.ZIP)

= Files =
'''VFS.Include''' (if enviroment=nil then use current one)
( string "filename" [, table enviroment = nil [, number mode ] ] ) ->
The environment arg sets the global environment (see generic lua refs). In almost all cases, this should be left nil to preserve Springs default.

VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (=location) from which to include files.

'''VFS.LoadFile'''
( string "filename" [, number mode ] ) -> nil | string data
'''VFS.FileExists'''
( string "filename" [, number mode ] ) -> boolean
example usage: if VFS.FileExists("maps/Castles.sdz") then ... end 

'''VFS.DirList'''
( string "directory" [, string "pattern" = "*" [, number mode ] ] )
-> { [1] = string filename, ... }
'''VFS.SubDirs'''
( string "directory", [, string "pattern" = "*" [, number mode ] ] )
-> { [1] = string subdir1, ... }

'''VFS.GetAvailableAIs'''
( [ string gameName] [, string mapName ] )
-> { ai1, ai2, ... }
Gets a list of all Spring AIs. The optional gameName and mapName parameters can be used to include game/map specific LuaAIs in the list.

'''VFS.UseArchive''' unsynced only!
( string "filename" [, number mode ], lua_function [, arg1 [,arg2 ]] )
-> result1,result2,... of the given lua_function
Loads an archive '''temporarely''' in the VFS and then runs the given lua_function, which can make usage of the files in the archive.

'''VFS.MapArchive''' unsynced only!
( string "filename/modname of archive", [string checksum of archive] )
-> bool
Permanently loads an archive into the VFS (to load zipped music collections etc.). Does nothing if the archive is already loaded in the VFS (won't reload even if there are changes made to the archive). If checksum is given it checks if the to be loaded file is correct, if not then it won't load it and return false.

'''VFS.UnmapArchive''' unsynced only! available in 98.0
( string "filename/modname of archive")
-> bool
Removes an already loaded archive (see VFS.MapArchive)

'''VFS.CompressFolder''' unsynced only!
( string "folderPath" [, string "archiveType" ] [, string "compressedFilePath" ] [, bool includeFolder ] [, number mode ] ) -> nil

Compresses the specified folder. archiveType defines the compression type which can currently be only "zip" includeFolder specifies whether the archive should have the specified folder as root (defaults to false) 

'''VFS.GetFileAbsolutePath''' unsynced only! available in 105.0
( string "filename" [, number mode ] ) -> absPath | nil

'''VFS.GetArchiveContainingFile''' unsynced only! available in 105.0
( string "filename" [, number mode ] ) -> archiveNameWithVersion | nil

= Generic hash =
'''VFS.CalculateHash''' {{new|101.0}}
( string input, number hashType)
-> string md5hash

Calculates hash (in base64 form) of a given string (with md5 support initially). Note supplying 0 (MD5) as hashType is mandatory

= Archives =

'''VFS.GetMaps''' {{new|98.0}}
( ) -> {
[1] = string mapName, ...
}

'''VFS.GetGames''' {{new|98.0}}
( ) -> {
[1] = string gameName, ...
}

'''VFS.GetAllArchives''' {{new|98.0}}
( ) -> {
[1] = string archiveName, ...
}

'''VFS.GetLoadedArchives''' {{new|105.0}}
( ) -> {
[1] = string archiveName, ...
}

'''VFS.GetArchivePath''' {{new|105.0}}
( string archiveName ) -> string archivePathOnDisk

'''VFS.GetNameFromRapidTag''' {{new|105.0}}
( string rapidTag ) -> string archiveName

'''VFS.HasArchive''' {{new|98.0}}
( string archiveName ) -> boolean

'''VFS.GetArchiveInfo''' {{new|98.0}}
( string archiveName ) - >
{
name = string,
shortname = string,
version = string,
mutator = string,
game = string,
shortgame = string,
description = string,
mapfile = string,
modtype = number,
}
modtype values:1=primary, 0=hidden, 3=map

'''VFS.GetArchiveChecksum''' {{new|98.0}}
( string archiveName ) -> string singleArchiveChecksum, string completeArchiveChecksum

'''VFS.GetArchiveDependencies''' {{new|98.0}}
( string archiveName ) -> {
[1] = string archiveName, ...
}

'''VFS.GetArchiveReplaces''' {{new|98.0}}
( string archiveName ) -> {
[1] = string archiveName, ...
}

'''VFS.DownloadArchive''' {{new|101.0}}
( name, category ) -> nil

Category must be one of: map, game, engine.

'''VFS.AbortDownload''' {{new|104.0}}
( id ) -> boolean foundAndRemoved

Additional functions are available as part of the [[Lua_UnsyncedCtrl#.28Virtual-.29FileSystem|unsynced ctrl]].

= Packing =
The Pack- and Unpack-functions are used to convert numbers->strings and strings->numbers.
So you can read a binary file and then convert the received strings back to numbers and the other way around. Also you can use it in combination with the SendLuaXYZMsg-functions.

'''VFS.PackU8'''

'''VFS.PackU16'''

'''VFS.PackU32'''

'''VFS.PackS8'''

'''VFS.PackS16'''

'''VFS.PackS32'''

'''VFS.PackF32'''

arguments are:

'''VFS.PackX( number arg1, number arg2, number arg3, ... )''' -> string

'''VFS.PackX( {[1]=number,[2]=number,..} )''' -> string

'''VFS.UnpackU8'''

'''VFS.UnpackU16'''

'''VFS.UnpackU32'''

'''VFS.UnpackS8'''

'''VFS.UnpackS16'''

'''VFS.UnpackS32'''

'''VFS.UnpackF32'''

arguments are:

'''VFS.UnpackX( string "binary" [, number position = 1] [, number count] )'''
-> number | table { [1]=number,[2]=number,.. }

= Zlib =
'''VFS.ZlibCompress''' unsynced only!
( string "uncompressedStr" )
-> nil | string "compressedStr"

'''VFS.ZlibDecompress''' available in synced, too!
( string "compressedStr" [, number uncompressed size = 65500] )
-> nil | string "uncompressedStr"

[[category: Lua]]

Lua VFS

2019-04-05T23:26:09Z

Gajop: /* Files */

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

= Modes =
'''VFS.RAW'''

'''VFS.MOD''' {{new|104.0}}

'''VFS.MAP''' {{new|104.0}}

'''VFS.BASE''' {{new|104.0}}

'''VFS.MENU''' {{new|104.0}}

'''VFS.ZIP'''

'''VFS.RAW_FIRST'''

'''VFS.ZIP_FIRST'''

'''VFS.RAW_ONLY''' (same as VFS.RAW)

'''VFS.ZIP_ONLY''' (same as VFS.ZIP)

= Files =
'''VFS.Include''' (if enviroment=nil then use current one)
( string "filename" [, table enviroment = nil [, number mode ] ] ) ->
The environment arg sets the global environment (see generic lua refs). In almost all cases, this should be left nil to preserve Springs default.

VFS modes are single char strings and can be concatenated; doing specifies an order of preference for the mode (=location) from which to include files.

'''VFS.LoadFile'''
( string "filename" [, number mode ] ) -> nil | string data
'''VFS.FileExists'''
( string "filename" [, number mode ] ) -> boolean
example usage: if VFS.FileExists("maps/Castles.sdz") then ... end 

'''VFS.DirList'''
( string "directory" [, string "pattern" = "*" [, number mode ] ] )
-> { [1] = string filename, ... }
'''VFS.SubDirs'''
( string "directory", [, string "pattern" = "*" [, number mode ] ] )
-> { [1] = string subdir1, ... }

'''VFS.GetAvailableAIs'''
( [ string gameName] [, string mapName ] )
-> { ai1, ai2, ... }
Gets a list of all Spring AIs. The optional gameName and mapName parameters can be used to include game/map specific LuaAIs in the list.

'''VFS.UseArchive''' unsynced only!
( string "filename" [, number mode ], lua_function [, arg1 [,arg2 ]] )
-> result1,result2,... of the given lua_function
Loads an archive '''temporarely''' in the VFS and then runs the given lua_function, which can make usage of the files in the archive.

'''VFS.MapArchive''' unsynced only!
( string "filename/modname of archive", [string checksum of archive] )
-> bool
Permanently loads an archive into the VFS (to load zipped music collections etc.). Does nothing if the archive is already loaded in the VFS (won't reload even if there are changes made to the archive). If checksum is given it checks if the to be loaded file is correct, if not then it won't load it and return false.

'''VFS.UnmapArchive''' unsynced only! available in 98.0
( string "filename/modname of archive")
-> bool
Removes an already loaded archive (see VFS.MapArchive)

'''VFS.CompressFolder''' unsynced only!
( string "folderPath" [, string "archiveType" ] [, string "compressedFilePath" ] [, bool includeFolder ] [, number mode ] ) -> nil

Compresses the specified folder. archiveType defines the compression type which can currently be only "zip" includeFolder specifies whether the archive should have the specified folder as root (defaults to false) 

'''VFS.GetFileAbsolutePath''' unsynced only! available in 105.0
( string "filename" [, number mode ] ) -> absPath | nil

'''VFS.GetArchiveContainingFile''' unsynced only! available in 105.0
( string "filename" [, number mode ] ) -> archiveNameWithVersion | nil

= Generic hash =
'''VFS.CalculateHash''' {{new|101.0}}
( string input, number hashType)
-> string md5hash

Calculates hash (in base64 form) of a given string (with md5 support initially). Note supplying 0 (MD5) as hashType is mandatory

= Archives =

'''VFS.GetMaps''' {{new|98.0}}
( ) -> {
[1] = string mapName, ...
}

'''VFS.GetGames''' {{new|98.0}}
( ) -> {
[1] = string gameName, ...
}

'''VFS.GetAllArchives''' {{new|98.0}}
( ) -> {
[1] = string archiveName, ...
}

'''VFS.HasArchive''' {{new|98.0}}
( string archiveName ) -> boolean

'''VFS.GetArchiveInfo''' {{new|98.0}}
( string archiveName ) - >
{
name = string,
shortname = string,
version = string,
mutator = string,
game = string,
shortgame = string,
description = string,
mapfile = string,
modtype = number,
}
modtype values:1=primary, 0=hidden, 3=map

'''VFS.GetArchiveChecksum''' {{new|98.0}}
( string archiveName ) -> string singleArchiveChecksum, string completeArchiveChecksum

'''VFS.GetArchiveDependencies''' {{new|98.0}}
( string archiveName ) -> {
[1] = string archiveName, ...
}

'''VFS.GetArchiveReplaces''' {{new|98.0}}
( string archiveName ) -> {
[1] = string archiveName, ...
}

'''VFS.DownloadArchive''' {{new|101.0}}
( name, category ) -> nil

Category must be one of: map, game, engine.

'''VFS.AbortDownload''' {{new|104.0}}
( id ) -> boolean foundAndRemoved

Additional functions are available as part of the [[Lua_UnsyncedCtrl#.28Virtual-.29FileSystem|unsynced ctrl]].

= Packing =
The Pack- and Unpack-functions are used to convert numbers->strings and strings->numbers.
So you can read a binary file and then convert the received strings back to numbers and the other way around. Also you can use it in combination with the SendLuaXYZMsg-functions.

'''VFS.PackU8'''

'''VFS.PackU16'''

'''VFS.PackU32'''

'''VFS.PackS8'''

'''VFS.PackS16'''

'''VFS.PackS32'''

'''VFS.PackF32'''

arguments are:

'''VFS.PackX( number arg1, number arg2, number arg3, ... )''' -> string

'''VFS.PackX( {[1]=number,[2]=number,..} )''' -> string

'''VFS.UnpackU8'''

'''VFS.UnpackU16'''

'''VFS.UnpackU32'''

'''VFS.UnpackS8'''

'''VFS.UnpackS16'''

'''VFS.UnpackS32'''

'''VFS.UnpackF32'''

arguments are:

'''VFS.UnpackX( string "binary" [, number position = 1] [, number count] )'''
-> number | table { [1]=number,[2]=number,.. }

= Zlib =
'''VFS.ZlibCompress''' unsynced only!
( string "uncompressedStr" )
-> nil | string "compressedStr"

'''VFS.ZlibDecompress''' available in synced, too!
( string "compressedStr" [, number uncompressed size = 65500] )
-> nil | string "uncompressedStr"

[[category: Lua]]

Script.txt

2019-01-15T15:49:15Z

Gajop:

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

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

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

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

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

Since 99.0 <code>GAME/Gametype</code> can be a [[rapid]] tag, and demo recording can be disabled by setting <code>GAME/RecordDemo</code> to 0

Since 102.0 <code>GAME/SaveFile</code> can be specified in start script in order to start from a (lua) save (.slsf).

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

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

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

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

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

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

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

[[Category:Development]]

Mapdev:Tutorial Simple

2019-01-02T03:49:24Z

Gajop: /* Edit mapinfo.lua */

= Beginners Tutorial Stage 1 =
This beginners tutorial is aimed at getting you from nothing, to something simple which you can build upon.

* We'll start with the height map, defining the structure of the terrain
* Then the metalmap, a resource scheme built into the spring engine
* The diffuse texture, defining the colour of the terrain
* The minimap, for when selecting the map in the game lobby
* The grass map, for that extra flourish of detail
* Finally set up the start positions

= What you will need =
* An image editor, such as [http://www.gimp.org/ GIMP] or [http://www.adobe.com/products/photoshop.html Adobe Photoshop], [http://en.wikipedia.org/wiki/List_of_raster_graphics_editors#List etc]
* [http://www.7-zip.org/ 7zip]
* Windows - [[MapConv]], Linux - [[MapConvNG]]
* a copy of the map blueprint [https://github.com/jk3064/Map-Blueprint/archive/master.zip archive]

There are a multitude of other tools you can use to make maps, however for the purposes of this beginners tutorial, these are the only ones you will need. Check the [[Mapdev:Main#Tools|tools]] section for more information.

= Download =
* [http://springfiles.com/spring/other/mapdev-stage1-working-files Download] the working files
* [http://springfiles.com/spring/spring-maps/mapdev-stage1 Download] the completed map archive

= Preparation =
<ol>
<li>Extract the mapcontainer.sdd folder from the blueprint archive into your working directory.</li>
Your directory structure should look like this:
<pre>working directory
|-mapcontainer.sdd/
|-LuaGaia/
|-mapconfig/
|-maphelper/
|-maps/
|-mapinfo.lua
|-mapoptions.lua
</pre>
<li>Rename the mapcontainer.sdd folder to the name of your map, eg. mymap.sdd
<li>Edit the following variables in the mapinfo.lua file, ignore the rest for now.
* name
* shortname
* description
* author
* version (just put like v1 or something in here)
</ol>

= Create Height map =
For this tutorial we will be creating a 4x4 size map, which is relatively small. Typically maps will be 8x8 (for a 1v1) or larger, but entirely depends on the game you are targeting.
<ol>
<li>Check the [[Mapdev:height|height]] page to get our image dimensions. In our case a 4x4 map yields a image resolution of 257x257 pixels
<li>Create a 257x257 greyscale image using your image editor
<li>Draw the terrain</li>
<li>Save the image to your working directory, call it heightmap.png
</ol>
{{Tip|Black represents the lowest elevation on the map, white represents the highest, in between lies all the shades of grey. Hard edges in the image will be cliffs, and smooth gradients will be ramps.}}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-height.png|256px]] || [[File:Mapdev-height-example.png]]
|-
! Example Height Map !! Ingame Result
|}</center>
== Edit mapinfo.lua ==
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Change the <code>minHeight</code> and <code>maxHeight</code> variables to <code>10</code> and <code>256</code> respectively 
These values control the overall height of the terrain, and will be unique to your map. After loading up the map in game you may want to revisit and tweak these values to get the best result. 
The resulting portion of code should appear like this:
<pre>local mapinfo = {
...
smf = {
minHeight = 10,
maxHeight = 256,
...
},
...
}</pre>
</ol>

= Create Metal Map =
{{Caution|There are several games for Spring which use their own resourcing system. If you are creating a map for one of those games, a metal map may not be necessary, however it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.}}
<ol>
<li>Check the [[Mapdev:metal|metal]] page to get our image dimensions. In our case a 4x4 map yields an image resolution of 128x128 pixels
<li>Create a 128x128 RGB image using your image editor
<li>Paint the whole image black
<li>Paint full red spots 6 or so pixels in diameter on the places where you want metal to appear in game.
<li>Save the image to your working directory, call it metalmap.png
</ol>
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-metal.png|256px]] || [[File:Mapdev-metal-example.png]]
|-
! Example Metal Map !! Ingame Result
|}</center>
== Edit mapinfo.lua ==
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Change the <code>maxMetal </code> and the <code>extractorRadius</code> variables to <code>6.0</code> and <code>32.0</code> respectively 
These variables control the maximum amount of metal that a metal extractor can extract at full capacity, and the radius that a metal extractor will be able to draw from. 
The resulting portion of code will appear thus:
<pre>local mapinfo = {
...
maxMetal = 6.0,
extractorRadius = 32.0,
...
}</pre>
</ol>

= Create Diffuse Texture =
<ol>
<li>Check the [[Mapdev:diffuse|diffuse]] page to get our image dimensions. In our case a 4x4 map yields an image resolution of 2048x2048 pixels
<li>Create a 2048x2048 RGB image using your image editor
<li>Paint your ground colour in such a way that it compliments the height of the terrain, and metal spots.
<li>Save the image to your working directory, call it diffuse.png
</ol>
{{Tip|It may be useful to use the heightmap.png and metalmap.png images as a starting points, scaling them up to size, and then painting over the top.}}
{{Caution|The larger the map the greater the file size this texture will be, a 4x4 map at 2048x2048 the diffuse texture image is already at 5.4mb, imagine a 32x32 size map, it would be in the hundreds of megabytes. Working with large textures is difficult, and requires good hardware. }}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-diffuse.jpg]] || [[File:Mapdev-diffuse-example.png]]
|-
! Example Diffuse Map !! Ingame Result
|}</center>

= Create Mini Map =
The [[Mapdev:minimap|mini-map]] is a thumbnail image of the the whole map displayed in lobbies when selecting maps.
<ol>
<li>Load up your diffuse.png image
<li>Scale the image to exactly 1024x1024 pixels
<li>Save the image to your working directory, call it mini.png
</ol>

= Create Grass Map =
Grass adds additional depth to your map, giving it a little bit extra.
# Check the [[Mapdev:grass|grass]] page to get our image dimensions. In our case a 4x4 map yields a image resolution of 64x64 pixels
# Create a 64x64 RGB image using your image editor
# Paint the image fully black to begin with
# Paint varying strengths of blue for where you want the grass to show up.
# Save the image to your working directory, call it grassmap.png
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-grass.png]] || [[File:Mapdev-grass-example.png|455px]]
|-
! Grass map !! In Game Result
|}</center>

= Define Start Positions =
considering the small size of the map we will only define two teams
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Locate the teams subtable and delete the lines for teams 2 and 3
<li>Edit the <code>x</code> and <code>z</code> coordinate for each team to define their start location 
The coordinates for spring relate 1:1 with the pixels in the diffuse map. Starting at the top left of the image at (0,0). <code>x</code> increases horizontally to the right, <code>z</code> increases vertically downwards. 
The code should look similar to this:
<pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 256, z = 1024}},
[1] = {startPos = {x = 1792, z = 1024}},
},
...
}</pre>
</ol>
<center>
{| class="wikitable"
| [[File:Mapdev-coords.png]]
|-
! Coordinates
|}</center>

= Review =
From the tutorial we have learned how to make the:
* Height map
* Diffuse texture
* Metal map
* Mini map
* Grass map
* Start locations

Your directory structure should look similar to this:
<pre>working directory
|-mymapname.sdd/
| |-LuaGaia/
| |-mapconfig/
| |-maphelper/
| |-maps/
| |-mapinfo.lua
| |-mapoptions.lua
|-grassmap.png
|-heightmap.png
|-metalmap.png
|-diffuse.png
|-minimap.png
</pre>

Now we need to get the map loaded into the game

= Finalizing =
Continue to [[Mapdev:Tutorial_Finalizing|this page]] to compile, test and archive your map for distribution.

= I want more =
Continue to [[Mapdev:Tutorial_Intermediate|stage two]]

[[Category:Map Dev]]

Mapdev:Tutorial Simple

2019-01-02T03:49:17Z

Gajop: /* Edit mapinfo.lua */

= Beginners Tutorial Stage 1 =
This beginners tutorial is aimed at getting you from nothing, to something simple which you can build upon.

* We'll start with the height map, defining the structure of the terrain
* Then the metalmap, a resource scheme built into the spring engine
* The diffuse texture, defining the colour of the terrain
* The minimap, for when selecting the map in the game lobby
* The grass map, for that extra flourish of detail
* Finally set up the start positions

= What you will need =
* An image editor, such as [http://www.gimp.org/ GIMP] or [http://www.adobe.com/products/photoshop.html Adobe Photoshop], [http://en.wikipedia.org/wiki/List_of_raster_graphics_editors#List etc]
* [http://www.7-zip.org/ 7zip]
* Windows - [[MapConv]], Linux - [[MapConvNG]]
* a copy of the map blueprint [https://github.com/jk3064/Map-Blueprint/archive/master.zip archive]

There are a multitude of other tools you can use to make maps, however for the purposes of this beginners tutorial, these are the only ones you will need. Check the [[Mapdev:Main#Tools|tools]] section for more information.

= Download =
* [http://springfiles.com/spring/other/mapdev-stage1-working-files Download] the working files
* [http://springfiles.com/spring/spring-maps/mapdev-stage1 Download] the completed map archive

= Preparation =
<ol>
<li>Extract the mapcontainer.sdd folder from the blueprint archive into your working directory.</li>
Your directory structure should look like this:
<pre>working directory
|-mapcontainer.sdd/
|-LuaGaia/
|-mapconfig/
|-maphelper/
|-maps/
|-mapinfo.lua
|-mapoptions.lua
</pre>
<li>Rename the mapcontainer.sdd folder to the name of your map, eg. mymap.sdd
<li>Edit the following variables in the mapinfo.lua file, ignore the rest for now.
* name
* shortname
* description
* author
* version (just put like v1 or something in here)
</ol>

= Create Height map =
For this tutorial we will be creating a 4x4 size map, which is relatively small. Typically maps will be 8x8 (for a 1v1) or larger, but entirely depends on the game you are targeting.
<ol>
<li>Check the [[Mapdev:height|height]] page to get our image dimensions. In our case a 4x4 map yields a image resolution of 257x257 pixels
<li>Create a 257x257 greyscale image using your image editor
<li>Draw the terrain</li>
<li>Save the image to your working directory, call it heightmap.png
</ol>
{{Tip|Black represents the lowest elevation on the map, white represents the highest, in between lies all the shades of grey. Hard edges in the image will be cliffs, and smooth gradients will be ramps.}}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-height.png|256px]] || [[File:Mapdev-height-example.png]]
|-
! Example Height Map !! Ingame Result
|}</center>
== Edit mapinfo.lua ==
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Change the <code>minHeight</code> and <code>maxHeight</code> variables to <code>10</code> and <code>256</code> respectively 
These values control the overall height of the terrain, and will be unique to your map. After loading up the map in game you may want to revisit and tweak these values to get the best result. 
The resulting portion of code should appear like this:
<pre>local mapinfo = {
...
smf = {
minHeight = 10,
maxHeight = 256,
...
},
...
}</pre>
</ol>

= Create Metal Map =
{{Caution|There are several games for Spring which use their own resourcing system. If you are creating a map for one of those games, a metal map may not be necessary, however it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.}}
<ol>
<li>Check the [[Mapdev:metal|metal]] page to get our image dimensions. In our case a 4x4 map yields an image resolution of 128x128 pixels
<li>Create a 128x128 RGB image using your image editor
<li>Paint the whole image black
<li>Paint full red spots 6 or so pixels in diameter on the places where you want metal to appear in game.
<li>Save the image to your working directory, call it metalmap.png
</ol>
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-metal.png|256px]] || [[File:Mapdev-metal-example.png]]
|-
! Example Metal Map !! Ingame Result
|}</center>
== Edit mapinfo.lua ==
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Change the <code>maxMetal </code> and the <code>extractorRadius</code> variables to <code>6.0</code> and <code>32.0</code> respectively 
These variables control the maximum amount of metal that a metal extractor can extract at full capacity, and the radius that a metal extractor will be able to draw from. 
The resulting portion of code will appear thus:
<code><pre>local mapinfo = {
...
maxMetal = 6.0,
extractorRadius = 32.0,
...
}</pre></code>
</ol>

= Create Diffuse Texture =
<ol>
<li>Check the [[Mapdev:diffuse|diffuse]] page to get our image dimensions. In our case a 4x4 map yields an image resolution of 2048x2048 pixels
<li>Create a 2048x2048 RGB image using your image editor
<li>Paint your ground colour in such a way that it compliments the height of the terrain, and metal spots.
<li>Save the image to your working directory, call it diffuse.png
</ol>
{{Tip|It may be useful to use the heightmap.png and metalmap.png images as a starting points, scaling them up to size, and then painting over the top.}}
{{Caution|The larger the map the greater the file size this texture will be, a 4x4 map at 2048x2048 the diffuse texture image is already at 5.4mb, imagine a 32x32 size map, it would be in the hundreds of megabytes. Working with large textures is difficult, and requires good hardware. }}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-diffuse.jpg]] || [[File:Mapdev-diffuse-example.png]]
|-
! Example Diffuse Map !! Ingame Result
|}</center>

= Create Mini Map =
The [[Mapdev:minimap|mini-map]] is a thumbnail image of the the whole map displayed in lobbies when selecting maps.
<ol>
<li>Load up your diffuse.png image
<li>Scale the image to exactly 1024x1024 pixels
<li>Save the image to your working directory, call it mini.png
</ol>

= Create Grass Map =
Grass adds additional depth to your map, giving it a little bit extra.
# Check the [[Mapdev:grass|grass]] page to get our image dimensions. In our case a 4x4 map yields a image resolution of 64x64 pixels
# Create a 64x64 RGB image using your image editor
# Paint the image fully black to begin with
# Paint varying strengths of blue for where you want the grass to show up.
# Save the image to your working directory, call it grassmap.png
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-grass.png]] || [[File:Mapdev-grass-example.png|455px]]
|-
! Grass map !! In Game Result
|}</center>

= Define Start Positions =
considering the small size of the map we will only define two teams
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Locate the teams subtable and delete the lines for teams 2 and 3
<li>Edit the <code>x</code> and <code>z</code> coordinate for each team to define their start location 
The coordinates for spring relate 1:1 with the pixels in the diffuse map. Starting at the top left of the image at (0,0). <code>x</code> increases horizontally to the right, <code>z</code> increases vertically downwards. 
The code should look similar to this:
<pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 256, z = 1024}},
[1] = {startPos = {x = 1792, z = 1024}},
},
...
}</pre>
</ol>
<center>
{| class="wikitable"
| [[File:Mapdev-coords.png]]
|-
! Coordinates
|}</center>

= Review =
From the tutorial we have learned how to make the:
* Height map
* Diffuse texture
* Metal map
* Mini map
* Grass map
* Start locations

Your directory structure should look similar to this:
<pre>working directory
|-mymapname.sdd/
| |-LuaGaia/
| |-mapconfig/
| |-maphelper/
| |-maps/
| |-mapinfo.lua
| |-mapoptions.lua
|-grassmap.png
|-heightmap.png
|-metalmap.png
|-diffuse.png
|-minimap.png
</pre>

Now we need to get the map loaded into the game

= Finalizing =
Continue to [[Mapdev:Tutorial_Finalizing|this page]] to compile, test and archive your map for distribution.

= I want more =
Continue to [[Mapdev:Tutorial_Intermediate|stage two]]

[[Category:Map Dev]]

Mapdev:Tutorial Simple

2019-01-02T03:48:43Z

Gajop: /* Define Start Positions */

= Beginners Tutorial Stage 1 =
This beginners tutorial is aimed at getting you from nothing, to something simple which you can build upon.

* We'll start with the height map, defining the structure of the terrain
* Then the metalmap, a resource scheme built into the spring engine
* The diffuse texture, defining the colour of the terrain
* The minimap, for when selecting the map in the game lobby
* The grass map, for that extra flourish of detail
* Finally set up the start positions

= What you will need =
* An image editor, such as [http://www.gimp.org/ GIMP] or [http://www.adobe.com/products/photoshop.html Adobe Photoshop], [http://en.wikipedia.org/wiki/List_of_raster_graphics_editors#List etc]
* [http://www.7-zip.org/ 7zip]
* Windows - [[MapConv]], Linux - [[MapConvNG]]
* a copy of the map blueprint [https://github.com/jk3064/Map-Blueprint/archive/master.zip archive]

There are a multitude of other tools you can use to make maps, however for the purposes of this beginners tutorial, these are the only ones you will need. Check the [[Mapdev:Main#Tools|tools]] section for more information.

= Download =
* [http://springfiles.com/spring/other/mapdev-stage1-working-files Download] the working files
* [http://springfiles.com/spring/spring-maps/mapdev-stage1 Download] the completed map archive

= Preparation =
<ol>
<li>Extract the mapcontainer.sdd folder from the blueprint archive into your working directory.</li>
Your directory structure should look like this:
<pre>working directory
|-mapcontainer.sdd/
|-LuaGaia/
|-mapconfig/
|-maphelper/
|-maps/
|-mapinfo.lua
|-mapoptions.lua
</pre>
<li>Rename the mapcontainer.sdd folder to the name of your map, eg. mymap.sdd
<li>Edit the following variables in the mapinfo.lua file, ignore the rest for now.
* name
* shortname
* description
* author
* version (just put like v1 or something in here)
</ol>

= Create Height map =
For this tutorial we will be creating a 4x4 size map, which is relatively small. Typically maps will be 8x8 (for a 1v1) or larger, but entirely depends on the game you are targeting.
<ol>
<li>Check the [[Mapdev:height|height]] page to get our image dimensions. In our case a 4x4 map yields a image resolution of 257x257 pixels
<li>Create a 257x257 greyscale image using your image editor
<li>Draw the terrain</li>
<li>Save the image to your working directory, call it heightmap.png
</ol>
{{Tip|Black represents the lowest elevation on the map, white represents the highest, in between lies all the shades of grey. Hard edges in the image will be cliffs, and smooth gradients will be ramps.}}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-height.png|256px]] || [[File:Mapdev-height-example.png]]
|-
! Example Height Map !! Ingame Result
|}</center>
== Edit mapinfo.lua ==
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Change the <code>minHeight</code> and <code>maxHeight</code> variables to <code>10</code> and <code>256</code> respectively 
These values control the overall height of the terrain, and will be unique to your map. After loading up the map in game you may want to revisit and tweak these values to get the best result. 
The resulting portion of code should appear like this:
<code><pre>local mapinfo = {
...
smf = {
minHeight = 10,
maxHeight = 256,
...
},
...
}</pre></code>
</ol>

= Create Metal Map =
{{Caution|There are several games for Spring which use their own resourcing system. If you are creating a map for one of those games, a metal map may not be necessary, however it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.}}
<ol>
<li>Check the [[Mapdev:metal|metal]] page to get our image dimensions. In our case a 4x4 map yields an image resolution of 128x128 pixels
<li>Create a 128x128 RGB image using your image editor
<li>Paint the whole image black
<li>Paint full red spots 6 or so pixels in diameter on the places where you want metal to appear in game.
<li>Save the image to your working directory, call it metalmap.png
</ol>
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-metal.png|256px]] || [[File:Mapdev-metal-example.png]]
|-
! Example Metal Map !! Ingame Result
|}</center>
== Edit mapinfo.lua ==
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Change the <code>maxMetal </code> and the <code>extractorRadius</code> variables to <code>6.0</code> and <code>32.0</code> respectively 
These variables control the maximum amount of metal that a metal extractor can extract at full capacity, and the radius that a metal extractor will be able to draw from. 
The resulting portion of code will appear thus:
<code><pre>local mapinfo = {
...
maxMetal = 6.0,
extractorRadius = 32.0,
...
}</pre></code>
</ol>

= Create Diffuse Texture =
<ol>
<li>Check the [[Mapdev:diffuse|diffuse]] page to get our image dimensions. In our case a 4x4 map yields an image resolution of 2048x2048 pixels
<li>Create a 2048x2048 RGB image using your image editor
<li>Paint your ground colour in such a way that it compliments the height of the terrain, and metal spots.
<li>Save the image to your working directory, call it diffuse.png
</ol>
{{Tip|It may be useful to use the heightmap.png and metalmap.png images as a starting points, scaling them up to size, and then painting over the top.}}
{{Caution|The larger the map the greater the file size this texture will be, a 4x4 map at 2048x2048 the diffuse texture image is already at 5.4mb, imagine a 32x32 size map, it would be in the hundreds of megabytes. Working with large textures is difficult, and requires good hardware. }}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-diffuse.jpg]] || [[File:Mapdev-diffuse-example.png]]
|-
! Example Diffuse Map !! Ingame Result
|}</center>

= Create Mini Map =
The [[Mapdev:minimap|mini-map]] is a thumbnail image of the the whole map displayed in lobbies when selecting maps.
<ol>
<li>Load up your diffuse.png image
<li>Scale the image to exactly 1024x1024 pixels
<li>Save the image to your working directory, call it mini.png
</ol>

= Create Grass Map =
Grass adds additional depth to your map, giving it a little bit extra.
# Check the [[Mapdev:grass|grass]] page to get our image dimensions. In our case a 4x4 map yields a image resolution of 64x64 pixels
# Create a 64x64 RGB image using your image editor
# Paint the image fully black to begin with
# Paint varying strengths of blue for where you want the grass to show up.
# Save the image to your working directory, call it grassmap.png
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-grass.png]] || [[File:Mapdev-grass-example.png|455px]]
|-
! Grass map !! In Game Result
|}</center>

= Define Start Positions =
considering the small size of the map we will only define two teams
<ol>
<li>Open the mapinfo.lua file in a text editor
<li>Locate the teams subtable and delete the lines for teams 2 and 3
<li>Edit the <code>x</code> and <code>z</code> coordinate for each team to define their start location 
The coordinates for spring relate 1:1 with the pixels in the diffuse map. Starting at the top left of the image at (0,0). <code>x</code> increases horizontally to the right, <code>z</code> increases vertically downwards. 
The code should look similar to this:
<pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 256, z = 1024}},
[1] = {startPos = {x = 1792, z = 1024}},
},
...
}</pre>
</ol>
<center>
{| class="wikitable"
| [[File:Mapdev-coords.png]]
|-
! Coordinates
|}</center>

= Review =
From the tutorial we have learned how to make the:
* Height map
* Diffuse texture
* Metal map
* Mini map
* Grass map
* Start locations

Your directory structure should look similar to this:
<pre>working directory
|-mymapname.sdd/
| |-LuaGaia/
| |-mapconfig/
| |-maphelper/
| |-maps/
| |-mapinfo.lua
| |-mapoptions.lua
|-grassmap.png
|-heightmap.png
|-metalmap.png
|-diffuse.png
|-minimap.png
</pre>

Now we need to get the map loaded into the game

= Finalizing =
Continue to [[Mapdev:Tutorial_Finalizing|this page]] to compile, test and archive your map for distribution.

= I want more =
Continue to [[Mapdev:Tutorial_Intermediate|stage two]]

[[Category:Map Dev]]

Mapdev:lightemission

2018-12-18T15:39:50Z

Gajop: /* mapinfo.lua */

= Light Emission Texture =
Adds colour to a fragment (pixel). The colour added is the RGB colour of the emission texture, while the alpha of the emission texture determines the amount of the original colour that remains.

Can be used for accentuation. For example, metal spots in shadowed regions
<center>
{| class="wikitable"
|+ Example
|
[[File:Map without light emission.jpg|frameless|Map without light emission]]
||
[[File:Map with light emission.jpg|frameless|Map with light emission]]
|-
! Without Light Emission Texture!! With Light Emission Texture
|}</center>

= Specification =
== mapinfo.lua ==
The relevant sections of the [[Mapdev:mapinfo.lua|mapinfo.lua]]
<pre>
local mapinfo = {
...
resources = {
...
lightEmissionTex = "light_emission.png",
...
},
...
}</pre>

== Image File==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain. Should be the same size as the [[Mapdev:specular]] image
|}
<pre>
Modifies the fragment color as follows

fragmentColor.rgb = fragmentColor.rgb * (1 - lightEmissionTex.a) + lightEmissionTex.rgb
</pre>

[[Category:Map Dev]]

Mapdev:skyreflectmod

2018-12-18T15:39:39Z

Gajop: /* mapinfo.lua */

= Sky Reflection Modifier Texture =
Sets the weight for mixing the diffuse texture colour with the reflected colour of the sky. This occurs before any other shading calculations use the diffuse colour.

This can be used to suggest a surface composed of reflective materials, such as ice or crystals.

<center>
{| class="wikitable"
|+ Example
| [[File: skyreflectmod_without_example.png|300px]]|| [[File: skyreflectmod_with_example.png|300px]]
|-
! Without Sky Reflection Modifier Map !! With Sky Reflection Modifier Map
|}</center>

= Specification =
== mapinfo.lua ==
The relevant sections of the [[Mapdev:mapinfo.lua|mapinfo.lua]]
<pre>
local mapinfo = {
...
resources = {
...
skyReflectModTex = "skyreflectmod.png",
...
},
...
}</pre>

== Image File==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGB
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain. Should be the same size as the [[Mapdev:specular]] image
|}
<pre>
Modifies the diffuse colours as follows:
diffuseColor.r = diffuseColor.r * (1 - skyReflectModTex.r) +
reflectionColor.r * skyReflectModTex.r
diffuseColor.g = diffuseColor.g * (1 - skyReflectModTex.g) +
reflectionColor.g * skyReflectModTex.g
diffuseColor.b = diffuseColor.b * (1 - skyReflectModTex.b) +
reflectionColor.b * skyReflectModTex.b

Equivalent to the GLSL code: (diffuseColor is a vector)
diffuseColor = mix(diffuseColor, reflectionColor, skyReflectModTex)
</pre>

[[Category:Map Dev]]

Mapdev:normal

2018-12-18T15:39:09Z

Gajop: /* mapinfo.lua */

= Normal Texture =
Gives the terrain a normal map. This can be used to suggest small surface details while keeping terrain flat. The RGB channels determine the XYZ of the new surface normal (in tangent space), while the alpha channel determines how much of the original surface normal is kept.

[https://code.google.com/p/gimp-normalmap/ This GIMP plugin] provides various ways to convert heightmaps into normal maps.

{{Caution|Requires clients to have GLSL-spec hardware}}
<center>
{| class="wikitable"
|+ Example
| {{FIXME}} needs image file || {{FIXME}} needs image file
|-
! Without Normal Map !! With Normal Map
|}</center>

= Important Info =

* The normal map effect will *not* be shown unless you have a specular map defined. It can be as simple as a full-black with full-black alpha image, TGA 32-bit format is recommended. 
* If you want to merge two normal maps, for instance, one for the terrain and one for the resources (metal, geo vents), it's not as simple as it might sound if you want to do it properly. You can read about it in detail [http://wiki.polycount.com/wiki/Normal_map here]. The "Whiteout" technique is recommended, there is a Photoshop action available for it [https://polycount.com/discussion/163801/udn-and-whiteout-normal-map-blending-photoshop-actions here] 

= Specification =
== mapinfo.lua ==
The relevant sections of the [[Mapdev:mapinfo.lua|mapinfo.lua]]
<pre>
local mapinfo = {
...
resources = {
...
detailNormalTex = "normal.png",
...
},
...
}</pre>

== Image File==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain.
|}

<pre>
Modifies the shading normal as follows

shadingNormal.xyz = NORMALIZE(terrainNormal.xyz * (1 - detailNormalTex.a)
+ detailNormalTex.rgb)
</pre>

[[Category:Map Dev]]

Mapdev:specular

2018-12-18T15:38:59Z

Gajop: /* mapinfo.lua */

= Specular =
Gives you per-pixel control over the color and intensity of specular highlights anywhere on the map. You could eg. make all highlights red, or have them depend on the type of material that a pixel represents, or something more exotic.
The alpha channel defines how "polished" the surface looks (glossiness), and the RGB color is the amount of light that gets reflected for each color channel.
{{Caution|requires clients to have GLSL-spec hardware}}
<center>
{| class="wikitable"
| [[File:Mapdev-specular.jpg|256px]] || [[File:Mapdev-spec_with.jpg|451px]]
|-
! Example Specular Texture
! Ingame Result
|}</center>

= Specification =
== mapinfo.lua ==
The relevant sections of the [[Mapdev:mapinfo.lua|mapinfo.lua]]
* If specularTex points to a file that does not exist, you will get full unmoderated specularity based on whatever your map's lighting settings are
<pre>
local mapinfo = {
resources = {
...
specularTex = "",
...
},
...
lighting = {
...
groundSpecularColor = {0.1, 0.1, 0.1},
...
},
...
}
</pre>

== Image File ==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain.
|}
* The RGB channels will control the red, green, and blue contribution per highlight
* The Alpha channel (multiplied by 16) becomes the specular exponent. Or on other words controls the sharpness of the specular highlights, the higher the value the sharper the highlights.
* You have to set the RGB values to zero if you want no specular contribution
* If you omit the alpha channel, or have a fully opaque image, the specular exponent is at its max and the results are a very sharp specular highlights.
{{Caution|If you set the alpha value of the specular texture to zero, or you will get the below result. Use almost zero instead.}}
<center>
{| class="wikitable"
| [[File:Mapdev-spec_alpha_issue.jpg]]
|}</center>

= Forum Discussion =
* [http://springrts.com/phpbb/viewtopic.php?f=13&t=21951 Make Your Maps Shiny(er) With SSMF]

[[Category:Map Dev]]

Mapdev:splatdetailnormals

2018-12-18T15:38:46Z

Gajop: /* mapinfo.lua */

= Detail Normal Texture Splatting (DNTS) =

This extends the existing functionality of SSMF splatted detail textures [[Mapdev:splatdetail]], with the option of specifying 4 different (normal map + greyscale diffuse map) detail textures.

Splatted detail textures only allowed grayscale textures to be overlayed on the map, while DNTS also allows normal maps as well.

Instead of creating a combined detail texture of 4 different single-channel diffuse detail textures stored in a single RGBA image, it uses four separate normal textures.

The textures must contain the normal maps in the RGB channel (standard normal maps), with a diffuse luminance in the alpha channel.

The system uses the same splatDistributionTexture as regular SSMF.

'''You cannot specify these options in .smd files, only .lua!'''

Example result:

[[File:dnts_example.jpg|960px]]
== Distribution Image ==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA, DDS
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain.
|}

The RGBA Channels are individual greyscale distribution maps which define which detail textures to splat onto the ground. The intensity of the splatted textures is multipled by the pixel values for the corresponding channels.
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-ddist.gif]] || [[File:Mapdev-ddist.png]]
|-
! Detail Distribution maps !! Combined Result
|}</center>

== Detail Normal Textures ==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA, DDS
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGB for normal maps only, RGBA for normal map + diffuse map in alpha channel. The Y (green) channel of normal maps should be inverted.
|-
! Resolution
| Any, recommended powers of two, will be tiled over the terrain.
|}

<center>
{| class="wikitable"
|+ Detail Normal Texture Example
| [[File:Mapdev-dnts-normal.jpg|400px]] || [[File:Mapdev-dnts-diffuse-alpha.jpg|400px]]
|-
! Normal texture in RGB channel !! greyscale diffuse in ALPHA channel
|}</center>

= Specification =

Specify splatDetailNormalTex1 .. splatDetailNormalTex4 in the MAP resources section. splatDetailTex will be unused if and of splatDetailNormalTex[1-4] are present.

Specify splatDetailNormalDiffuseAlpha=1 to enable diffuse textures stored in alpha channels.

splatDetailNormalDiffuseAlpha=0 is the default value, and will ignore all and any alpha channels in the splatDetailNormalTex's, resulting in a purely normal mapped surface, with no extra diffuse texturing.

texScales and texMults work identically to [[Mapdev:splatdetail]]

== mapinfo.lua ==
<pre>
local mapinfo = {
...
resources = {
...
splatDistrTex = "splatDistributionTex.tga",
splatDetailNormalDiffuseAlpha = 1,
splatDetailNormalTex = {
"sandpebbles_NORM.tga",
"crystal_245_dnts.dds",
"grass_91_dnts.dds",
"pebbles_250_dnts_u8888.dds",
alpha = true,
},
...
},
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre>

[[Category:Map Dev]]

Mapdev:splatdetail

2018-12-18T15:38:21Z

Gajop: /* mapinfo.lua */

= Details =
Splat Detail textures extend the default single detail texture that is applied uniformly over the entire map, by allowing the mapper to specify 4 different greyscale detail textures, and offers control of the strength, spatial distribution and tiling resolution of each detail texture.

Important: Splat Detail textures requires a specular texture [[Mapdev:specular]] to exist and be defined in order to be enabled!

{{Caution|requires clients to have GLSL-spec hardware}}
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-splat-without.jpg|330px]] || [[File:Mapdev-splat-with.jpg|330px]]
|-
! Default Detail Map !! Splat Detail Maps
|-
| colspan="2" | ''* Click on images for higher res''
|}</center>

= Specification =
== mapinfo.lua ==
<pre>
local mapinfo = {
...
resources = {
...
splatDistrTex = "splatDistributionTex.tga",
splatDetailTex = "splatDetailTex.tga",
...
},
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre>

=== texScales ===

texScales offers a way to adjust the tiling resolution of each of the 4 splat detail textures. Values of 0.02 are the default values, lower values will increase the size of the textures on the ground, and higher values will decrease the tile size.

<center>
{| class="wikitable"
|[[File:Map measure.png|512px|measuring stick]]
|-
! texScales
|}</center>

=== texMults ===

texMults offers a quick way to adjust the strength at which each detail texture will be blended onto the map. Values of 1.0 are the default values, lower values will make the detail texture fainter, higher values make it more pronounced. This is very useful for fine-tuning the strengths after generating the splat distribution texture, which is time-consuming to manipulate in an image editor, and cant be increased above a certain value there.

== Distribution Image ==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain.
|}

The RGBA Channels are individual greyscale distribution maps which define which detail textures to splat onto the ground. The intensity of the splatted textures is multipled by the pixel values for the corresponding channels.
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-ddist.gif]] || [[File:Mapdev-ddist.png]]
|-
! Detail Distribution maps !! Combined Result
|}</center>

== Detail Image ==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| Any, recommended powers of two, will be tiled over the terrain.
|}
Each Channel represents a seperate greyscale image. The ground colour is multiplied by the pixel values of the channel. The intensity of the effect is also controlled per channel using the {{xtaglink|mapinfo.lua|texMults}} variables, low numbers = less effect.
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-details.gif]] || [[File:Mapdev-details.png]]
|-
! Individual Detail Textures !! Combined Result
|}</center>

= Forum Discussion =
* [http://springrts.com/phpbb/viewtopic.php?f=56&t=21565 Detail texture resource thread]
* [http://springrts.com/phpbb/viewtopic.php?f=13&t=22564 Detail texture splatting is ready!]

[[Category:Map Dev]]

Mapdev:detail

2018-12-18T15:38:12Z

Gajop: /* mapinfo.lua */

= Details =
{{FIXME}} Needs description here
<center>
{| class="wikitable"
|+ Example
| {{FIXME}} needs image || [[File:Mapdev-splat-without.jpg|330px]]
|-
! Example Detail Texture !! Ingame Result
|-
| colspan="2" | ''* Click on images for higher res''
|}</center>

= Specification =
== mapinfo.lua ==
<pre>
local mapinfo = {
...
resources = {
...
detailTex = "",
...
},
...
}</pre>

== Image File ==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA, BMP, DDS {{new|99.0}}
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGB
|-
! Resolution
| Any powers of two, eg. 256, 512, 1024...
|}

[[Category:Map Dev]]

Mapdev:diffuse

2018-12-18T15:37:49Z

Gajop: /* mapinfo.lua */

= Diffuse =
The colour of the terrain, then modified with the lighting values in mapinfo.lua
<center>
{| class="wikitable"
|+ Example
| [[File:Mapdev-diffuse.jpg]] || [[File:Mapdev-diffuse-example.png]]
|-
! Example Diffuse Map !! Ingame Result
|}</center>

= Specification =
== mapinfo.lua ==
The relevant sections of the mapinfo.lua file that effect the colour of the ground are in the [[Map_Making:mapinfo.lua#Lighting|Lighting subtable]]

<pre>
local mapinfo = {
...
lighting = {
...
--// 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,
...
},
...
}
</pre>

== Image File ==
{| class="wikitable" width="100%"
! width="15%" | File Location
| The diffuse texture is chopped into 32x32 pixel tiles compressed using DXT1 and compiled into the smt using [[MapConv]] or [[MapConvNG]].
|-
! File Format
| Any that Mapconv programs support
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| <center>
{| class="wikitable" style="text-align: center;"
!Spring Map Size*
!pixels = Spring Map Size * 512
|-
| 2
| 1024
|-
| 4
| 2048
|-
| 6
| 3072
|-
| ...
| ...
|-
| 32
| 16 384
|-
| style="text-align: left;font-style:italic" colspan=2 | * must be multiples of 2
|}</center>
|}

== Compression ==
The DXT1 compression is lossy, but in a consistent manner. all 32x32 tiles will have exactly the same size. To reduce the number of tiles saved in tile file(SMT) you can align graphical elements to a 32x32 pixel grid. MapConv can detect that a tile is repeated and reference it only once. This means that any repetition of the diffuse image, so long as it is aligned to a 32x32 pixel grid will result in a reduction in size.

* Use tiled textures that are multiples of 32x32 in dimensions.
* Place features like geovents and metal spots on a 32x32 grid.
* Repeat as much as possible on a 32x32 pixel grid.

[[Category:Map Dev]]

Mapdev:parallax

2018-12-18T15:37:26Z

Gajop: /* mapinfo.lua */

= Parallax Texture =
modifies the diffuse, normal, and specular
TEXTURE COORDINATES before sampling is done

{{FIXME}} description as to why you want to use Parallax textures.
<center>
{| class="wikitable"
|+ Example
| {{FIXME}} needs image file || {{FIXME}} needs image file
|-
! Without Parallax Map !! With Parallax Map
|}</center>
= Specification =
== mapinfo.lua ==
The relevant sections of the [[Mapdev:mapinfo.lua|mapinfo.lua]]
<pre>
local mapinfo = {
...
resources = {
...
parallaxHeightTex = "parallax.png",
...
},
...
}</pre>

== Image File==
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGBA
|-
! Resolution
| Any, recommended powers of two, will be stretched over the terrain. Should be the same size as the [[Mapdev:specular]] image
|}
{{FIXME}} needs cleaning.
<pre>
height, scale, and bias parameters are packed
as follows to produce a texel offset-factor f

h = (parallaxHeightTex.r * 65280 + parallaxHeightTex.g * 256) / 65536
s = (parallaxHeightTex.b)
b = (parallaxHeightTex.a - 0.5)
f = h * s + b
</pre>

= Forum Discussions =
* [http://springrts.com/phpbb/viewtopic.php?f=13&t=29108 Parallax Maps?]

[[Category:Map Dev]]

Modrules.lua

2018-12-18T11:29:24Z

Gajop: /* system */

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

==Purpose==
This file controls various global parameters of the game, for example how fast units gain experience, what unit types can be transported, how fine grained the LOS system is, etc.

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

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

==Data Types==
{{DataTypes}}

==Details==
<code>Modrules.lua</code> is divided into several sub-tables containing tags specific to each section, as follows:

===capture===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to capture something.
}}

===construction===
{{tag
|name = constructionDecay
|type = bool
|default = true
|description = Do uncompleted building frames begin to decay if no builder is working on them?
}}

{{tag
|name = constructionDecayTime
|type = float
|default = 6.66
|description = The time in seconds before abandoned building frames begin to decay.
}}

{{tag
|name = constructionDecaySpeed
|type = float
|default = 0.03
|description = How fast build progress decays for abandoned building frames. Note that the rate is inversely proportional to the {{xtaglink|Gamedev:UnitDefs|buildtime}} i.e. a building with a larger {{xtaglink|Gamedev:UnitDefs|buildtime}} will decay more slowly for a given value of this tag than a building with a shorter {{xtaglink|Gamedev:UnitDefs|buildtime}}.
}}

===experience===
{{tag
|name = experienceMult
|type = float
|default = 1.0
|description = Controls the amount of experience gained by units engaging in combat. The formulae used are:
::<code>xp for damage = 0.1 * experienceMult * damage / target_HP * target_power / attacker_power</code>
::<code>xp for kill = 0.1 * experienceMult * target_power / attacker_power</code>.
: Where {{xtaglink|Gamedev:UnitDefs|power}} can be set by the UnitDef tag.
}}

{{tag
|name = powerScale
|type = float
|default = 1.0
|description = Controls how gaining experience changes the relative {{xtaglink|Gamedev:UnitDefs|power}} of the unit. The formula used is <code>Power multiplier = powerScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = healthScale
|type = float
|default = 0.7
|description = Controls how gaining experience increases the {{xtaglink|Gamedev:UnitDefs|maxDamage}} (total hitpoints) of the unit. The formula used is <code>Health multiplier = healthScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = reloadScale
|type = float
|default = 0.4
|description = Controls how gaining experience decreases the {{xtaglink|Gamedev:UnitDefs|reloadTime}} of the unit's weapons. The formula used is <code>Rate of fire multiplier = reloadScale * (1 + xp / (xp + 1))</code>.
}}

===featureLOS===
{{tag
|name = featureVisibility
|type = int
|default = 3
|description = Controls the visibility of features. Can be <code>0</code> - no default LOS for features, <code>1</code> - Gaia features always visible, <code>2</code> - allyteam & Gaia features always visible, or <code>3</code> - all features always visible.
}}

===fireAtDead===
{{tag
|name = fireAtKilled
|type = bool
|default = false
|description = Will units continue to target and fire on enemies which are running their <code>Killed()</code> animation? (See [[Animation-LuaCallins#Generic]])
}}

{{tag
|name = fireAtCrashing
|type = bool
|default = false
|description = Will units continue to target and fire on enemy aircraft which are in the 'crashing' state? (See [[Lua_SyncedCtrl#Unit_Control]])
}}

===flankingBonus===
{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Gamedev:UnitDefs|flankingBonusMode}} for units. 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.
}}

====los====
{{tag
|name = losMipLevel
|type = int
|default = 1
|description = Controls the resolution of the LOS calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the LOS map in both x and y direction. Must be between <code>0</code> and <code>6</code> inclusive.
}}

{{tag
|name = losMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|sightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = airMipLevel
|type = int
|default = 1
|description = Controls the resolution of the LOS vs. aircraft calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the air-LOS map in both x and y direction. Must be between <code>0</code> and <code>30</code> inclusive. [http://springrts.com/mantis/view.php?id=4031#c11709] - jK describe for you what the value means.
}}

{{tag
|name = airLosMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|airSightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = radarMipLevel
|type = int
|default = 2
|description = Controls the resolution of the radar. See description of airMipLevel for details.
}}

===movement===
{{tag
|name = allowAirPlanesToLeaveMap
|type = bool
|default = true
|description = Are (gunship) aircraft allowed to fly outside the bounds of the map?
}}

{{tag
|name = allowAircraftToHitGround
|type = bool
|default = true
|special = {{new|90.0}}
|description = Are aircraft allowed to hit the ground whilst manoeuvring?
}}

{{tag
|name = allowPushingEnemyUnits
|type = bool
|default = false
|special = {{new|83.0}}
|description = Can enemy ground units push each other during collisions?
}}

{{tag
|name = allowCrushingAlliedUnits
|type = bool
|default = false
|special = {{new|85.0}}
|description = Can allied ground units crush each other during collisions? Units still have to be explicitly set as crushable using the <code>crushable</code> parameter of [[Lua_SyncedCtrl#Unit_Control|Spring.SetUnitBlocking]].
}}

{{tag
|name = allowUnitCollisionDamage
|type = bool
|default = false
|special = {{new|85.0}}
|description = Do unit-unit (skidding) collisions cause damage?
}}

{{tag
|name = allowUnitCollisionOverlap
|type = bool
|default = true
|special = {{new|89.0}}
|description = Can mobile units collision volumes overlap one another? Allows unit movement like [http://www.youtube.com/watch?v=mRtePUdVk2o this (video)] at the cost of more 'clumping'.
}}

{{tag
|name = allowGroundUnitGravity
|type = bool
|default = true
|special = {{new|92.0}}
|description = Allows fast moving mobile units to 'catch air' as they move over terrain.
}}

{{tag
|name = allowHoverUnitStrafing
|type = bool
|default = true if using QTPFS pathfinder
|special = {{new|92.0}}
|description = Allows hovercraft units to slide in turns.
}}

{{tag
|name = useClassicGroundMoveType
|type = bool
|default = false
|special = {{new|89.0}} {{removed|102.0}}
|description = A ticket back to unit movement circa 2009: no reversing, no {{xtaglink|Gamedev:UnitDefs|turninplace|false}}, no smooth collision handling, no nothing. For comparison of pathfinding code.
}}

===paralyze===
{{tag
|name = paralyzeOnMaxHealth
|type = bool
|default = true
|description = Are units paralyzed when the level of emp is greater than their current health or their maximum health?
}}

===reclaim===
{{tag
|name = multiReclaim
|type = int
|default = 0
|description = Can multiple units reclaim a feature or only one? <code>0</code> implies the latter, all other values the former.
}}

{{tag
|name = reclaimMethod
|type = int
|default = 1
|description = Controls how features are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = unitMethod
|type = int
|default = 1
|description = Controls how units are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = featureEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a feature cost? Multiplier against the fraction of the features' {{xtaglink|Gamedev:FeatureDefs|metal}} content reclaimed.
}}

{{tag
|name = unitEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a unit cost? Multiplier against the fraction of the unit's {{xtaglink|Gamedev:UnitDefs|buildCostEnergy}} reclaimed.
}}

{{tag
|name = unitEfficiency
|type = float
|default = 1.0
|description = How much metal should reclaiming a unit return? Multiplier against the unit's {{xtaglink|Gamedev:UnitDefs|buildCostMetal}}.
}}

{{tag
|name = allowEnemies
|type = bool
|default = true
|description = Can enemy units be reclaimed?
}}

{{tag
|name = allowAllies
|type = bool
|default = true
|description = Can allied units be reclaimed?
}}

===repair===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to repair something.
}}

===resurrect===
{{tag
|name = energyCostFactor
|type = float
|default = 0.5
|description = How much of the original energy cost it requires to resurrect something.
}}

===sensors===
{{tag
|name = requireSonarUnderWater
|type = bool
|default = true
|description = If <code>true</code> then when underwater, units only get LOS if they also have sonar.
}}
{{tag
|name = alwaysVisibleOverridesCloaked
|type = bool
|default = false
|special = {{new|101.0}}
|description = If <code>true</code> then units will be visible even when cloaked (probably?).
}}
{{tag
|name = separateJammers
|type = bool
|default = true
|special = {{new|101.0}}
|description = When <code>true</code> each allyTeam only jams their own units.
}}

===system===
{{tag
|name = pathFinderSystem
|type = int
|default = 0
|special={{new|85.0}}
|description = Which pathfinder does the game use? Can be <code>0</code> - The legacy default pathfinder, <code>1</code> - Quad-Tree Pathfinder System ([[QTPFS]])}} or <code>-1</code> - disabled.

{{tag
|name = pathFinderUpdateRate
|type = float
|default = 0.007
|special={{new|98.0}}
|description = Controls how often the pathfinder updates; larger values means more rapid updates.}}

{{tag
|name = allowTake
|type = bool
|default = true
|special = {{new|103.0}}
|description = Enables and disables the {{var|/take}} [[UI_commands|UI command]].}}

===transportability===
{{tag
|name = transportAir
|type = bool
|default = false
|description = Can aircraft be transported?
}}

{{tag
|name = transportShip
|type = bool
|default = false
|description = Can ships be transported?
}}

{{tag
|name = transportHover
|type = bool
|default = false
|description = Can hovercraft be transported?
}}

{{tag
|name = transportGround
|type = bool
|default = true
|description = Can ground units be transported?
}}

{{tag
|name = targetableTransportedUnits
|type = bool
|default = false
|special = {{new|89.0}}
|description = Can transported units be targeted by weapons? <code>true</code> allows both manual and automatic targeting.
}}

==Examples==

===Empty===

<code>modrules.lua</code> can simply return an empty table like this:
<pre>
return {}
</pre>
If you do this, Spring will use the default values.

===Configurable by modoptions===
Interestingly <code>modrules.lua</code> can read [[Modoptions.lua|modoptions]], so these parameters can be scripted to be configurable from the lobby.
For example to allow selecting either legacy default pathfinder or [[QTPFS]] via a modoption:
<pre>
system = {
pathFinderSystem = (Spring.GetModOptions() and (Spring.GetModOptions().qtpfs == "1") and 1) or 0,
},
</pre>

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

[http://code.google.com/p/conflictterra/source/browse/games/CT/gamedata/modrules.lua 'Conflict Terra' Modrules.lua]

[https://code.google.com/p/evolutionrts/source/browse/trunk/evolutiondev.sdd/Gamedata/modrules.lua 'Evolution RTS' Modrules.lua]

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

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

[[Category:gamedata]]

Modrules.lua

2018-12-18T11:28:35Z

Gajop: /* system */

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

==Purpose==
This file controls various global parameters of the game, for example how fast units gain experience, what unit types can be transported, how fine grained the LOS system is, etc.

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

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

==Data Types==
{{DataTypes}}

==Details==
<code>Modrules.lua</code> is divided into several sub-tables containing tags specific to each section, as follows:

===capture===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to capture something.
}}

===construction===
{{tag
|name = constructionDecay
|type = bool
|default = true
|description = Do uncompleted building frames begin to decay if no builder is working on them?
}}

{{tag
|name = constructionDecayTime
|type = float
|default = 6.66
|description = The time in seconds before abandoned building frames begin to decay.
}}

{{tag
|name = constructionDecaySpeed
|type = float
|default = 0.03
|description = How fast build progress decays for abandoned building frames. Note that the rate is inversely proportional to the {{xtaglink|Gamedev:UnitDefs|buildtime}} i.e. a building with a larger {{xtaglink|Gamedev:UnitDefs|buildtime}} will decay more slowly for a given value of this tag than a building with a shorter {{xtaglink|Gamedev:UnitDefs|buildtime}}.
}}

===experience===
{{tag
|name = experienceMult
|type = float
|default = 1.0
|description = Controls the amount of experience gained by units engaging in combat. The formulae used are:
::<code>xp for damage = 0.1 * experienceMult * damage / target_HP * target_power / attacker_power</code>
::<code>xp for kill = 0.1 * experienceMult * target_power / attacker_power</code>.
: Where {{xtaglink|Gamedev:UnitDefs|power}} can be set by the UnitDef tag.
}}

{{tag
|name = powerScale
|type = float
|default = 1.0
|description = Controls how gaining experience changes the relative {{xtaglink|Gamedev:UnitDefs|power}} of the unit. The formula used is <code>Power multiplier = powerScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = healthScale
|type = float
|default = 0.7
|description = Controls how gaining experience increases the {{xtaglink|Gamedev:UnitDefs|maxDamage}} (total hitpoints) of the unit. The formula used is <code>Health multiplier = healthScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = reloadScale
|type = float
|default = 0.4
|description = Controls how gaining experience decreases the {{xtaglink|Gamedev:UnitDefs|reloadTime}} of the unit's weapons. The formula used is <code>Rate of fire multiplier = reloadScale * (1 + xp / (xp + 1))</code>.
}}

===featureLOS===
{{tag
|name = featureVisibility
|type = int
|default = 3
|description = Controls the visibility of features. Can be <code>0</code> - no default LOS for features, <code>1</code> - Gaia features always visible, <code>2</code> - allyteam & Gaia features always visible, or <code>3</code> - all features always visible.
}}

===fireAtDead===
{{tag
|name = fireAtKilled
|type = bool
|default = false
|description = Will units continue to target and fire on enemies which are running their <code>Killed()</code> animation? (See [[Animation-LuaCallins#Generic]])
}}

{{tag
|name = fireAtCrashing
|type = bool
|default = false
|description = Will units continue to target and fire on enemy aircraft which are in the 'crashing' state? (See [[Lua_SyncedCtrl#Unit_Control]])
}}

===flankingBonus===
{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Gamedev:UnitDefs|flankingBonusMode}} for units. 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.
}}

====los====
{{tag
|name = losMipLevel
|type = int
|default = 1
|description = Controls the resolution of the LOS calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the LOS map in both x and y direction. Must be between <code>0</code> and <code>6</code> inclusive.
}}

{{tag
|name = losMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|sightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = airMipLevel
|type = int
|default = 1
|description = Controls the resolution of the LOS vs. aircraft calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the air-LOS map in both x and y direction. Must be between <code>0</code> and <code>30</code> inclusive. [http://springrts.com/mantis/view.php?id=4031#c11709] - jK describe for you what the value means.
}}

{{tag
|name = airLosMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|airSightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = radarMipLevel
|type = int
|default = 2
|description = Controls the resolution of the radar. See description of airMipLevel for details.
}}

===movement===
{{tag
|name = allowAirPlanesToLeaveMap
|type = bool
|default = true
|description = Are (gunship) aircraft allowed to fly outside the bounds of the map?
}}

{{tag
|name = allowAircraftToHitGround
|type = bool
|default = true
|special = {{new|90.0}}
|description = Are aircraft allowed to hit the ground whilst manoeuvring?
}}

{{tag
|name = allowPushingEnemyUnits
|type = bool
|default = false
|special = {{new|83.0}}
|description = Can enemy ground units push each other during collisions?
}}

{{tag
|name = allowCrushingAlliedUnits
|type = bool
|default = false
|special = {{new|85.0}}
|description = Can allied ground units crush each other during collisions? Units still have to be explicitly set as crushable using the <code>crushable</code> parameter of [[Lua_SyncedCtrl#Unit_Control|Spring.SetUnitBlocking]].
}}

{{tag
|name = allowUnitCollisionDamage
|type = bool
|default = false
|special = {{new|85.0}}
|description = Do unit-unit (skidding) collisions cause damage?
}}

{{tag
|name = allowUnitCollisionOverlap
|type = bool
|default = true
|special = {{new|89.0}}
|description = Can mobile units collision volumes overlap one another? Allows unit movement like [http://www.youtube.com/watch?v=mRtePUdVk2o this (video)] at the cost of more 'clumping'.
}}

{{tag
|name = allowGroundUnitGravity
|type = bool
|default = true
|special = {{new|92.0}}
|description = Allows fast moving mobile units to 'catch air' as they move over terrain.
}}

{{tag
|name = allowHoverUnitStrafing
|type = bool
|default = true if using QTPFS pathfinder
|special = {{new|92.0}}
|description = Allows hovercraft units to slide in turns.
}}

{{tag
|name = useClassicGroundMoveType
|type = bool
|default = false
|special = {{new|89.0}} {{removed|102.0}}
|description = A ticket back to unit movement circa 2009: no reversing, no {{xtaglink|Gamedev:UnitDefs|turninplace|false}}, no smooth collision handling, no nothing. For comparison of pathfinding code.
}}

===paralyze===
{{tag
|name = paralyzeOnMaxHealth
|type = bool
|default = true
|description = Are units paralyzed when the level of emp is greater than their current health or their maximum health?
}}

===reclaim===
{{tag
|name = multiReclaim
|type = int
|default = 0
|description = Can multiple units reclaim a feature or only one? <code>0</code> implies the latter, all other values the former.
}}

{{tag
|name = reclaimMethod
|type = int
|default = 1
|description = Controls how features are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = unitMethod
|type = int
|default = 1
|description = Controls how units are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = featureEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a feature cost? Multiplier against the fraction of the features' {{xtaglink|Gamedev:FeatureDefs|metal}} content reclaimed.
}}

{{tag
|name = unitEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a unit cost? Multiplier against the fraction of the unit's {{xtaglink|Gamedev:UnitDefs|buildCostEnergy}} reclaimed.
}}

{{tag
|name = unitEfficiency
|type = float
|default = 1.0
|description = How much metal should reclaiming a unit return? Multiplier against the unit's {{xtaglink|Gamedev:UnitDefs|buildCostMetal}}.
}}

{{tag
|name = allowEnemies
|type = bool
|default = true
|description = Can enemy units be reclaimed?
}}

{{tag
|name = allowAllies
|type = bool
|default = true
|description = Can allied units be reclaimed?
}}

===repair===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to repair something.
}}

===resurrect===
{{tag
|name = energyCostFactor
|type = float
|default = 0.5
|description = How much of the original energy cost it requires to resurrect something.
}}

===sensors===
{{tag
|name = requireSonarUnderWater
|type = bool
|default = true
|description = If <code>true</code> then when underwater, units only get LOS if they also have sonar.
}}
{{tag
|name = alwaysVisibleOverridesCloaked
|type = bool
|default = false
|special = {{new|101.0}}
|description = If <code>true</code> then units will be visible even when cloaked (probably?).
}}
{{tag
|name = separateJammers
|type = bool
|default = true
|special = {{new|101.0}}
|description = When <code>true</code> each allyTeam only jams their own units.
}}

===system===
{{tag
|name = pathFinderSystem
|type = int
|default = 0
|special={{new|85.0}}
|description = Which pathfinder does the game use? Can be <code>0</code> - The legacy default pathfinder, <code>1</code> - Quad-Tree Pathfinder System ([[QTPFS]]).}} or <code>-11</code> - disabled

{{tag
|name = pathFinderUpdateRate
|type = float
|default = 0.007
|special={{new|98.0}}
|description = Controls how often the pathfinder updates; larger values means more rapid updates.}}

{{tag
|name = allowTake
|type = bool
|default = true
|special = {{new|103.0}}
|description = Enables and disables the {{var|/take}} [[UI_commands|UI command]].}}

===transportability===
{{tag
|name = transportAir
|type = bool
|default = false
|description = Can aircraft be transported?
}}

{{tag
|name = transportShip
|type = bool
|default = false
|description = Can ships be transported?
}}

{{tag
|name = transportHover
|type = bool
|default = false
|description = Can hovercraft be transported?
}}

{{tag
|name = transportGround
|type = bool
|default = true
|description = Can ground units be transported?
}}

{{tag
|name = targetableTransportedUnits
|type = bool
|default = false
|special = {{new|89.0}}
|description = Can transported units be targeted by weapons? <code>true</code> allows both manual and automatic targeting.
}}

==Examples==

===Empty===

<code>modrules.lua</code> can simply return an empty table like this:
<pre>
return {}
</pre>
If you do this, Spring will use the default values.

===Configurable by modoptions===
Interestingly <code>modrules.lua</code> can read [[Modoptions.lua|modoptions]], so these parameters can be scripted to be configurable from the lobby.
For example to allow selecting either legacy default pathfinder or [[QTPFS]] via a modoption:
<pre>
system = {
pathFinderSystem = (Spring.GetModOptions() and (Spring.GetModOptions().qtpfs == "1") and 1) or 0,
},
</pre>

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

[http://code.google.com/p/conflictterra/source/browse/games/CT/gamedata/modrules.lua 'Conflict Terra' Modrules.lua]

[https://code.google.com/p/evolutionrts/source/browse/trunk/evolutiondev.sdd/Gamedata/modrules.lua 'Evolution RTS' Modrules.lua]

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

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

[[Category:gamedata]]

Sounds.lua

2018-12-18T11:17:26Z

Gajop: /* External Examples */

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

===SoundItem Properties===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[https://github.com/ZeroK-RTS/Zero-K/blob/master/gamedata/sounds.lua ZeroK sounds.lua]

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

Modrules.lua

2018-12-18T11:03:35Z

Gajop: /* Examples */

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

==Purpose==
This file controls various global parameters of the game, for example how fast units gain experience, what unit types can be transported, how fine grained the LOS system is, etc.

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

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

==Data Types==
{{DataTypes}}

==Details==
<code>Modrules.lua</code> is divided into several sub-tables containing tags specific to each section, as follows:

===capture===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to capture something.
}}

===construction===
{{tag
|name = constructionDecay
|type = bool
|default = true
|description = Do uncompleted building frames begin to decay if no builder is working on them?
}}

{{tag
|name = constructionDecayTime
|type = float
|default = 6.66
|description = The time in seconds before abandoned building frames begin to decay.
}}

{{tag
|name = constructionDecaySpeed
|type = float
|default = 0.03
|description = How fast build progress decays for abandoned building frames. Note that the rate is inversely proportional to the {{xtaglink|Gamedev:UnitDefs|buildtime}} i.e. a building with a larger {{xtaglink|Gamedev:UnitDefs|buildtime}} will decay more slowly for a given value of this tag than a building with a shorter {{xtaglink|Gamedev:UnitDefs|buildtime}}.
}}

===experience===
{{tag
|name = experienceMult
|type = float
|default = 1.0
|description = Controls the amount of experience gained by units engaging in combat. The formulae used are:
::<code>xp for damage = 0.1 * experienceMult * damage / target_HP * target_power / attacker_power</code>
::<code>xp for kill = 0.1 * experienceMult * target_power / attacker_power</code>.
: Where {{xtaglink|Gamedev:UnitDefs|power}} can be set by the UnitDef tag.
}}

{{tag
|name = powerScale
|type = float
|default = 1.0
|description = Controls how gaining experience changes the relative {{xtaglink|Gamedev:UnitDefs|power}} of the unit. The formula used is <code>Power multiplier = powerScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = healthScale
|type = float
|default = 0.7
|description = Controls how gaining experience increases the {{xtaglink|Gamedev:UnitDefs|maxDamage}} (total hitpoints) of the unit. The formula used is <code>Health multiplier = healthScale * (1 + xp / (xp + 1))</code>.
}}

{{tag
|name = reloadScale
|type = float
|default = 0.4
|description = Controls how gaining experience decreases the {{xtaglink|Gamedev:UnitDefs|reloadTime}} of the unit's weapons. The formula used is <code>Rate of fire multiplier = reloadScale * (1 + xp / (xp + 1))</code>.
}}

===featureLOS===
{{tag
|name = featureVisibility
|type = int
|default = 3
|description = Controls the visibility of features. Can be <code>0</code> - no default LOS for features, <code>1</code> - Gaia features always visible, <code>2</code> - allyteam & Gaia features always visible, or <code>3</code> - all features always visible.
}}

===fireAtDead===
{{tag
|name = fireAtKilled
|type = bool
|default = false
|description = Will units continue to target and fire on enemies which are running their <code>Killed()</code> animation? (See [[Animation-LuaCallins#Generic]])
}}

{{tag
|name = fireAtCrashing
|type = bool
|default = false
|description = Will units continue to target and fire on enemy aircraft which are in the 'crashing' state? (See [[Lua_SyncedCtrl#Unit_Control]])
}}

===flankingBonus===
{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Gamedev:UnitDefs|flankingBonusMode}} for units. 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.
}}

====los====
{{tag
|name = losMipLevel
|type = int
|default = 1
|description = Controls the resolution of the LOS calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the LOS map in both x and y direction. Must be between <code>0</code> and <code>6</code> inclusive.
}}

{{tag
|name = losMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|sightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = airMipLevel
|type = int
|default = 1
|description = Controls the resolution of the LOS vs. aircraft calculations. A higher value means lower resolution but increased performance. An increase by one level means half the resolution of the air-LOS map in both x and y direction. Must be between <code>0</code> and <code>30</code> inclusive. [http://springrts.com/mantis/view.php?id=4031#c11709] - jK describe for you what the value means.
}}

{{tag
|name = airLosMul
|type = float
|default = 1.0
|special = {{removed|101.0}}
|description = Multiplies all unit's {{xtaglink|Gamedev:UnitDefs|airSightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = radarMipLevel
|type = int
|default = 2
|description = Controls the resolution of the radar. See description of airMipLevel for details.
}}

===movement===
{{tag
|name = allowAirPlanesToLeaveMap
|type = bool
|default = true
|description = Are (gunship) aircraft allowed to fly outside the bounds of the map?
}}

{{tag
|name = allowAircraftToHitGround
|type = bool
|default = true
|special = {{new|90.0}}
|description = Are aircraft allowed to hit the ground whilst manoeuvring?
}}

{{tag
|name = allowPushingEnemyUnits
|type = bool
|default = false
|special = {{new|83.0}}
|description = Can enemy ground units push each other during collisions?
}}

{{tag
|name = allowCrushingAlliedUnits
|type = bool
|default = false
|special = {{new|85.0}}
|description = Can allied ground units crush each other during collisions? Units still have to be explicitly set as crushable using the <code>crushable</code> parameter of [[Lua_SyncedCtrl#Unit_Control|Spring.SetUnitBlocking]].
}}

{{tag
|name = allowUnitCollisionDamage
|type = bool
|default = false
|special = {{new|85.0}}
|description = Do unit-unit (skidding) collisions cause damage?
}}

{{tag
|name = allowUnitCollisionOverlap
|type = bool
|default = true
|special = {{new|89.0}}
|description = Can mobile units collision volumes overlap one another? Allows unit movement like [http://www.youtube.com/watch?v=mRtePUdVk2o this (video)] at the cost of more 'clumping'.
}}

{{tag
|name = allowGroundUnitGravity
|type = bool
|default = true
|special = {{new|92.0}}
|description = Allows fast moving mobile units to 'catch air' as they move over terrain.
}}

{{tag
|name = allowHoverUnitStrafing
|type = bool
|default = true if using QTPFS pathfinder
|special = {{new|92.0}}
|description = Allows hovercraft units to slide in turns.
}}

{{tag
|name = useClassicGroundMoveType
|type = bool
|default = false
|special = {{new|89.0}} {{removed|102.0}}
|description = A ticket back to unit movement circa 2009: no reversing, no {{xtaglink|Gamedev:UnitDefs|turninplace|false}}, no smooth collision handling, no nothing. For comparison of pathfinding code.
}}

===paralyze===
{{tag
|name = paralyzeOnMaxHealth
|type = bool
|default = true
|description = Are units paralyzed when the level of emp is greater than their current health or their maximum health?
}}

===reclaim===
{{tag
|name = multiReclaim
|type = int
|default = 0
|description = Can multiple units reclaim a feature or only one? <code>0</code> implies the latter, all other values the former.
}}

{{tag
|name = reclaimMethod
|type = int
|default = 1
|description = Controls how features are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = unitMethod
|type = int
|default = 1
|description = Controls how units are reclaimed. Can be <code>0</code> - gradual reclaim, <code>1</code> - all reclaimed at end, any other positive value <code>n</code> - reclaim in <code>n</code> chunks.
}}

{{tag
|name = featureEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a feature cost? Multiplier against the fraction of the features' {{xtaglink|Gamedev:FeatureDefs|metal}} content reclaimed.
}}

{{tag
|name = unitEnergyCostFactor
|type = float
|default = 0.0
|description = How much energy should reclaiming a unit cost? Multiplier against the fraction of the unit's {{xtaglink|Gamedev:UnitDefs|buildCostEnergy}} reclaimed.
}}

{{tag
|name = unitEfficiency
|type = float
|default = 1.0
|description = How much metal should reclaiming a unit return? Multiplier against the unit's {{xtaglink|Gamedev:UnitDefs|buildCostMetal}}.
}}

{{tag
|name = allowEnemies
|type = bool
|default = true
|description = Can enemy units be reclaimed?
}}

{{tag
|name = allowAllies
|type = bool
|default = true
|description = Can allied units be reclaimed?
}}

===repair===
{{tag
|name = energyCostFactor
|type = float
|default = 0.0
|description = How much of the original energy cost it requires to repair something.
}}

===resurrect===
{{tag
|name = energyCostFactor
|type = float
|default = 0.5
|description = How much of the original energy cost it requires to resurrect something.
}}

===sensors===
{{tag
|name = requireSonarUnderWater
|type = bool
|default = true
|description = If <code>true</code> then when underwater, units only get LOS if they also have sonar.
}}
{{tag
|name = alwaysVisibleOverridesCloaked
|type = bool
|default = false
|special = {{new|101.0}}
|description = If <code>true</code> then units will be visible even when cloaked (probably?).
}}
{{tag
|name = separateJammers
|type = bool
|default = true
|special = {{new|101.0}}
|description = When <code>true</code> each allyTeam only jams their own units.
}}

===system===
{{tag
|name = pathFinderSystem
|type = int
|default = 0
|special={{new|85.0}}
|description = Which pathfinder does the game use? Can be <code>0</code> - The legacy default pathfinder or <code>1</code> - Quad-Tree Pathfinder System ([[QTPFS]]).}}

{{tag
|name = pathFinderUpdateRate
|type = float
|default = 0.007
|special={{new|98.0}}
|description = Controls how often the pathfinder updates; larger values means more rapid updates.}}

{{tag
|name = allowTake
|type = bool
|default = true
|special = {{new|103.0}}
|description = Enables and disables the {{var|/take}} [[UI_commands|UI command]].}}

===transportability===
{{tag
|name = transportAir
|type = bool
|default = false
|description = Can aircraft be transported?
}}

{{tag
|name = transportShip
|type = bool
|default = false
|description = Can ships be transported?
}}

{{tag
|name = transportHover
|type = bool
|default = false
|description = Can hovercraft be transported?
}}

{{tag
|name = transportGround
|type = bool
|default = true
|description = Can ground units be transported?
}}

{{tag
|name = targetableTransportedUnits
|type = bool
|default = false
|special = {{new|89.0}}
|description = Can transported units be targeted by weapons? <code>true</code> allows both manual and automatic targeting.
}}

==Examples==

===Empty===

<code>modrules.lua</code> can simply return an empty table like this:
<pre>
return {}
</pre>
If you do this, Spring will use the default values.

===Configurable by modoptions===
Interestingly <code>modrules.lua</code> can read [[Modoptions.lua|modoptions]], so these parameters can be scripted to be configurable from the lobby.
For example to allow selecting either legacy default pathfinder or [[QTPFS]] via a modoption:
<pre>
system = {
pathFinderSystem = (Spring.GetModOptions() and (Spring.GetModOptions().qtpfs == "1") and 1) or 0,
},
</pre>

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

[http://code.google.com/p/conflictterra/source/browse/games/CT/gamedata/modrules.lua 'Conflict Terra' Modrules.lua]

[https://code.google.com/p/evolutionrts/source/browse/trunk/evolutiondev.sdd/Gamedata/modrules.lua 'Evolution RTS' Modrules.lua]

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

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

[[Category:gamedata]]

Lua SyncedRead

2018-12-15T14:56:07Z

Gajop: /* Features */

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

== Game ==

=== Special TeamID Variables ===
(those special TeamIDs are not supported by all functions) 
'''Spring.ALL_UNITS''' 
'''Spring.MY_UNITS''' 
'''Spring.ALLY_UNITS''' 
'''Spring.ENEMY_UNITS'''

''For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID() 

'''Spring.GetGaiaTeamID'''
( ) -> number teamID

=== GameStates ===
'''Spring.IsGodModeEnabled'''
( ) -> boolean
'''Spring.IsCheatingEnabled'''
( ) -> boolean
'''Spring.IsDevLuaEnabled'''
( ) -> boolean
'''Spring.IsEditDefsEnabled'''
( ) -> boolean
'''Spring.AreHelperAIsEnabled'''
( ) -> boolean
'''Spring.FixedAllies'''
( ) -> nil | boolean

'''Spring.IsGameOver'''
( ) -> boolean

=== RulesParams ===
Those functions allow to save data per Game,Team and Unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
string values are new since 95.0

'''Spring.GetRulesInfoMap''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

'''Spring.GetGameRulesParam'''
( number ruleIndex | string ruleName ) -> nil | number value | string value
'''Spring.GetGameRulesParams'''
( ) -> nil | { [ruleName1] = number | string value1, ... }

'''Spring.GetTeamRulesParam'''
( number teamID, number index | string ruleName ) -> nil | number value | string value
'''Spring.GetTeamRulesParams'''
( number teamID ) -> nil | { [ruleName1] = number | string value1, ... }

'''Spring.GetUnitRulesParam'''
( number unitID, number index | string ruleName ) -> nil | number value | string value
'''Spring.GetUnitRulesParams'''
( number unitID ) -> nil | { [ruleName1] = number | string value1, ... }

'''Spring.GetFeatureRulesParam'''
( number featureID, number index | string ruleName ) -> nil | number value | string value
'''Spring.GetFeatureRulesParams'''
( number featureID ) -> nil | { [ruleName1] = number | string value1, ... }

=== Mod-/Map-Options ===
'''Spring.GetModOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }
'''Spring.GetMapOptions'''
( ) -> {} | { "keyName1" = string "value", "keyName2" = string "value", ... }

! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition: 
"if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end" 
not only: 
"if (Spring.GetModOptions.exampleOption) then...end"

=== Speed/Time ===
'''Spring.GetGameSpeed''' As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

=== Vectors ===
'''Spring.GetWind'''
( ) -> number dirX, number dirY, number dirZ,
number strength, number normDirX, number normDirY, number normDirZ

'''Spring.GetHeadingFromVector'''
( number x, number z ) -> number heading
'''Spring.GetVectorFromHeading'''
( number heading ) -> number x, number z

== Sides/Factions ==
'''Spring.GetSideData'''
( string sideName ) -> nil | string startUnit, string caseSensitiveSideName
( number sideID ) -> nil | string sideName, string startUnit, string caseSensitiveSideName
( ) -> { [1] = { sideName=string,caseName=string,startUnit=string}, [2] = .., .. }

== Teams ==
=== StartBoxes/StartPositions ===
'''Spring.GetAllyTeamStartBox'''
( number allyID ) -> nil | number xmin, number zmin, number xmax, number zmax
'''Spring.GetTeamStartPosition'''
( number teamID ) -> nil | number x, number y, number z

=== Player,Team,Ally Lists/Info ===

Note: AIs are associated to teamIDs (and do not have playerIDs). Code to cycle through AI teamIDs can be found [https://springrts.com/phpbb/viewtopic.php?f=21&t=36873#p586026 here]

'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given

'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

'''Spring.GetPlayerInfo'''
( number playerID ) ->
nil | string "name", (PRE-83.0: in synced code this is "SYNCED_NONAME"!)
boolean active,
boolean spectator,
number teamID,
number allyTeamID,
number pingTime,
number cpuUsage,
string country,
number rank
table customPlayerKeys
'''Spring.GetPlayerControlledUnit'''
( number playerID ) -> nil | number unitID

'''Spring.GetAIInfo'''
( number teamID ) ->
number skirmishAIID,
string name,
number hostingPlayerID,
string shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN")
string version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN")
table options (synced & non-local => empty-table)
Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position.

'''Spring.GetAllyTeamInfo'''
( number allyteamID ) -> nil | table customTeamKeys

'''Spring.GetTeamInfo'''
( number teamID ) ->
nil | number teamID,
number leader, (:= a player id)
boolean isDead,
boolean isAiTeam,
string "side",
number allyTeam,
table customTeamKeys,
number incomeMultiplier
'''Spring.GetTeamResources'''
( number teamID, string "metal" | "energy" ) ->
nil | number currentLevel,
number storage,
number pull,
number income,
number expense,
number share,
number sent,
number received
'''Spring.GetTeamUnitStats'''
( number teamID ) ->
nil | number killed,
number died,
number capturedBy,
number capturedFrom,
number received,
number sent
'''Spring.GetTeamResourceStats''' 0.82 and later
( number teamID, string "metal" | "energy" ) ->
nil | number used,
number produced,
number excessed,
number received,
number sent
'''Spring.GetTeamStatsHistory'''
( number teamID [, number startIndex [, number endIndex = startIndex ]]) ->
nil |
number cur_max_index |
{
[1] = {
"time" = number,
"frame" = number,
"metalUsed" = number,
"metalProduced" = number,
"metalExcess" = number,
"metalReceived" = number,
"metalSent" = number,
"energyUsed" = number,
"energyProduced" = number,
"energyExcess" = number,
"energyReceived" = number,
"energySent" = number,
"damageDealt" = number,
"damageReceived" = number,
"unitsProduced" = number,
"unitsDied" = number,
"unitsReceived" = number,
"unitsSent" = number,
"unitsCaptured" = number,
"unitsOutCaptured" = number,
"unitsKilled" = number
}, ...
}
if called with just teamID as argument it returns the current possible range for startIndex/endIndex :={1..cur_max_index}

'''Spring.GetTeamLuaAI'''
( number teamID ) -> string "luaAI"

Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, so maybe depends, but in my LuaAI.lua name is on first position...

=== Teams/PlayersAllied ===
'''Spring.AreTeamsAllied'''
( number teamID1, number teamID2 ) -> nil | boolean
'''Spring.ArePlayersAllied'''
( number playerID1, number playerID2 ) -> nil | boolean

== Units ==
=== GetUnits ===
'''Spring.GetAllUnits'''
( ) -> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetTeamUnits'''
( number teamID ) -> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitsSorted'''
( number teamID ) -> nil |
unitDefTable = {
[number unitDefID] = { [1] = [number unitID], etc... },
etc...
}
'''Spring.GetTeamUnitsCounts'''
( number teamID ) -> nil | countTable = { [number unitDefID] = count, etc... }
'''Spring.GetTeamUnitsByDefs'''
( number teamID, number unitDefID | { number unitDefID1, ... } )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetTeamUnitDefCount'''
( number teamID, number unitDefID ) -> nil | number count
'''Spring.GetTeamUnitCount'''
( number teamID ) -> nil | number count

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }

plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0


'''Spring.GetUnitNearestAlly'''
( number unitID [, number range ] ) -> nil | number unitID
'''Spring.GetUnitNearestEnemy'''
( number unitID [, number range [, bool useLOS]] ) -> nil | number unitID

Post 95.0 this no longer returns neutral units

=== Unit Informations ===
'''Spring.ValidUnitID'''
( number unitID ) -> boolean
'''Spring.GetUnitIsDead'''
( number unitID ) -> nil | boolean
Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise 
keep this in mind when using (not Spring.GetUnitIsDead())

'''Spring.GetUnitTooltip'''
( number unitID ) -> nil | string tooltip
'''Spring.GetUnitDefID'''
( number unitID ) -> nil | number unitDefID
'''Spring.GetUnitTeam'''
( number unitID ) -> nil | number teamID
'''Spring.GetUnitAllyTeam'''
( number unitID ) -> nil | number allyID
'''Spring.GetUnitLineage''' Removed from version 0.83.x 
( number unitID ) -> nil | number lineage | number lineage, boolean lineageIsRoot
'''Spring.GetUnitNeutral'''
( number unitID ) -> nil | boolean neutral
'''Spring.GetUnitHealth'''
( number unitID ) -> nil | number health, number maxHealth, number paralyzeDamage,
number captureProgress, number buildProgress
build Progress is returned as floating Point between 0.0 and 1.0

'''Spring.GetUnitArmored''' armorMultiple new in version 0.83.x
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitMaxRange'''
( number unitID ) -> nil | number maxEngagementRange
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitHarvestStorage'''
( number unitID ) -> nil | number metal
See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.

'''Spring.GetUnitMetalExtraction''' 0.82+ and later
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitMass''' {{new|101.0}}
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' {{new|85.0}}
( number unitID ) -> nil | boolean blocking, boolean crushable
{{new|95.0}} Now return values are:
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

'''Spring.GetUnitPosition'''
( number unitID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz
[, number mpx, number mpy, number mpz ]
[, number apx, number apy, number apz ]
since 89.0, returns the base (default), middle or aim position of the unit.

'''Spring.GetUnitBasePosition''' Deprecated in 89.0, use GetUnitPosition
( number unitID ) -> nil | number x, number y, number z
returns the bottom of the unit.

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
returns the direction vector

'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
returns heading directions used in COB scripts

'''Spring.GetUnitRotation''' {{New|95.0}}
(number unitID) --> nil | number pitch, number yaw, number roll
Marked as (WIP) in changelog

'''Spring.GetUnitVelocity''' velw new in 95.0
( number unitID ) -> nil | number velx, number vely, number velz, number velLength
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' returns what unit a constructor/factory is currently building
( number unitID ) -> nil | number unitID
'''Spring.GetUnitCurrentBuildPower''' {{new|92.0}}
( number unitID ) -> nil | number buildPower
'''Spring.GetUnitNanoPieces'''
( number unitID ) -> nil | { [1] = number piece1, etc ... }
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
possible types are: los, airLos, radar, sonar, seismic, radarJammer & sonarJammer

'''Spring.GetUnitLosState''' raw is only available in gadgets
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil | number raw |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' surfaceDist new in 95.0
( number unitID1, number unitID2 [, boolean 2D] [, boolean surfaceDist] ) -> nil | number distance
returns the distance of 2 units, surfaceDist calculates the distance between the unitsphere surfaces instead of their midpos

'''Spring.GetUnitFeatureSeparation''' {{new|101.0}}
( number unitID, number featureID [, boolean 2D] ) -> nil | number distance

'''Spring.GetUnitDefDimensions'''
( number unitDefID ) -> nil |
{
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' new in version 0.80+
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

==== Unit Weapon Informations ====
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"


'''Spring.GetUnitWeaponDamages''' {{new|101.0}}
( number unitID, number weaponNum | "selfDestruct" | "explode", string tag ) -> nil | number
`tag` can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.

'''Spring.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ

'''Spring.GetUnitWeaponTryTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponTestTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponTestRange''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponHaveFreeLineOfFire''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

From 104.0 onwards the param list changes so that source firing position can also be passed:

( unitID, weaponNum,
targetID | [srcPosX [, srcPosY [, srcPosZ [, tgtPosX [, tgtPosY [, tgtPosZ ]]]]]] ) -> nil | boolean success

'''Spring.GetUnitWeaponCanFire''' {{new|95.0}}
( number unitID, number weaponNum ) -> nil | boolean canFire

'''Spring.GetUnitWeaponTarget''' {{new|95.0}}
( number unitID, number weaponNum ) -> nil |
number 0 | number 1, bool isUserTarget, number unitID |
number 2, bool isUserTarget, { number posX, number posY, number posZ } |
number 3, bool isUserTarget, number ProjectileID

''returned number of args is always 3 if targetType != None''

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

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

==== Unit LOS ====
'''Spring.IsUnitInLos''' {{new|101.0}}
( number unitID, number allyID ) -> boolean
'''Spring.IsUnitInAirLos''' {{new|101.0}}
( number unitID, number allyID ) -> boolean
'''Spring.IsUnitInRadar''' {{new|101.0}}
( number unitID, number allyID ) -> boolean
'''Spring.IsUnitInJammer''' {{new|101.0}}
( number unitID, number allyID ) -> boolean

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}

'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want move a piece to another piece.

'''Spring.GetUnitPieceDirection''' Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir
( number unitID, number piece ) -> number dirx, number diry, number dirz

'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.

'''Spring.GetUnitPieceMatrix'''
( number unitID, number piece ) -> { [1] = number, ... , [16] = number }

'''Spring.GetUnitPieceList'''
( number unitID ) -> { [1] = string "piecename", ... , [pieceNumN] = string "piecename" }

'''Spring.GetUnitPieceMap'''
( number unitID ) -> { "piecename1" = pieceNum1, ... , "piecenameN" = pieceNumN }

'''Spring.GetUnitPieceInfo'''
( number unitID, number piece ) -> {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}
{{new|95.0}} "parent" field
{{new|101.0}} parent for root pieces is now "[null]" instead of ""

'''Spring.GetUnitScriptPiece'''
( number unitID [, number scriptPiece ] )
-> nil | { scriptPieceNum = number modelPieceNum } | number modelPieceNum

This functions translate the COB ScriptPiece numbers into the ModelPiece numbers (the set of ScriptPieces is a subset of the ModelPieces, means #ScriptPieces <= #ModelPieces), which is used in all other functions (the "number piece" means always the modelpiece). So if you get via Cob2Lua a pieceID you have to translate it with this function. Btw the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }

'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
As of 101.0 this is 1-based piece index argument (was 0-based).

=== CommandQueues ===
'''Spring.GetUnitCommands''' 
'''Spring.GetCommandQueue''' (Alias)
( number unitID, number count = 0 ) -> nil | number commandQueueSize {{new|96}}
( number unitID [, number count = -1] )
-> nil | table commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}

This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]

'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' (cleans the buildqueue of things the unit can't build itself)
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID, number count = 0 ) -> nil | number commandQueueSize {{new|96}}
( number unitID [, number count = -1 ] )
-> nil | table commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}

'''Spring.GetFactoryCounts''' (used to get the buildqueue of a factory, seems screwed o_O)
( number unitID [, number count [, boolean addCMDs ] ] ) -> nil | commandQueueTable = {
[2] = { [number unitDefID | number -cmdID] = number count }, ...
}

=== Command Descriptions/Buttons ===
'''Spring.GetUnitCmdDescs'''
( number unitID [, number startIndex [, number endIndex ] ] ) -> nil | {
[1] = {
"id" = number,
"type" = number,
"name" = string,
"action" = string,
"tooltip" = string,
"texture" = string,
"cursor" = string,
"hidden" = boolean,
"disabled" = boolean,
"showUnique" = boolean,
"onlyTexture" = boolean,

"params" = { [1] = string, ... }
}, ...
}
'''Spring.FindUnitCmdDesc'''
( number unitID, number cmdID ) -> nil | number index

== Features ==
=== GetFeatures ===
'''Spring.GetFeaturesInRectangle'''
( number xmin, number zmin, number xmax, number zmax )
-> featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeatureMass''' {{new|101.0}}
( number featureID ) -> nil | number
'''Spring.GetFeatureSeparation''' {{new|101.0}}
( number featureID1, number featureID2 [, boolean 2D] ) -> nil | number distance
'''Spring.GetFeaturePosition'''
( number featureID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
since 89.0, returns the base (default), middle or aim position of the feature.

'''Spring.GetFeatureVelocity''' {{new|95.0}}
( number featureID [, boolean norm] )
-> nil | number velx, number vely, number velz, number velLength

'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz

'''Spring.GetFeatureRotation''' {{New|101.0}}
(number featureID) --> nil | number pitch, number yaw, number roll

'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources''' reclaimTime {{new|105.0}}
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft, number reclaimTime
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

'''Spring.GetFeaturePieceCollisionVolumeData''' {{new|101.0}}
( number featuerID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

'''Spring.GetFeatureBlocking'''
(number featureID) --> boolean collidable, boolean crushable, boolean blocking
{{new|95.0}} Now return values are:
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

=== Feature Pieces ===
See #Unit_Pieces for full details.

'''Spring.GetFeatureLastAttackedPiece'''

'''Spring.GetFeaturePieceMap'''

'''Spring.GetFeaturePieceList'''

'''Spring.GetFeaturePieceInfo'''

'''Spring.GetFeaturePiecePosition'''

'''Spring.GetFeaturePieceDirection'''

'''Spring.GetFeaturePiecePosDir'''

'''Spring.GetFeaturePieceMatrix'''

== COB ==
'''Spring.GetCOBUnitVar'''
( number unitID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBTeamVar'''
( number teamID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBAllyTeamVar'''
( number allyID, integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY
'''Spring.GetCOBGlobalVar'''
( integer varID [, boolean unpack = false ] )
-> nil | number value | number unpackedX, number unpackedY

== Ground ==
Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
''This returns the ground original (before terraforming) height at a given x,z position''

'''Spring.GetGroundNormal'''
( number x, number z [, smoothedNormal] ) -> number x, number y, number z, number slope
{{new|100.0}}: smoothedNormal and slope

'''Spring.GetGroundInfo'''
( number x, number z ) -> string "Type", number metal, number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed,
number shipSpeed, boolean receiveTracks
'''Spring.GetGroundBlocked'''
( number x, number z |
number x1, number z1, number x2, number z2 )
-> nil | string "feature", number featureID | string "unit", number unitID
'''Spring.GetGroundExtremes'''
( ) -> nil | number minHeight, number maxHeight

'''Spring.GetSmoothMeshHeight'''
( number x, number z ) -> number y

'''Spring.GetMetalMapSize'''
( ) -> number sizeX, number sizeY

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
where x & z are in metal map coordinates (worldspace/16)

'''Spring.GetTerrainTypeData''' {{new|92.0}}
( number i )
-> nil | string "name", number hardness,
number tankSpeed, number kbotSpeed, number hoverSpeed, number shipSpeed,
boolean receiveTracks

'''Spring.GetGrass'''
( number x, number z ) -> number 0 | 1
where x & z are in worldspace coordinates

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove
{{New|95.0}} parameters now are:
number unitDefID,
number pos.x, number pos.y, number pos.z
[, number dir.x
[, number dir.y
[, number dir.z
[, boolean testTerrain
[, boolean testObjects
[, boolean centerOnly ]]]]]]
) --> boolean

'''Spring.TestBuildOrder'''
( number unitDefID, number x, number y, number z, number facing)
-> number blocking [,number featureID]

blocking can be:
0 - blocked
1 - mobile unit in the way
2 - free (or if featureID is != nil then with a blocking feature that can be reclaimed)
facing can be:
0, "s", "south"
1, "e", "east"
2, "n", "north"
3, "w", "west"
'''Spring.Pos2BuildPos''' optional param ''facing'' supported in 0.83 and later
( number unitDefID, number x, number y, number z[, number facing] )
-> nil | number x, number y, number z

=== PathFinding ===
'''Spring.GetUnitEstimatedPath'''
( number unitID ) -> nil | {
[1] = { x,y,z }, ...
},{
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}
GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState''' jammed new in 95.0
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar, boolean jammed
jammed indicates if a position is actively being radar- or sonar-jammed by '''any''' allyteam

'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

( number xmin, number zmin, number xmax, number zmax
[, boolean excludeWeaponProjectiles
[, boolean excludePieceProjectiles] ] )
-> nil | projectileTable = { [1] = number projectileID, etc... }

'''Spring.GetProjectileOwnerID''' {{new|99.0}}
(number projectileID) -> nil | number unitID

'''Spring.GetProjectileTeamID''' {{new|99.0}}
(number projectileID) -> nil | number teamID

'''Spring.GetProjectileDefID'''
(number projectileID) -> nil | number weaponDefID
using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName

'''Spring.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece

'''Spring.GetProjectileTarget'''
( number projectileID )
Pre 95.0: -> nil | number targetID, string targetTypeStr
Post 95.0: -> nil | [number targetTypeInt, number targetID | table targetPos = {x, y, z}]

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

'''Spring.GetProjectileIntercepted''' {{new|99.0}}
( number projectileID ) -> nil | boolean isBeingIntercepted

'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
{{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons

'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity

'''Spring.GetPieceProjectileParams''' {{new|95.0}}
( number projectileID ) -> nil | number explosionFlags, number spinAngle,
number spinSpeed, number spinVector.x, number spinVector.y, number spinVector.z
Where explosionFlags use binary flags with the following integer equivalents:
more info [http://springrts.com/wiki/Animation-CobConstants#explode here]
SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 

'''Spring.GetProjectileTimeToLive''' {{new|99.0}}
( number projectileID ) -> nil | number ttl

'''Spring.GetProjectileDirection''' {{new|95.0}}
( number projectileID ) -> nil | number dir.x, number dir.y, number dir.z

'''Spring.GetProjectileSpinAngle''' Deprecated in 95.0
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed''' Deprecated in 95.0
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec''' Deprecated in 95.0
( number projectileID ) -> nil | number x, number y, number z

'''Spring.GetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.

[[category: Lua]]

Sounds.lua

2018-12-09T23:11:21Z

Gajop:

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

===SoundItem Properties===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Lua UnsyncedCtrl

2018-12-08T15:31:50Z

Gajop: /* (Virtual-)FileSystem */

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

<div class="note">
NOTE: Prior to 102.0, entries below marked (needs ModUICtrl) require the setting ModUICtrl to be enabled in the users [[springrc]], if you want to use them in unsynced LuaRules/LuaGaia. It is enabled by default in previous versions and removed in 102.0 so you generally don't need to care.</div>

= UI =
'''Spring.SetLastMessagePosition'''
( number x, number y, number z ) -> nil

= Ingame Console =
'''Spring.Echo'''
( arg1 [, arg2 [, ... ] ] ) -> nil

Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.

'''Spring.Log'''
( string section, int logLevel | string logLevel,
arg2 [, arg3 [, ... ] ] ) -> nil

Possible values for logLevel are:
"debug" | LOG.DEBUG
"info" | LOG.INFO
"notice" | LOG.NOTICE (engine default) {{new|97}}
"warning" | LOG.WARNING
"error" | LOG.ERROR
"fatal" | LOG.FATAL

'''Spring.SendCommands''' (needs ModUICtrl)
( string command1 [, string command2 [ ... ] ] ) -> nil
( {string command1, string command2, ...} ) -> nil

== GUI ==
'''Spring.SetActiveCommand''' (needs ModUICtrl)
( string action [, string actionExtra ] ) -> nil | boolean
( number cmdIndex [, number button = 1
[, boolean leftClick, boolean rightClick,
boolean alt, boolean ctrl, boolean meta, boolean shift]] ) -> nil | boolean
'''Spring.LoadCmdColorsConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.LoadCtrlPanelConfig''' (needs ModUICtrl)
( string config ) -> nil
'''Spring.ForceLayoutUpdate''' (needs ModUICtrl)
( ) -> nil
'''Spring.SetDrawSelectionInfo''' disables the "Selected Units x" box in the GUI (needs ModUICtrl)
( boolean enable ) -> nil

== Mouse ==
'''Spring.SetMouseCursor''' (needs ModUICtrl)
( string cursorName [, number scale ] ) -> nil
'''Spring.WarpMouse''' (needs ModUICtrl)
( number x, number y ) -> nil

== LOS Colors ==
'''Spring.SetLosViewColors''' (needs ModUICtrl)

New arguments since 100.0 (radar2 is the inside of radar edge):
( always = {r,g,b}, LOS = {r,g,b}, radar = {r,g,b}, jam = {r,g,b}, radar2 = {r,g,b}) -> nil

Arguments for 99.0 and before:
( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil

== SendMessage ==
'''Spring.SendMessage'''
( string "message" ) -> nil
'''Spring.SendMessageToPlayer'''
( number playerID, string "message" ) -> nil
'''Spring.SendMessageToTeam'''
( number teamID, string "message" ) -> nil
'''Spring.SendMessageToAllyTeam'''
( number allyID, string "message" ) -> nil
'''Spring.SendMessageToSpectators'''
( string "message" ) -> nil
Funfact:
<PLAYER#> (with # being a playerid) inside the string will be replaced with the players name.
ie
Spring.SendMessage ("<PLAYER1> did something")
might display as "ProRusher did something"

== Markers ==
'''Spring.MarkerAddPoint''' (needs ModUICtrl)
( number x, number y, number z [, string text = "" [, bool localOnly] ] ) -> nil
'''Spring.MarkerAddLine''' (needs ModUICtrl)
( number x1, number y1, number z1, number x2, number y2, number z2 ) -> nil
'''Spring.MarkerErasePosition''' (needs ModUICtrl)
( number x, number y, number z ) -> nil

= Sounds =
'''Spring.LoadSoundDef'''
( string "soundfile" ) -> nil | boolean success
Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.

'''Spring.PlaySoundFile''' Plays WAV or OGG sounds.
( string "soundfile" [, number volume = 1.0
[, number posx, number posy, number posz
[, number speedx, number speedy, number speedz ] ] ], [string/number channel ] ) -> nil | boolean
`channel` is new in Spring0.83, and can be one of those:
"general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3


'''Spring.PlaySoundStream'''
( string "oggfile" [, number volume = 1.0
[, bool enqueue ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream currently running.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

= SendLuaMessage =
Very important! (allows synced inter-lua-enviroment communications)

'''Spring.SendLuaUIMsg''' (needs ModUICtrl)
( string message, string mode ) -> nil
possible modes are: "s"/"specs" & "a"/"allies"
'''Spring.SendLuaGaiaMsg''' (needs ModUICtrl)
( string message ) -> nil
'''Spring.SendLuaRulesMsg''' (needs ModUICtrl)
( string message ) -> nil

= AI =
'''Spring.SendSkirmishAIMessage''' {{new|83.0}}
( number aiTeam, string message )
-> nil | boolean ai_processed, { [1] = string response1, etc... }
Note there is nothing in this table due to "limitations" of the AI interface.

= Units =
'''Spring.SetUnitLeaveTracks''' {{new|83.0}}
( number unitID, boolean leavetracks ) -> nil

'''Spring.SetUnitSelectionVolumeData''' {{new|104.0}}
( number featureID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil

== Unit Selection ==
'''Spring.SelectUnitMap'''
( { [unitID] = anything, ...} [,boolean append] ) -> nil
'''Spring.SelectUnitArray'''
( { [1] = unitID1 , [2] = unitID2 , ...} [,boolean append] ) -> nil

'''Spring.SetDrawSelectionInfo'''
( boolean drawSelectionInfo ) -> nil

== Unit Group ==
'''Spring.SetUnitGroup''' (needs ModUICtrl)
( number unitID, number groupID ) -> nil

== Give Order ==
'''Spring.GiveOrder''' gives order to all selected units (needs ModUICtrl)
( number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnit''' (needs ModUICtrl)
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitMap''' (needs ModUICtrl)
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitMap''' (needs ModUICtrl)
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
}
) -> nil | boolean true
'''Spring.GiveOrderArrayToUnitArray''' (needs ModUICtrl)
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"}
}, ..
},
[boolean pairwise]
) -> nil | boolean true

pairwise param ({{new|89.0}}) is used to send multiple units a single individual command

'''Spring.SetBuildFacing'''
( int Facing ) -> nil

'''Spring.SetBuildSpacing'''
( int Spacing ) -> nil

== Unit NoDraw,NoSelect,NoMinimap ==
'''Spring.SetUnitNoDraw''' LuaGadgets only!
( number unitID, boolean noDraw ) -> nil
'''Spring.SetUnitNoSelect''' LuaGadgets only!
( number unitID, boolean noSelect ) -> nil
'''Spring.SetUnitNoMinimap''' LuaGadgets only!
( number unitID, boolean noMinimap ) -> nil

= Features =
'''Spring.SetFeatureFade''' {{new|101.0}}
( int featureID, bool allow ) -> nil
Control whether a feature will fade or not when zoomed out.

'''Spring.SetFeatureNoDraw''' LuaGadgets only!
( number featureID, boolean noDraw ) -> nil

'''Spring.SetFeatureSelectionVolumeData''' {{new|104.0}}
( number featureID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil

= Developers =
'''Spring.SetDrawSky'''
( boolean drawSky ) -> nil
'''Spring.SetDrawWater'''
( boolean drawWater ) -> nil
'''Spring.SetDrawGround'''
( boolean drawGround ) -> nil

'''Spring.SetWaterParams''' As of 104.0 no longer needs cheating enabled
( table params ) -> nil
Allows to change water params (mostly BumpWater ones) at runtime. You may want to set BumpWaterUseUniforms in your [[springrc]] to 1, then you don't even need to restart BumpWater via `/water 4`. 
`params` table may contain:
params = {
absorb = {number r, number g, number b},
baseColor = {number r, number g, number b},
minColor = {number r, number g, number b},
surfaceColor = {number r, number g, number b},
diffuseColor = {number r, number g, number b},
specularColor = {number r, number g, number b},
planeColor = {number r, number g, number b},
texture = string file,
foamTexture = string file,
normalTexture = string file,
damage = number value,
repeatX = number value,
repeatY = number value,
surfaceAlpha = number value,
ambientFactor = number value,
diffuseFactor = number value,
specularFactor = number value,
specularPower = number value,
fresnelMin = number value,
fresnelMax = number value,
fresnelPower = number value,
reflectionDistortion = number value,
blurBase = number value,
blurExponent = number value,
perlinStartFreq = number value,
perlinLacunarity = number value,
perlinAmplitude = number value,
numTiles = number value,
shoreWaves = boolean value,
forceRendering = boolean value,
hasWaterPlane = boolean value,
}

'''Spring.SetMapRenderingParams''' {{new|104.0}}
( table params ) -> nil
Allows to change map rendering params at runtime. 
`params` table may contain:
params = {
splatTexMults = {number r, number g, number b, number a},
splatTexScales = {number r, number g, number b, number a},
voidWater = boolean value,
voidGround = boolean value,
splatDetailNormalDiffuseAlpha = boolean value,
}

'''Spring.SetLogSectionFilterLevel''' {{New|95.0}}
( string sectionName, string|number logLevel )
see [[infolog.txt]] for possible log sections (?)

'''Spring.SetDrawGroundDeferred''' {{New|95.0}}
( boolean drawGroundDeferred [, boolean drawGroundForward] ) -> nil
{{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass

'''Spring.SetDrawModelsDeferred''' {{New|95.0}}
( boolean drawUnitsDeferred,
boolean drawFeaturesDeferred
[, boolean drawUnitsForward
[, boolean drawFeaturesForward ]]
) -> nil

{{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes

'''Spring.SetVideoCapturingMode''' {{new|104.0}}
( boolean allowCaptureMode ) -> nil

This doesn't actually record the game in any way, it just regulates the framerate and interpolations.

'''Spring.SetVideoCapturingTimeOffset''' {{new|104.0}}
( number timeOffset ) -> nil

= GUI =
'''Spring.DrawUnitCommands'''
( number unitID ) -> nil
( { [1] = unitID, ... } [, false ] ) -> nil
( { [unitID] = anything, ... }, true ) -> nil

'''Spring.SetTeamColor'''
( number teamID, number r, number g, number b ) -> nil

'''Spring.AssignMouseCursor''' changes/creates the cursor of a single CursorCmd
( string "cmdName", string "iconFileName"
[, boolean overwrite = true [, boolean hotSpotTopLeft = false] ] ) -> nil | boolean
Note, that iconFileName is not the full filename instead it is like this: 
wanted filename: Anims/cursorattack_0.bmp 
=> iconFileName: cursorattack


'''Spring.ReplaceMouseCursor''' mass replace all occurrence of the cursor in all CursorCmds
( string "oldFileName", string "newFileName" [, boolean hotSpotTopLeft = false] ) -> nil | boolean

'''Spring.SetCustomCommandDrawData''' register your custom cmd so it gets visible in the unit's cmd queue
( number cmdID,
number cmdID_cloneIcon | string iconname,
{ number r, number g, number b, number a } [, boolean showArea ] ) -> nil
( number cmdID, nil) -> nil

= Sharing =
'''Spring.SetShareLevel''' note: shareLevel is 0<= x <= 1 (needs ModUICtrl)
( string "metal" | "energy", number shareLevel ) -> nil
'''Spring.ShareResources''' (needs ModUICtrl)
( number teamID, string "units" ) -> nil
( number teamID, string "metal" | "energy", number amount ) -> nil

= UnitDef RadarIcons & BuildPics =
'''Spring.AddUnitIcon'''
( string iconName, string texFile [, number size [, number dist [, boolean radAdjust ]]] )
-> nil | boolean
'''Spring.FreeUnitIcon'''
( string iconName ) -> nil | boolean
'''Spring.SetUnitDefIcon''' (RadarIcon) (needs ModUICtrl)
( number unitDefID, string iconName ) -> nil
'''Spring.SetUnitDefImage''' (BuildPic) (needs ModUICtrl)
( number unitDefID, luaTexture | string texFile ) -> nil

= Camera =
'''Spring.SetCameraState'''
( table camState, number camTime) -> nil | boolean
camState has the same format as the output of Spring.GetCameraState(). See [[Lua_camState]] for details about camState.

The camState's mode/name must fit the rest of the state. Getting a state, changing its mode/name and then passing it to SetCameraState will have undesired results. [https://springrts.com/mantis/view.php?id=5028#c15491 Also see #5028]

'''Spring.SetCameraTarget'''
( number x, number y, number z [,number transTime] ) -> nil
For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.

'''Spring.SetCameraOffset''' (needs ModUICtrl)
( [number px = 0 [, number py = 0 [, number pz = 0
[, number tx = 0 [, number ty = 0 [, number tz = 0]]]]]] ) -> nil

= (Virtual-)FileSystem =
'''Spring.ExtractModArchiveFile'''
( string modfile ) -> boolean
'''Spring.CreateDir''' (needs ModUICtrl)
( string path ) -> nil | boolean

The full VFS API is available at [[Lua_VFS|link]].

= Engine Config =
The following functions read the engine configs saved in [[Springsettings.cfg]], a version-ed instance of these or a custom file supplied on the command line.
If ''*Overlay'' is ''true'', the value will only be set in memory, and not be restored for the next game

'''Spring.SetConfigInt'''
( string name, number value [, boolean useOverlay = false] ) -> nil

'''Spring.SetConfigFloat''' {{new|104.0}}
( string name, number value [, boolean useOverlay = false] ) -> nil

'''Spring.SetConfigString'''
( string name, string value [, boolean useOverlay = false] ) -> nil

= World Primitives =
outdated! use opengl api instead!

'''Spring.AddWorldIcon'''
( number cmdID, number x, number y, number z ) -> nil
'''Spring.AddWorldText'''
( string "text", number x, number y, number z ) -> nil
'''Spring.AddWorldUnit'''
( number unitDefID,
number x, number y, number z,
number team, number facing) -> nil

= Sun =
The dynamic Sun must be invoked via /dynamicsun (Dynamic sun was removed in 104.0, use SetSunDirection, SetSunLighting & SetAtmosphere instead).

'''Spring.SetSunManualControl''' {{removed|104.0}}
( boolean setManualControl ) - > nil

'''Spring.SetSunParameters''' {{removed|104.0}}
( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

'''Spring.SetSunDirection'''
( number dirX, number dirY, number dirZ ) -> nil

'''Spring.SetSunLighting''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following sun lighting parameters:
{ground,unit}{Ambient,Diffuse,Specular}Color and specularExponent
All Colourvalues have to in the Range from 0.0 to 1.0 for all colors and the alpha
Example usage: Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })


'''Spring.SetAtmosphere''' {{new|101.0}}
( table params ) -> nil

It can be used to modify the following atmosphere parameters:
fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})


= Misc =

'''Spring.Reload''' {{new|99.0}}
( string startscript )
start-script is the CONTENT of the [[script.txt]] spring should use to start.

'''Spring.Restart''' {{new|0.79}}
( string commandline_args, string startscript )
-> if this call returns, something went wrong
''commandline_args'' are commandline arguments passed to spring executable

'''Spring.Start''' {{new|102.0}}
( string commandline_args, string startscript )
-> if this call returns, something went wrong
Launches a new Spring instance without terminating the existing one

start-script is the CONTENT of the [[script.txt]] spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to ''commandline_args''

'''Spring.SetWMIcon''' {{new|83.0}}
( string iconFileName ) -> nil
Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo). 
Note: has to be 24bit or 32bit 
Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) 
Note: ''*.bmp'' images have to be in BGR format (default for m$ ones). 
Note: ''*.ico'' images are not supported.

'''Spring.SetWMCaption''' {{new|83.0}}
( string title [, string titleShort = title ] ) -> nil

Sets the window ''title'' for the process (default: "Spring <version>").

The ''shortTitle'' is displayed in the OS task-bar (default: "Spring <version>").

'''NOTE:''' ''shortTitle'' is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. See [http://www.gpwiki.org/index.php/SDL:Tutorials:Initializing_SDL_Libraries#About_the_icon_.28.22Icon_Title.22.29_parameter_on_different_window-managers this site] for more details.

'''Spring.ClearWatchDogTimer''' {{new|83.0}}
( [ string threadName = main ] ) -> nil

'''Spring.SetClipboard''' {{new|98.0}}
( string text) -> nil

= Rendering =
== Preload ==
Allow the engine to load the unit's model (and texture) in a background thread. Wreckages and buildOptions of a unit are automatically preloaded.

'''Spring.PreloadUnitDefModel''' {{new|101.0}}
( number unitDefID ) -> nil

'''Spring.PreloadFetureDefModel''' {{new|101.0}}
( number featureDefID ) -> nil

== Lighting ==
NOTE: these (0.83+) lighting callouts only work when called from unsynced gadgets!

'''Spring.AddMapLight''' (requires MaxDynamicMapLights > 0)
(table lightParams) -> number lightHandle
'''Spring.AddModelLight''' (requires MaxDynamicModelLights > 0)
(table lightParams) -> number lightHandle

'''Spring.UpdateMapLight'''
(number lightHandle, table lightParams) -> boolean success
'''Spring.UpdateModelLight'''
(number lightHandle, table lightParams) -> boolean success

'''Spring.SetMapLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success
'''Spring.SetModelLightTrackingState'''
(number lightHandle, number unitOrProjectileID,
boolean enableTracking, boolean unitOrProjectile) -> boolean success

'''lightParams''' is a table that should contain at least one of the following recognized key/value pairs:

lightParams = {
position = {px, py, pz},
direction = {dx, dy, dz},
ambientColor = {red, green, blue},
diffuseColor = {red, green, blue},
specularColor = {red, green, blue},
intensityWeight = {ambientWeight, diffuseWeight, specularWeight},

-- per-frame decay of ambientColor (spread over TTL frames)
ambientDecayRate = {ambientRedDecay, ambientGreenDecay, ambientBlueDecay},
-- per-frame decay of diffuseColor (spread over TTL frames)
diffuseDecayRate = {diffuseRedDecay, diffuseGreenDecay, diffuseBlueDecay},
-- per-frame decay of specularColor (spread over TTL frames)
specularDecayRate = {specularRedDecay, specularGreenDecay, specularBlueDecay},
-- *DecayType = 0.0 -> interpret *DecayRate values as linear, else as exponential
decayFunctionType = {ambientDecayType, diffuseDecayType, specularDecayType},

radius = number elmos,
fov = number degrees,
ttl = number frames,
priority = number,
ignoreLOS = boolean,
}

= Map =
'''Spring.SetSkyBoxTexture''' {{new|101.0}}
( string texName ) -> nil

'''Spring.SetMapShadingTexture''' {{new|101.0}}
( string texType, string texName ) -> boolean success

<div class="note">Example usage: Spring.SetMapShadingTexture("$ssmf_specular", "name_of_my_shiny_texture")</div>

'''Spring.SetMapSquareTexture'''
( number texSqrX, number texSqrY, string luaTexName ) -> boolean success

'''Spring.SetMapShader''' {{101.0}}
( number standardShaderID, number deferredShaderID ) -> nil

<div class="note">The ID's must refer to valid programs returned by gl.CreateShader. Passing in a value of 0 will cause the respective shader to revert back to its engine default. Custom map shaders that declare a uniform ivec2 named "texSquare" can sample from the default diffuse texture(s), which are always bound to TU 0.</div>

[[category: Lua]]

Lua SyncedCtrl

2018-12-05T12:47:37Z

Gajop: /* Feature Control */

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

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

'''Spring.GameOver''' {{new|83.0}}
( {number allyTeamID1, number allyTeamID2, ...} ) -> nil
Will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed

= RulesParams =
string values are new since 95.0

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

'''Spring.SetFeatureRulesParam''' new since 102.0
( number featureID, string paramName, number|string paramValue [, table losAccess] ) -> nil
see above for further documentation of losAccess

'''Spring.SetTeamRulesParam'''
( number teamID, string paramName, number|string paramValue [, table losAccess] ) -> nil
see above for further documentation of losAccess

'''Spring.SetGameRulesParam'''
( string paramName, number|string paramValue [, table losAccess] ) -> nil
see above for further documentation of losAccess

= Resources =
'''Spring.AddTeamResource'''
( number teamID, string "metal" | "energy", number amount ) -> nil
'''Spring.UseTeamResource'''
( number teamID,
string "metal" | "energy",number amount |
{ metal = number amount, energy = number amount}
) -> nil | boolean hadEnough

'''Spring.SetTeamResource'''
( number teamID, string res, number amount ) -> nil

possible values for res are:
"m" = metal
"e" = energy
"ms" = metal storage
"es" = energy storage


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

'''Spring.ShareTeamResource''' 0.82 and later
( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

= Teams =
'''Spring.SetAlly''' {{new|98.0}}
( number firstAllyTeamID, number secondAllyTeamID, boolean ally ) -> nil

Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID


'''Spring.AssignPlayerToTeam''' {{new|98.0}} {{Sourcelinkhash|7ed9a7e34814c60e5ae16281520cccc4daf3c367}}
( number playerID, number teamID)

'''Spring.SetGlobalLos''' {{new|101.0}}
( number allyTeamID, bool globallos )

= Unit Handling =
'''Spring.CreateUnit''' note: offmap positions are clamped! (you still can use MoveCtrl todo so)
( string "defName" | number unitDefID,
number x, number y, number z,
(number facing | string "facing"),
number teamID
[, boolean build = false]
[, boolean flattenGround = true]
[, number unitID]
[, number builderID]) -> number unitID | nil (meaning unit was not created)

possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
if build is true the unit is created in "being built" state, with buildProgress = 0
unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with
a specific ID.


'''Spring.DestroyUnit'''
( number unitID
[, boolean selfd = false]
[, boolean reclaimed = false]
[, number attackerID ] ) -> nil

selfd := makes the unit act like it self-destructed
reclaimed := don't show any DeathSequences, don't leave a wreckage.
NOTE this does _not_ give back the resources to the team!


'''Spring.TransferUnit'''
( number unitID,
numer newTeamID
[, boolean given = true ] ) -> nil
if given=false, the unit is captured

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

'''Spring.SetUnitTooltip'''
( number unitID, string "tooltip" ) -> nil

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

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

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

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

'''Spring.SetUnitExperience'''
( number unitID, number experience ) -> nil

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

'''Spring.SetUnitCrashing''' {{new|83.0}}
( number unitID, boolean crashing ) -> boolean success

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

'''Spring.SetUnitNeutral'''
( number unitID, boolean neutral ) -> nil

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

'''Spring.SetUnitMaxRange'''
( number unitID, number maxRange ) -> nil

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

'''Spring.SetUnitBlocking''' crushable new in version 85.0
( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil

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

'''Spring.SetUnitMetalExtraction'''    "depth" corresponds to metal extraction rate (value range similar to "extractsMetal" unitDef)
( number unitID, number depth [,number range] ) -> nil

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

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

'''Spring.UnitAttach''' {{new|101.0}}
( number transporterID, number passengerID, number pieceNum ) -> nil

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

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

'''Spring.SetUnitLoadingTransport''' {{new|101.0}}
( number passengerID, number transportID ) -> nil

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

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

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

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

'''Spring.SetUnitArmored''' armorMultiple new in version 0.83.x
( number unitID, boolean armored [, number armorMultiple] ) -> nil

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

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

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,] (*)
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["salvoLeft" = number value,]
["nextSalvo" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}
(*) if you change the range of a weapon with dynamic damage
make sure you use SetUnitWeaponDamages to change dynDamageRange as well.


'''Spring.SetUnitWeaponDamages''' {{new|101.0}}
( number unitID, number weaponNum | "selfDestruct" | "explode", table damages ) -> nil
( number unitID, number weaponNum | "selfDestruct" | "explode", string key, number value ) -> nil
format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}


'''Spring.SetUnitCollisionVolumeData'''
( number unitID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_NUM_TYPES // number of non-disabled collision volume types
};
enum COLVOL_TESTS {
COLVOL_TEST_DISC = 0,
COLVOL_TEST_CONT = 1,
COLVOL_NUM_TESTS = 2 // number of tests
};
enum COLVOL_AXES {
COLVOL_AXIS_X = 0,
COLVOL_AXIS_Y = 1,
COLVOL_AXIS_Z = 2,
COLVOL_NUM_AXES = 3 // number of collision volume axes
};


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

'''Spring.SetUnitTravel'''
( number unitID, number travel [, number travelPeriod] ) -> nil

'''Spring.SetUnitMoveGoal''' used by default commands to get in build-,attackrange etc.
(number unitID, number goalx, number goaly, number goalz
[, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )
{{new|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]

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

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

'''Spring.SetUnitPhysics''' drag new in version 95.0
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
number dragx, number dragy, number dragz,
) -> nil

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

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

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

'''Spring.SetUnitRotation'''
( number unitID, number rotx, number roty, number rotz ) -> nil

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

'''Spring.AddUnitSeismicPing'''
( number unitID, number pingSize ) -> nil

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

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


mpx, mpy, mpz: new middle position of unit

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

relative: are the new coordinates relative to world or unit coordinates?


'''Spring.SetUnitRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

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

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


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

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

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

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

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

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

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

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

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

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

== Unit Resourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil

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


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

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

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

See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.

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

'''Spring.DestroyFeature'''
( number featureID ) -> nil

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

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

'''Spring.SetFeatureResources''' {{new|104.0}}
( number featureID, number metal, number energy [, number reclaimTime [, number reclaimLeft ]] )

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

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

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

{{new|104.0}} Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing {{value|-1}}. The level of progress can now be set via the additional 4th param.

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

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

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

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

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

(like their feature counterparts at [[Lua_SyncedCtrl#Unit_Control]])

'''Spring.SetFeatureMoveCtrl'''
( number featureID [, boolean enable [, number* args]]) to control feature movement
the number* arguments are parsed as follows and all optional
if enable is true:
[, velVector(x,y,z) -- initial velocity for feature
[, accVector(x,y,z) -- acceleration added every frame
]]
if enable is false:
[, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl
[, impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl
[, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl
]]]

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

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

'''Spring.SetFeatureAlwaysVisible'''
( number featureID, boolean enable ) -> nil

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

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

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

check Spring.SetUnitMidAndAimPos for further explanation of the arguments

'''Spring.SetFeatureRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

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

'''Spring.SetFeatureBlocking'''
(number featureID, boolean blocking, boolean collidable) --> boolean

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

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

'''Spring.CallCOBScriptCB''' 
broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

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

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

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

'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
 also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]

= Give Order =
options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation) 
see [[Lua CMDs]] for relevant constants


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

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

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

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

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

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

'''Spring.RemoveGrass'''
( number x, number z ) -> nil

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

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

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

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

'''Spring.SetHeightMapFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
Example code:<code><pre>
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for x=0,Game.mapSizeX, Game.squareSize do
Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
end
end
end)
</pre></code>
'''Spring.AddHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
the terraform argument is a scaling factor:
so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.

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

'''Spring.SetSmoothMeshFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
'''Spring.AddSmoothMesh''' can only be called in SetSmoothMeshFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetSmoothMesh''' can only be called in SetSmoothMeshFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff

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

'''Spring.SetSquareBuildingMask''' {{new|103.0}}
( number x, number z, int mask ) -> nil

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

== MetalAmount ==
'''Spring.SetMetalAmount''' {{new|83.0}}
( number x, number z, number metalAmount)
x & z coords are in worldspace/16 metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua)

= Command Descriptions =
Doesn't work in unsynced code! 

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil

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

{{var|queueing}} is {{new|101.0}} and allows custom commands to be non-queueing (handy for state toggles).

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

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

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

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

an ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag)
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]

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

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

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

possible keys of explosionParams are:
weaponDef = number,
owner = number,
hitUnit = number,
hitFeature = number,
craterAreaOfEffect = number,
damageAreaOfEffect = number,
edgeEffectiveness = number,
explosionSpeed = number,
gfxMod = number,
impactOnly = boolean,
ignoreOwner = boolean,
damageGround = boolean,


'''Spring.SpawnCEG'''
( string "cegname" | number cegID,
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil | boolean success, cegID
cegID new in 95.0

'''Spring.SpawnSFX''' {{new|104.0}}
( number unitID, number sfxID,
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
[, boolean absolute ]
) -> nil | boolean success

Equal to the [[Animation-LuaCallouts#Effects|UnitScript versions of EmitSFX]], but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

= Projectiles =
'''Spring.SpawnProjectile'''
( number weaponDefID, table projectileParams ) -> nil | number projectileID
possible keys of projectileParams are:
pos = {number x, number y, number z},
end = {number x, number y, number z},
speed = {number x, number y, number z},
spread = {number x, number y, number z},
error = {number x, number y, number z},
owner = number,
team = number,
ttl = number,
gravity = number,
tracking = number,
maxRange = number,
startAlpha = number,
endAlpha = number,
model = string,
cegTag = string,


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

'''Spring.SetProjectileTarget'''

Pre 95.0: ( number projectileID,
[ number targetID, string targetTypeStr ] | [ number posX, number posY, number posZ ] )
-> nil | boolean validTarget

Post 95.0: ( number projectileID,
[ number targetID [, number targetType]] | [number posX, number posY, number posZ])
--> nil | boolean validTarget
targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE


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

'''Spring.SetProjectileMoveControl''' (disables engine movecontrol, so lua can fully control the physics)
( number projID, boolean enable ) -> nil
'''Spring.SetProjectilePosition'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileVelocity'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
( number projID ) -> nil
'''Spring.SetProjectileGravity'''
( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle''' {{new|95.0}} Deprecated
( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed''' {{new|95.0}} Deprecated
( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec''' {{new|95.0}} Deprecated
( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
( number projID, string ceg_name ) -> nil

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

'''Spring.SetProjectileAlwaysVisible''' {{new|95.0}}
(number projectileID, boolean alwaysVisible) --> nil

'''Spring.SetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, table damages ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}


[[category: Lua]]

Icontypes.lua

2018-12-03T03:08:01Z

Gajop:

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

==Purpose==
This file defines the icons used to represent units on the minimap and rendered in place of 3d geometry when zoomed out.

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

* {{sourcelink|file=rts/Rendering/IconHandler.cpp}}

==Data Types==
{{DataTypes}}

==Details==

Game developers can set icons for different types of units, (such as land, air, sea), or go so far as to give every unit its own icon. The different types icons will be shown for friendly units, and enemy units within Line Of Sight. For enemy units in radar range Spring will use the 'default' icon.

===IconType Properties===
{{tag
|name = bitmap
|type = string
|default = ""
|description = The location of the custom icon image (not limited to bitmaps!). If it is missing or incorrect, Spring replaces it with the standard radar dot. The bitmap will get blended with the team color, so there is no special team color channel. In order to look nice, the image will need to have an alpha channel for transparency.}}

{{tag
|name = size
|type = float
|default = 1.0
|description = Acts as multiplier for the icon size. The larger the number, the larger the icon will be.}}

{{tag
|name = distance
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance at which the unit will show up as an icon. The larger the number, the further away the camera has to be from the unit for it to turn into an icon.}}

{{tag
|name = radiusAdjust
|type = bool
|default = false
|description = Whether or not the icon should scale with the unit radius.}}

===Assigning IconTypes===
To assign units to a specific icon type, set the {{xtaglink|Gamedev:UnitDefs|iconType}} attribute of their UnitDef to the type name set in <code>icontypes.lua</code> (see [[#Example]])

<pre>
...
iconType = "circle",
...
</pre>

If the {{xtaglink|Gamedev:UnitDefs|iconType}} tag is missing, Spring sets it to the "default" icontype. If the "default" type is not specified, Spring will create it with the default values. Furthermore, enemy units that are within radar range, but not in your Line Of Sight, will be shown as the default icon. Thus if there is a bitmap specified for the "default" icon type it will override the standard radar blip.

==Example==
<pre>
local iconTypes = {
default = {
size = 1,
radiusadjust = true,
},
flag = {
bitmap = "icons/flag.png",
size = 6,
radiusadjust = true,
distance = 100,
},
circle = {
bitmap = "icons/circle.png",
size = 4,
radiusadjust = true,
distance = 100,
},
...
}

return iconTypes
</pre>

[[Category:Gamedata]]

CEG:Defs

2018-12-02T10:26:13Z

Gajop: /* Overall Format */

= CEG Definitions =

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

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

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

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

== CEG Textures ==

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

== Overall Format ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==== Properties ====

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

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

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

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

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

==== Properties ====

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

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

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

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

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

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

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

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

=== CExploSpikeProjectile ===

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

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

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

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

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

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

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

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

=== CHeatCloudProjectile ===

Creates an expanding sprite. Simple but effective.

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

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

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

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

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

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

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

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

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

=== CSimpleParticleSystem ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== CSpherePartSpawner ===

Draws an expanding sphere.

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

==== Properties ====

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

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

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

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

=== CSimpleGroundFlash ===

Draws an expanding ground texture.

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

==== Properties ====

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

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

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

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

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

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

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

==== Properties ====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Examples==


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

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

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

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

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

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

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

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

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

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

[[Category:CEG]]

Resources.lua

2018-12-02T10:25:50Z

Gajop:

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

==Purpose==
This file is used by a game to reference textures for use in [[CEG|Custom Explosion Generators]], as well as various default explosions and other engine textures such as default trees and water etc. Maps have a corresponding file, <code>resources_map.lua</code> which behaves in the same way.

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

* {{sourcelink|file=rts/Rendering/ProjectileDrawer.cpp}} (smoke, groundfx & projectiletextures) <code>resources_map.lua</code> is only read here.

* {{sourcelink|file=rts/Rendering/GroundDecalHandler.cpp}} (scars)
* {{sourcelink|file=rts/Rendering/Env/AdvTreeGenerator.cpp}} (trees)
* {{sourcelink|file=rts/Map/MapInfo.cpp}} (caustics & maps)

==Details==

The engine loads textures from seven subtables within the <code>graphics</code> subtable of the returned resources table. Certain tables are automatically added by the engine if a game is not overriding them, they are numerical arrays whereas all others are key-value associative arrays. Engine defaults which are required to be present are included in the [[#Automatic]] example below.

* <code>caustics</code> - Textures used with bumpmapped water. Automatically added by the engine. 
* <code>smoke</code> - Textures used for engine default smoke. Automatically added by the engine. 
* <code>scars</code> - Textures used for the burn scars left on the map by weapon explosions. Automatically added by the engine. 
* <code>trees</code> - Textures for engine default trees. 
* <code>maps</code> - Base textures in case a map does not provide it's own. 
* <code>groundfx</code> - Game or Map specific textures for [[CEG-Classes#CSimpleGroundFlash|CSimpleGroundFlash]] CEG's as well as engine default explosion [[CEG-Format#groundflash|groundflash]]. 
* <code>projectiletextures</code> - Game or Map specific textures for the other [[CEG-Classes]] as well as engine defaults. This is the only table that is read from <code>resources_map.lua</code> 

==Example==
===Automatic===
The following example (which is becoming a [http://en.wikipedia.org/wiki/De_facto_standard de facto standard]) sets out the engine default textures, and recursively adds any textures from the game's <code>Bitmaps/projectileTextures/</code> and <code>Bitmaps/groundFX/</code> directories, respectively. It will ignore any directories created by [http://en.wikipedia.org/wiki/Apache_Subversion SVN], and can be easily edited to filter out [http://en.wikipedia.org/wiki/Git_(software) git] or any other version control software.

<pre>
local resources = {
graphics = {
-- Spring Defaults
trees = {
bark = 'Bark.bmp',
leaf = 'bleaf.bmp',
gran1 = 'gran.bmp',
gran2 = 'gran2.bmp',
birch1 = 'birch1.bmp',
birch2 = 'birch2.bmp',
birch3 = 'birch3.bmp',
},
maps = {
detailtex = 'detailtex2.bmp',
watertex = 'ocean.jpg',
},
groundfx = {
groundflash = 'groundflash.tga',
groundring = 'groundring.tga',
seismic = 'circles.tga',
},
projectiletextures = {
circularthingy = 'circularthingy.tga',
laserend = 'laserend.tga',
laserfalloff = 'laserfalloff.tga',
randdots = 'randdots.tga',
smoketrail = 'smoketrail.tga',
wake = 'wake.tga',
flare = 'flare.tga',
explo = 'explo.tga',
explofade = 'explofade.tga',
heatcloud = 'explo.tga',
flame = 'flame.tga',
muzzleside = 'muzzleside.tga',
muzzlefront = 'muzzlefront.tga',
largebeam = 'largelaserfalloff.tga',
},
}
}

local VFSUtils = VFS.Include('gamedata/VFSUtils.lua')

local function AutoAdd(subDir, map, filter)
local dirList = RecursiveFileSearch("bitmaps/" .. subDir)
for _, fullPath in ipairs(dirList) do
local path, key, ext = fullPath:match("bitmaps/(.*/(.*)%.(.*))")
if not fullPath:match("/%.svn") then
local subTable = resources["graphics"][subDir] or {}
resources["graphics"][subDir] = subTable
if not filter or filter == ext then
if not map then
table.insert(subTable, path)
else -- a mapped subtable
subTable[key] = path
end
end
end
end
end

-- Add mod projectiletextures and groundfx
AutoAdd("projectiletextures", true)
AutoAdd("groundfx", true)

return resources

</pre>
===External===
{{sourcelink|file=cont/base/springcontent/gamedata/resources.lua}} - Engine base content <code>resources.lua</code>

[[Category:Gamedata]]

Template:Obtaining The Source Code

2018-11-23T00:29:19Z

Gajop:

=== Tarballs ===
'''(For playing online)'''

{{Tarballs}}

=== Git ===
[https://github.com/spring/spring Spring project page at github]

Master repo URI: <code>{{GitCloneUrl}}</code> 
Backup repo: <code>git://git.code.sf.net/p/springrts/code</code>

====Latest Stable (master branch)====
Assuming the GIT command line client is installed, you can clone the repository with
<pre>git clone --recursive git://github.com/spring/spring.git -b master</pre>
and update it with:
<pre>git pull --rebase</pre>

====Bleeding-edge (develop branch)====
This will also allow you to make a patch out of the changes you make to the code, and send it to one of the developers with repository access. If you are new to git and github, you may want to have a look at [http://help.github.com/ this guide] to get you started.

Just as above with a minimal change: {{code|git clone --recursive git://github.com/spring/spring.git -b develop}}
and update with: {{code|git pull --rebase}}

Note: you can switch <code>branches</code> this way:{{code|
# backup your current changes
git stash

# switch branch
git checkout $MY_OTHER_BRANCH

# sometimes needed
# note, it deletes all your unstashed changes and all non-pushed commits on the new branch,
# but it doesn't delete untracked files.
#git reset --hard

# update/sync with remote repo
git pull --rebase

#optional
#git stash pop # reapplies your changes and DELETES the backup
#or
#git stash apply --index 0 # reapplies your changes and keep the backup (see `git stash list`)
}}

====Submodules====
To obtain the submodules you should clone the repository with --recursive as mentioned above.
If you haven't done this, you can execute the following code
{{code|
git submodule sync
git submodule update --init
}}

To update the submodules, you have to execute the same commands again or pull normally.

Building Spring on Linux

2018-11-23T00:28:05Z

Gajop:

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the >=4.6 series should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL2
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
** ''curl''
* Optional (for AI Interfaces, Skirmish AIs and unit tests)
** ''python'' (2.5+)
** ''jdk'' (1.5+)
** ''boost'' (version 1.47 or later)
*** ''chrono''
*** ''filesystem''
*** ''threads''
*** ''system''
*** ''chrono''

== Debian ==

For Jessie (debian 8.0 stable) this should work:

<pre>
sudo apt-get install build-essential zlib1g-dev libfreetype6-dev cmake \
libsdl2-dev libopenal-dev libglew-dev zip libvorbis-dev libxcursor-dev \
libdevil-dev libboost-system1.55-dev libboost-thread1.55-dev \
libboost-regex1.55-dev libboost-serialization1.55-dev \
libboost-program-options1.55-dev libboost-chrono1.55-dev \
libunwind-dev libboost-filesystem1.55-dev \
libboost-signals1.55-dev libboost-test1.55-dev \
xsltproc libfontconfig1-dev libcurl4-openssl-dev
</pre>

=== Ubuntu ===
<pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl2-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread-dev libboost-regex-dev libboost-system-dev \
libboost-program-options-dev libboost-signals-dev \
libboost-chrono-dev libboost-filesystem-dev libunwind8-dev \
default-jdk libcurl4-gnutls-dev
</pre>

to speed up compiling/linking, you can install gold, an alternative linker and when you plan to develop / recompile often ccache :

<pre>sudo apt-get install binutils-gold ccache</pre>

to make ccache useful, the cache size needs to be increased by:

<pre>ccache -M 5G</pre>

to set it to 5GB.

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-2
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre>

Or better you install Spring via [http://springrts.com/wiki/Gentoo_install layman], it will install all dependencies.

== Fedora ==

On Fedora 12-21:

<pre>
sudo yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel libunwind-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL2-devel p7zip
</pre>

On Fedora 8:

<pre>
yum install cmake boost-devel openal-devel SDL2-devel \
DevIL-devel glew-devel libvorbis-devel
</pre>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL2 already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

Try to use [http://idlemoor.github.io/slackrepo/ slackrepo], will search, update and install spring and dependences.

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<pre>
cmake .
make spring
</pre>

Install:

<pre>
make install-spring
</pre>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>~/spring</code> prefix instead of <code>/usr/local</code>, configure like this:

<pre>
cmake -DCMAKE_INSTALL_PREFIX=~/spring .
</pre>
For further ways of customizing your build, have a look at the variables shown with:
<pre>
cmake -LH .
</pre>

For other targets see the output of <code>make help</code>.

= See Also: =
* [[Finalizing_linux_install]]
* [[Troubleshooting_linux]]

[[Category:Compiling]]
[[Category:Linux]]

Coding Standards

2018-11-23T00:25:20Z

Gajop:

This document is not yet finished. 
Please add new points whenever they occur to you.


=Compiler=

Keep in mind that we use gcc (g++) as the main compiler, likewise for linux and windows builds. So be sure your code compiles and works with gcc.

=Directory structure=

http://github.com/spring/spring/blob/master/directories.txt

=Style=

==Indentation==

Use tabs, not spaces. This allows anyone to choose their favorite indentation size.

This implies that you should not use tabs in any other place then indentation. E.g. in the following sample use SPACE to align the constants.
{{code|
#define LOS_INLOS 1
#define LOS_INRADAR 2
}}

Do not attempt to align method parameters in a function call when breaking it over multiple lines. Just indent them using two tabs. Trying to align parameters with the opening parenthesis is unmaintainable: next time someone refactors the code and changes the function name, he has to go through all places it is used this way and waste his time inserting/removing spaces. Of course this applies to similar cases too; in general aligning stuff in such a way that an identifier rename requires realignment of all code using that identifier is bad practice.

==Curly braces==

For top-level types (struct/class/union/enum), braces go on the next line and for function definitions they may go on the same line:
<pre>
class CMyClass
{
};

void MyFunction()
{
}

// fine too
void MyFunction2() {
}
</pre>

Non-top-level types may use the same style as control flow braces.

For control flow, braces go on the same line:
<pre>
if (condition) {
} else {
}
for (int i = 0; i < 10; ++i) {
do {
while (condition2) {
}
} while (condition1);
}
</pre>

For if-else statements (and similar), the following is also fine:
<pre>
if (condition) {
}
else {
}
</pre>

For if's with a single line statement, it is preferred to omit the braces if no braces belonging to another control block follow immediately after the statement:
<pre>
function() { // recommended
if (condition)
statement;
if (condition) {
statement;
}
}
function() { // okay
if (condition) {
statement;
}
if (condition)
statement;
}
</pre>

==Naming==

In Spring engine code, concrete classes are prefixed with C, interfaces with I, structs with S. Both use CamelCase. Functions and methods use CamelCase too. Parameters, fields, variables use pascalCase.
<pre>
// interface
class ISkirmishAI
{
};

// concrete class implementing interface
class CMySkirmishAI : public ISkirmishAI
{
void MyMethod(bool myParam);
int myField;
char* myStr;
};
</pre>

There are two exception to this however:
* helper subclasses do not have any prefix, and
* value types neither (it is "<code>float3</code>", not "<code>Cfloat3</code>").

File-names are usually identical to the name of the main class that is inside, with the prefix stripped off. For example, <code>MySkirmishAI.cpp</code> for class <code>CMySkirmishAI</code>.

==General==

Try to keep code as readable as possible. This means, do not write very long functions, but split the problem in multiple functions. Use identifier names with an actual meaning as opposed to a,b,c, etc. The point is to allow other devs to "read" the code, as opposed to "figure it out".

Keep classes dedicated to a single function, do not create big monolithic classes which no one understands.

Insert a blank line to separate two parts of a function that have very distinct functionality. Otherwise try to keep the code compact with as few lines as possible, but avoid putting multiple statements on a single line and do not write lines more than 120 characters long.

We use comment tags (TODO, FIXME, ..) as described [http://en.wikipedia.org/wiki/Comment_%28computer_programming%29#Tags here].

On pointer or reference types, try to keep the respective symbol adjacent to the type:
<pre>
// better
char* myStr;
float* MyMethod(const char& myParam);
int* MyVar = (int*)OtherVar;
void MyMethod(const std::string& myParam);
// okay
char *myStr;
float *MyMethod(const char &myParam);
int *MyVar = (int *)OtherVar;
void MyMethod(const std::string &myParam);
// bad
char * myStr;
float * MyMethod(const char & myParam);
int * MyVar = (int *)OtherVar;
void MyMethod(const std::string & myParam);
</pre>

If there is no type, keep the symbol adjacent to the variable name:
<pre>
// better
char myChar, *myCharPointer, **myCharDoublePointer;
// okay
char myChar, * myCharPointer, ** myCharDoublePointer;
// bad
char myChar, * myCharPointer, * * myCharDoublePointer;
</pre>

For items separated by commas, e.g. function parameters and enums, keep one space after each comma:
<pre>
// good
void MyFun(int a, int b, int c);
int MyArr[3] = {1, 2, 3};
// bad
void MyFun(int a,int b,int c);
int MyArr[3] = {1,2,3};
</pre>

For operators, e.g. =, + and -, keep one space on each side. Avoid using extra spaces around parentheses:
<pre>
// good
void i = (1 - b);
void j = ((1 / b) + 5) * c;
// bad
void i=( 1-b );
void j=((1/b)+5)*c;
</pre>

==External dependencies==

Do not introduce new external dependencies without good motivation. The past has proven there are quite some libraries which just suck, do not build on some platform, are too buggy, make code unreadable, etc. If you really need to add a new dependency, be sure it is cross platform, and favor dependencies that are already packages in the major distributions like [http://www.debian.org/distrib/packages Debian] or [http://packages.ubuntu.com/ Ubuntu].

When working on Linux, remember to (get someone to) compile the dependency on Windows, both for MinGW and MSVC.

=Sources=

(This is good material to at least skim through; the first one is a must have for every serious programmer.)

* [http://en.wikipedia.org/wiki/Code_Complete Code complete 2] (commercial book)
* [http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf Philips Medical Systems - Coding Standard: C#] (free online book)

[[Category:Engine Dev]]

RapidTools

2018-11-19T00:58:34Z

Gajop:

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

Made by det

=Source=
https://github.com/spring/pr-downloader

=Bugs=
https://github.com/spring/pr-downloader/issues

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

Additional setup instructions: https://springrts.com/wiki/Admin:Rapid

=Tool description=
==AddZip==

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

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

==BuildGit==

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

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

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

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

for details see the source-code:
https://github.com/spring/pr-downloader/blob/master/src/Streamer.cpp#L94

==MakeZip==

can create a zip from a .sdp

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

===Notes===

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

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

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

[[Category: Download Systems]]

RapidTools

2018-11-19T00:58:00Z

Gajop:

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

Made by det

=Source=
https://github.com/spring/pr-downloader

=Bugs=
https://github.com/spring/pr-downloader/issues

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

Additional setup instructions: https://springrts.com/wiki/Admin:Rapid

=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/pr-downloader/blob/master/src/Streamer.cpp#L94

==MakeZip==

can create a zip from a .sdp

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

===Notes===

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

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

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

[[Category: Download Systems]]

Lua Libraries

2018-11-11T04:21:23Z

Gajop:

=Lua libraries=
This page lists all common Lua libraries that can be used in Spring game and map archives.

Libraries:
* [https://github.com/gajop/analytics analytics]: Usage analytics reporting
* [https://github.com/jk3064/chiliui ChiliUI]: UI framework [[Chili | docs]]
* [https://github.com/gajop/chilifx ChiliFX]: Chili effects
* [https://github.com/gajop/chotify Chotify]: Notification library in Chili
* [https://github.com/jk3064/Custom-Unit-Shader-Framework Custom Unit Shader Framework]: Unit rendering with shaders
* [https://github.com/gajop/i18n i18n]: Translations library
* [https://github.com/gajop/liblobby LibLobby]: Spring Lobby protocol library
* [https://github.com/gajop/Lua-Class-System LCS]: OOP (classes) in Lua
* [https://github.com/jk3064/lups LUPS]: Lua Particle System for Spring [[LUPS | docs]]
* [https://github.com/gajop/springmon springmon]: Spring file monitor and autoreloader
* [https://github.com/gajop/spring-wrapper-connector spring-wrapper-connector]: Wrapper program communication provider

==Single file libraries==
There is also a number of single file libraries that don't have their own repository but can technically still be considered libraries.

Library files:
* [https://github.com/SpringMCLegacy/SpringMCLegacy/blob/master/LuaRules/Gadgets/api_vector.lua Vector]: Small utility for vector operations
* [https://github.com/Spring-SpringBoard/SpringBoard-Core/blob/master/libs_sb/json.lua JSON]: Serializing to the JSON format
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_delay.lua Delay]: Delaying gadget calls
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/network.lua Network]: Delta compression for binary strings
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/camera.lua Camera]: Camera state serialization
* Deferred rendering [http://imolarpg.dyndns.org/svn/branches/BAR/shaders/deferred_lighting.glsl Shader] & [http://imolarpg.dyndns.org/svn/branches/BAR/luaui/widgets/gfx_deferred_rendering.lua Widget]: Deferred rendering (projectile) based lights

===Misc===
* {{forumlink|topic=28341|title=ChangePiece}} - Switch piece geometry

=== Additional resources ===

Some additional libraries can be found using Github topics, such as [https://github.com/topics/springrts-lib springrts-lib] and [https://github.com/topics/springrts springrts]

[[Category:Lua]] [[Category:Libraries]]

Gamedev:Main

2018-11-11T04:19:25Z

Gajop: /* Lua API & Libraries (excerpt) */

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

= Game Development =
This information is meant to help newcomers learn how to develop their own games for the Spring Engine. If you are interested in creating maps for Spring, see [[Mapdev:Main]].

= Templates & Examples =
* [[Gamedev:SpringABC|SpringABC]] - A hierarchical set of empty template games, without examples
* [[SpringTutorialGame|Spring Tutorial Game]] - A tutorial template game with full examples
* [[Gamedev:PublicRepos|Public Repos]] - Publicly readable Spring game code repositories

= Technical Documentation =
== GameData ==
* [[Armordefs.lua]] - armor classes
* [[Icontypes.lua]] - strategic unit icons
* [[Modinfo.lua]] - game identifier file (name, version,...)
* [[Modrules.lua]] - Global game variables
* [[Movedefs.lua]] - MoveClasses for pathfinding
* [[Resources.lua]] - index file for textures
* [[Sidedata.lua]] - playable factions/races/sides
* [[Sounds.lua]] - index file for sounds
* [[Messages.lua]] - Team death messages {{new|95.0}}:deprecated

== Definition Files ==
* [[Gamedev:UnitDefs]] - define the attributes of units
* [[Gamedev:WeaponDefs]] - define the attributes of weapons/projectiles
* [[Gamedev:FeatureDefs]] - define the attributes of static map features and wrecks
* [[CEG:Main]] Particle effects (explosions etc)

== Lua API & Libraries (excerpt) ==
* [[Lua_Scripting|Lua API Documentation]]
* [[Lua_Libraries|Lua Libraries]]

== Animation of units ==
Lua Animations (LUS)
*[[Animation-LuaScripting]]
**[[Animation-LuaCallins]]
**[[Animation-LuaCallouts]]
**[[Animation-CobLuaDifferences]]

COB Animations (Antiquated)
*[[Animation-CobOverview]]
**[[Animation-CobAnimation]]
**[[Animation-CobCallins]]
**[[Animation-CobConstants]]
**[[Animation-CobThreads]]
**[[Animation-CobHitByWeaponID]]
**[[Lua-LuaCOB]] - how to interface COB with LUA
**[[CEG_For_Units|Game Development:Calling basic CEGs from COB]]
**{{forumlink|topic=7457|title=GPL COB Examples}}

== Models & Textures ==
* [[About_s3o|.s3o]]
* [[Assimp]]
** [[3DModels:AssimpWorkflow]]
* [[3DModels:Textures]]
* [[Shaders:CustomUnitShadingFramework]]
** [[Shaders:PBRShaders]]

== Misc ==
* [[Gamedev:DebugDrawModes]]
* [[Gamedev:Archives]] - packing game/map
* [[Gamedev:Buildpics]]
* [[Gamedev:CollisionVolumes]]
* [[Gamedev:Glossary]]
* [[Gamedev:MouseCursors]]
* [[Gamedev:Sidepics]]
* [[Gamedev:Structure]]
* [[VirtualFileSystem]]

= Tools =
== In-Game Tools ==
*[http://springboard-core.readthedocs.io/en/latest/ SpringBoard] - Powerful map and scenario editor
*[[Map Making: Feature Placer|Feature Placer]] - A Map Feature & NPC Unit Placement Tool

== External Tools ==
* [[Upspring]]
* [[Map,_Mod,_And_Unit_Development_Programs|Development Tools]]

= Engine Related =
* [[Download_Testing]] - Test the compatibility of your game on upcoming versions of the Spring engine.

* [[EngineChangelogForContentDevs]] - New engine versions sometimes require games to adjust. A list of common problems.

* [[EngineSource_for_GameDevs]] - Notes about the engine source, from modding point of view.

= Tutorials =
== Tips, Tricks & Testing ==
[[TestingYourGame|These tricks and commands]] are useful for testing or debugging.

== Game Development Tutorials ==
*[[The Complete Guide To Making A Spring Game]] - A fairly comprehensive getting started tutorial.
*[http://springrts.com/phpbb/viewtopic.php?f=14&t=26409| Porting TA content to Spring]
*<strike>[[Simple Mod Tutorial|Simple Game Tutorial]]</strike> - needs to be updated

==Modelling Tutorials==
'''Wings3D'''
* [[3DModels:Wings3DTutorial]]
* [http://springrts.com/phpbb/viewtopic.php?t=10612 Wings UV Mapping Tutorial]

'''Blender'''
* [[TutorialBlenderWorkFlow|Blender Workflow Tutorial]]

'''3DS Max'''
* [http://springrts.com/phpbb/viewtopic.php?t=10503 Runecrafter's 3DS Max UV Mapping Tutorial]

==Texturing Tutorials==
* [http://springrts.com/phpbb/viewtopic.php?f=57&t=22392 DDS Textures: How To]
* [http://springrts.com/phpbb/viewtopic.php?t=10947 Greeble Tutorial 1]
* [http://springrts.com/phpbb/viewtopic.php?f=9&t=12356 Greeble Tutorial 2]

=Misc=
* [[Ren'Py]]: a visual novel engine that can be used with Spring
* <strike>[http://answers.springlobby.info/ Q&A Site for the Spring Engine]</strike> Currently down.

[[Category:Game Dev]]

Lua WeaponDefs

2018-11-10T17:51:33Z

Gajop:

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

The '''WeaponDefs[]''' table holds all information about the weapons used in a game.

Works the same way as [[Lua_UnitDefs]] except the tables are called '''WeaponDefs[]''' and '''WeaponDefNames[]'''

Note: Its entries are metatables, so you can't use the pairs() iterator on them, use this instead:
<pre>
for id,weaponDef in pairs(WeaponDefs) do
for name,param in weaponDef:pairs() do
Spring.Echo(name,param)
end
end
</pre>

==Naming==
If a unit named "tank" has a weapon named "gun", the resulting <code>name</code> will be "tank_gun" and you can get this weaponDefID like:

<code>local gunID = WeaponDefNames["tank_gun"].id</code>

==Example==
For a more detailed overview of tag definitions look at
[[Gamedev:WeaponDefs]] or look directly at the source at
https://github.com/spring/spring/blob/5f08624585852b8c8dfd1a16d020ae530269dc09/rts/Sim/Weapons/WeaponLoader.cpp

In key = value format, where WeaponDefs[weaponDefID].key==value, with subtables at the end.
<pre>
accuracy = 0,
avoidFeature = false,
avoidFriendly = true,
avoidNeutral = false,
beamTTL = 0,
beamburst = false,
beamtime = 0.10000000149012,
bouncerebound = 1,
canAttackGround = true,
cegTag = "",
collisionSize = 0.050000000745058,
coverageRange = 0,
craterAreaOfEffect = 0,
cylinderTargeting = 1,
cylinderTargetting = 1,
damageAreaOfEffect = 6,
dance = 0,
description = "J7Laser",
duration = 0.050000000745058,
dynDamageExp = 0,
dynDamageInverted = false,
dynDamageMin = 0,
dynDamageRange = 0,
edgeEffectiveness = 0.99000000953674,
energyCost = 0,
explosionSpeed = 3.233583688736,
exteriorShield = false,
fireStarter = 0.69999998807907,
flightTime = 0,
gravityAffected = false,
groundbounce = false,
groundslip = 1,
heightBoostFactor = -1,
heightMod = 1,
highTrajectory = 2,
id = 220,
impactOnly = true,
intensity = 0.89999997615814,
interceptSolo = true,
interceptedByShieldType = 2,
interceptor = 0,
isShield = false,
largeBeamLaser = false,
laserHardStop = false,
leadBonus = 0,
leadLimit = -1,
manualFire = false,
maxAngle = 0.95873802900314,
metalCost = 0,
minIntensity = 0,
movingAccuracy = 0,
myGravity = 0,
name = "corcom_armcomlaser",
noAutoTarget = false,
noEnemyCollide = false,
noExplode = false,
noFeatureCollide = false,
noFriendlyCollide = false,
noGroundCollide = false,
noNeutralCollide = false,
noSelfDamage = true,
numbounce = -1,
onlyForward = false,
paralyzer = false,
predictBoost = 0,
projectiles = 1,
projectilespeed = 30.000001907349,
proximityPriority = 1,
range = 300,
reload = 0.40000000596046,
salvoDelay = 0.10000000149012,
salvoSize = 1,
selfExplode = false,
shieldAlpha = 0.20000000298023,
shieldBadColorB = 0.5,
shieldBadColorG = 0.5,
shieldBadColorR = 1,
shieldEnergyUse = 0,
shieldForce = 0,
shieldGoodColorB = 1,
shieldGoodColorG = 0.5,
shieldGoodColorR = 0.5,
shieldInterceptType = 0,
shieldMaxSpeed = 0,
shieldPower = 0,
shieldPowerRegen = 0,
shieldPowerRegenEnergy = 0,
shieldRadius = 0,
shieldRechargeDelay = 0,
shieldRepulser = false,
size = 2.1875,
sizeGrowth = 0.5,
smartShield = false,
soundTrigger = true,
sprayAngle = 0,
startvelocity = 0.0099999997764826,
stockpile = false,
stockpileTime = 30,
sweepFire = false,
targetBorder = 0,
targetMoveError = 0.050000000745058,
targetable = 0,
tdfId = 0,
tracks = false,
trajectoryHeight = 0,
turnRate = 0,
turret = true,
type = "BeamLaser",
uptime = 0,
visibleShield = false,
visibleShieldHitFrames = 0,
visibleShieldRepulse = false,
waterWeapon = false,
waterbounce = false,
weaponAcceleration = 0,
wobble = 0,
customParams = {},
damages = {
craterBoost = 0,
...
},
fireSound = {
[1] = {
id = 36,
name = "lasrfir1",
volume = 6.1237244606018,
},
...
},
hitSound = {
[1] = {
id = -1,
name = "",
volume = 6.1237244606018,
},
...
},
visuals = {
alphaDecay = 1,
alwaysVisible = false,
beamDecay = 1,
beamWeapon = false,
color2B = 1,
color2G = 1,
color2R = 1,
colorB = 0,
colorG = 0,
colorR = 1,
coreThickness = 0.10000000149012,
laserFlareSize = 7,
modelName = "",
noGap = true,
pulseSpeed = 1,
scrollSpeed = 5,
separation = 1,
sizeDecay = 0,
smokeTrail = false,
stages = 5,
thickness = 2,
tileLength = 200,
},
</pre>

[[category: Lua]]

Lua UnitDefs

2018-11-10T17:50:54Z

Gajop:

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

==What is this==
The '''UnitDefs[]''' table holds information about the unit'''types''' used in the game. It is indexed by a number, and normally refered to as unitDefID. It is read-only. To access its tags you write, for example,
<pre>
UnitDefs[unitDefID].name
</pre>

'''Note:''' 
The name of the keys often vary from the ones in the [[Gamedev:UnitDefs]] files.
For example ''maxDamage'' is named ''health''.

==UnitDefs reverse lookup: UnitDefNames==
The '''UnitDefNames[]''' table holds the unitdefs and can be used to get the unitdef table for a known unitname:
<pre>
local unitDef = UnitDefNames["supertank"]
</pre>

==Print all unitDefs==
This example code prints all unitdefs, with all keys and their values (but not their subtables).
<pre>
for id,unitDef in pairs(UnitDefs) do
for name,param in unitDef:pairs() do
Spring.Echo(name,param)
end
end
</pre>
Note that unitDef is a metatable, and requires the special iterator unitDef:pairs()

==Useful keys/snippets==
<code> UnitDefs[unitDefID].id </code> - gives back the unitDefID

<code> UnitDefs[unitDefID].name </code> - the internal unit name

<code> UnitDefs[unitDefID].humanName </code> - the displayed unit name

<code>UnitDefs[unitDefID].weapons</code> - See [[Lua_WeaponDefs]], <code>UnitDefs[unitDefID].weapons[1].weaponDef</code> returns the weaponDefID of the units first weapon, which apppears in the WeaponsDef table as <code>WeaponDefs[weaponDefID]</code>.

To read [[Gamedev:UnitDefs#customParams|custom parameters]] use:
<pre>
local myCustomParameters = UnitDefs[unitDefID].customParams
if (myCustomParameters) then
blub = myCustomParameters.blubfactor
end
</pre>
Key-names of the customParams table written must be lowercase and their values can only be strings.

===Types of Units===
Sometimes one wants to check type of unit. Like is it a factory, is it a transport and so on.
Complete list: <ref>''Spring 95, commit message'',{{Sourcelinkhash|4e58b8b0f7af04065878d34e5e17523246739b0c}}</ref>

*isTransport
*isImmobile
*isBuilding
*isBuilder
*isMobileBuilder
*isStaticBuilder
*isFactory
*isExtractor
*isGroundUnit
*isAirUnit
*isStrafingAirUnit
*isHoveringAirUnit
*isFighterAirUnit
*isBomberAirUnit

==Example UnitDef table==
In the form of key = value, where UnitDefs[unitDefID].key = value, with subtables at the bottom.

<pre>
activateWhenBuilt = true,
airLosRadius = 5.2734375,
airStrafe = true,
armorType = 3,
armoredMultiple = 1,
autoHeal = 2.5,
bankingAllowed = true,
buildDistance = 112,
buildRange3D = false,
buildSpeed = 300,
buildTime = 75000,
builder = false,
buildingDecalDecaySpeed = 0.10000000149012,
buildingDecalSizeX = 4,
buildingDecalSizeY = 4,
buildingDecalType = -1,
buildpicname = "CORCOM.DDS",
canAssist = true,
canAttack = true,
canAttackWater = true,
canBeAssisted = true,
canCapture = true,
canCloak = true,
canCrash = false,
canDGun = false,
canDropFlare = false,
canFight = true,
canFireControl = true,
canFly = false,
canGuard = true,
canKamikaze = false,
canLoopbackAttack = false,
canManualFire = true,
canMove = true,
canParalyze = false,
canPatrol = true,
canReclaim = true,
canRepair = true,
canRepeat = true,
canRestore = true,
canResurrect = false,
canSelfD = true,
canSelfRepair = false,
canStockpile = false,
canSubmerge = false,
cantBeTransported = false,
capturable = true,
captureSpeed = 900,
cloakCost = 100,
cloakCostMoving = 1000,
cloakTimeout = 128,
cobID = -1,
collide = true,
cost = 3111.4499511719,
crashDrag = 0.0049999998882413,
deathExplosion = "commander_blast",
decloakDistance = 50,
decloakOnFire = true,
decloakSpherical = true,
dlHoverFactor = -1,
energyCost = 26667,
energyMake = 25,
energyStorage = 0,
energyUpkeep = 0,
extractRange = 0,
extractsMetal = 0,
factoryHeadingTakeoff = true,
fallSpeed = 0.20000000298023,
fireState = -1,
flankingBonusDirX = 0,
flankingBonusDirY = 0,
flankingBonusDirZ = 1,
flankingBonusMax = 1.8999999761581,
flankingBonusMin = 0.89999997615814,
flankingBonusMobilityAdd = 0.0099999997764826,
flankingBonusMode = 1,
flareDelay = 0.30000001192093,
flareDropVectorX = 0,
flareDropVectorY = 0,
flareDropVectorZ = 0,
flareEfficiency = 0.5,
flareReloadTime = 5,
flareSalvoDelay = 0,
flareSalvoSize = 4,
flareTime = 90,
floatOnWater = false,
floater = false,
frontToSpeed = 0.10000000149012,
fullHealthFactory = false,
hasShield = false,
health = 3000,
height = 50,
hideDamage = true,
highTrajectoryType = 0,
holdSteady = false,
hoverAttack = false,
humanName = "Commander",
iconType = "corcom.user",
id = 261,
idleAutoHeal = 2.5,
idleTime = 1800,
isAirBase = false,
isAirUnit = false,
isBomberAirUnit = false,
isBuilder = true,
isBuilding = false,
isCommander = false,
isExtractor = false,
isFactory = false,
isFeature = false,
isFighterAirUnit = false,
isFirePlatform = false,
isGroundUnit = true,
isHoveringAirUnit = false,
isImmobile = false,
isMobileBuilder = true,
isStaticBuilder = false,
isStrafingAirUnit = false,
isTransport = false,
jammerRadius = 0,
kamikazeDist = 0,
kamikazeUseLOS = false,
leaveTracks = false,
levelGround = true,
loadingRadius = 220,
losHeight = 40,
losRadius = 14.0625,
makesMetal = 0,
mass = 5000,
maxAcc = 0.18000000715256,
maxAileron = 0.014999999664724,
maxBank = 0.80000001192093,
maxCoverage = 0,
maxDec = 1.125,
maxElevator = 0.0099999997764826,
maxFuel = 0,
maxHeightDif = 14.558809280396,
maxPitch = 0.44999998807907,
maxRepairSpeed = 300,
maxRudder = 0.0040000001899898,
maxSlope = -1,
maxThisUnit = 32000,
maxWaterDepth = 35,
maxWeaponRange = 300,
maxx = 17.423709869385,
maxy = 48.386325836182,
maxz = 14.10532283783,
metalCost = 2667,
metalMake = 1.5,
metalStorage = 0,
metalUpkeep = 0,
midx = 0.66120779514313,
midy = 19,
midz = 1.7122877836227,
minAirBasePower = 0,
minCollisionSpeed = 1,
minWaterDepth = -10000000,
minx = -16.537784576416,
miny = 0.058725833892822,
minz = -9.709508895874,
moveState = -1,
myGravity = 0.40000000596046,
name = "corcom",
nanoColorB = 0.20000000298023,
nanoColorG = 0.69999998807907,
nanoColorR = 0.20000000298023,
needGeo = false,
onOffable = false,
power = 3111.4499511719,
primaryWeapon = 2,
rSpeed = 0,
radarRadius = 700,
radius = 22,
reclaimSpeed = 300,
reclaimable = false,
refuelTime = 5,
releaseHeld = false,
reloadTime = 1,
repairSpeed = 300,
repairable = true,
resurrectSpeed = 300,
scriptName = "corcom.cob",
scriptPath = "corcom.cob",
seismicRadius = 0,
seismicSignature = 0,
selfDCountdown = 5,
selfDExplosion = "commander_blast",
shieldPower = -1,
showNanoFrame = true,
showNanoSpray = true,
showPlayerName = true,
slideTolerance = 0,
sonarJamRadius = 0,
sonarRadius = 300,
sonarStealth = false,
speed = 37.5,
speedToFront = 0.070000000298023,
startCloaked = false,
stealth = false,
strafeToAttack = false,
targfac = false,
techLevel = 0,
terraformSpeed = 1500,
tidalGenerator = 0,
tooltip = "Commander",
totalEnergyOut = 25,
trackOffset = 0,
trackStrength = 0,
trackStretch = 1,
trackType = -1,
trackWidth = 32,
transportByEnemy = false,
transportCapacity = 0,
transportMass = 100000,
transportSize = 0,
transportUnloadMethod = 0,
turnInPlace = true,
turnInPlaceSpeedLimit = 0.82499998807907,
turnRadius = 500,
turnRate = 1133,
type = "",
unitFallSpeed = 0,
upright = true,
useBuildingGroundDecal = false,
useSmoothMesh = true,
verticalSpeed = 3,
wantedHeight = 0,
waterline = 0,
windGenerator = 0,
wingAngle = 0.079999998211861,
wingDrag = 0.070000000298023,
wreckName = "corcom_dead",
xsize = 4,
zsize = 4,

buildOptions = {
[1] = unitDefID1,
[2] = unitDefID2,
...
},
collisionVolume = {
boundingRadius = 1.0893974967364e-026,
defaultToFootPrint = false,
defaultToPieceTree = false,
defaultToSphere = false,
offsetX = 0,
offsetY = 1,
offsetZ = 1.089395031546e-026,
scaleX = 6.4911419586111e-027,
scaleY = 1.9340968033141e-038,
scaleZ = 1.0894122878784e-026,
type = "ellipsoid",
},
customParams = {
...
},
modCategories = {
all = true,
commander = true,
notair = true,
...
},
model = {
name = "CORCOM.s3o",
path = "objects3d/CORCOM.s3o",
type = "s3o",
textures = {
tex1 = "Core_color.dds",
tex2 = "Core_other.dds",
},
},
moveDef = {
crushStrength = 50,
depth = 5000,
depthMod = 0,
family = "kbot",
heatMapping = false,
heatMod = 0.0041666668839753,
heatProduced = 60,
id = 6,
maxSlope = 0.41221469640732,
name = "akbot2",
slopeMod = 9.6801977157593,
type = "ground",
xsize = 3,
zsize = 3,
},
noChaseCategories = {
all = true,
...
},
sounds = {
activate = {},
arrived = {},
build = {
[1] = {
id = 208,
name = "nanlath2",
volume = 1,
},
...
},
...
},
weapons = {
[1] = {
fuelUsage = 0,
mainDirX = 0,
mainDirY = 0,
mainDirZ = 0.99999564886093,
maxAngleDif = -1,
slavedTo = 0,
weaponDef = 221,
badTargets = {
vtol = true,
},
onlyTargets = {
all = true,
antiemg = true,
...
},
},
...
},
</pre>

==Unit/Weapon damages and armor classes==

For details on how to extract which units/weapons target/damage which units, see https://springrts.com/phpbb/viewtopic.php?f=44&t=34382&p=575738#p575738 (TODO: migrate info to wiki).

==How to save unitDef tables to file==
To save all unitDefs to a file, including all tables, you can use
<pre>
local unitDef = UnitDefs[unitDefID]
local t = {}
for k,v in unitDef:pairs() do
t[k] = v
end
table.save(t, "lua_unitDef_" .. unitDef.name .. ".lua", "-- generated by table.save")
</pre>
The special iterator is needed because metatables. See https://springrts.com/phpbb/viewtopic.php?f=67&t=33778 for a widget to regenerate the example defs.

[[category: Lua]]

----
<references/>

Lua FeatureDefs

2018-11-10T17:49:14Z

Gajop:

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

The FeatureDefs[] table holds all information about the features used in a game.

Works the same way as [[Lua_UnitDefs]] except the tables are called '''FeatureDefs[]''' and '''FeatureDefNames[]'''

==Looping==
Note: Its entries are metatables, so you can't use the pairs() iterator on them, use this instead:
<pre>
for id,featureDef in pairs(FeatureDefs) do
for name,param in featureDef:pairs() do
Spring.Echo(name,param)
end
end
</pre>

==Example==
In key = value form, where FeatureDefs[featureDefID].key==value, with subtables at the end.
<pre>
autoreclaim = true,
blocking = true,
burnable = false,
deathFeatureID = 2,
destructable = true,
drawType = 0,
drawTypeString = "model",
energy = 0,
floating = false,
geoThermal = false,
height = 0,
id = 1,
mass = 4205.400390625,
maxHealth = 16290,
maxx = -10000,
maxy = -10000,
maxz = -10000,
metal = 6441,
midx = 0,
midy = 0,
midz = 0,
minx = 10000,
miny = 10000,
minz = 10000,
modelname = "objects3d/AAFUS_DEAD.s3o",
name = "aafus_dead",
noSelect = true,
radius = 0,
reclaimTime = 38646,
reclaimable = true,
resurrectable = -1,
smokeTime = 300,
tooltip = "Advanced Fusion Reactor Wreckage",
upright = false,
xsize = 10,
zsize = 8,
collisionVolume = {
boundingRadius = 5.8736290375751e-026,
defaultToFootPrint = false,
defaultToPieceTree = false,
defaultToSphere = false,
offsetX = 0,
offsetY = 1,
offsetZ = 6.3954851782821e-026,
scaleX = 6.1349811206651e-026,
scaleY = 1.9340968033141e-038,
scaleZ = 6.3955048998047e-026,
type = "ellipsoid",
},
customParams = {
...
},
</pre>

[[category: Lua]]

Lua Libraries

2018-10-14T12:57:14Z

Gajop: /* Lua libraries */

=Lua libraries=
This page lists all common Lua libraries that can be used in Spring game and map archives.

Libraries:
* [https://github.com/gajop/analytics analytics]: Usage analytics reporting
* [https://github.com/jk3064/chiliui ChiliUI]: UI framework [[Chili | docs]]
* [https://github.com/gajop/chilifx ChiliFX]: Chili effects
* [https://github.com/gajop/chotify Chotify]: Notification library in Chili
* [https://github.com/jk3064/Custom-Unit-Shader-Framework Custom Unit Shader Framework]: Unit rendering with shaders
* [https://github.com/gajop/i18n i18n]: Translations library
* [https://github.com/gajop/liblobby LibLobby]: Spring Lobby protocol library
* [https://github.com/gajop/Lua-Class-System LCS]: OOP (classes) in Lua
* [https://github.com/jk3064/lups LUPS]: Lua Particle System for Spring [[LUPS | docs]]
* [https://github.com/gajop/springmon springmon]: Spring file monitor and autoreloader
* [https://github.com/gajop/spring-wrapper-connector spring-wrapper-connector]: Wrapper program communication provider

==Single file libraries==
There is also a number of single file libraries that don't have their own repository but can technically still be considered libraries.

Library files:
* [https://github.com/SpringMCLegacy/SpringMCLegacy/blob/master/LuaRules/Gadgets/api_vector.lua Vector]: Small utility for vector operations
* [https://github.com/Spring-SpringBoard/SpringBoard-Core/blob/master/libs_sb/json.lua JSON]: Serializing to the JSON format
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_delay.lua Delay]: Delaying gadget calls
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/network.lua Network]: Delta compression for binary strings
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/camera.lua Camera]: Camera state serialization
* Deferred rendering [http://imolarpg.dyndns.org/svn/branches/BAR/shaders/deferred_lighting.glsl Shader] & [http://imolarpg.dyndns.org/svn/branches/BAR/luaui/widgets/gfx_deferred_rendering.lua Widget]: Deferred rendering (projectile) based lights

=== Additional resources ===

Some additional libraries can be found using Github topics, such as [https://github.com/topics/springrts-lib springrts-lib] and [https://github.com/topics/springrts springrts]

[[Category:Lua]] [[Category:Libraries]]

Lua Libraries

2018-10-13T17:14:51Z

Gajop: sorted libs alphabetically and added two new ones

=Lua libraries=
This page lists all common Lua libraries that can be used in Spring game and map archives.

If you want to extend this page, please only add working, well-documented libraries and frameworks, and their official links.
It's possible to add early work, but try to make sure it has some documentation, and keep it in its separate repository.

Libraries:
* [https://github.com/gajop/analytics analytics]: Usage analytics reporting
* [https://github.com/jk3064/chiliui ChiliUI]: UI framework [[Chili | docs]]
* [https://github.com/gajop/chilifx ChiliFX]: Chili effects
* [https://github.com/gajop/chotify Chotify]: Notification library in Chili
* [https://github.com/jk3064/Custom-Unit-Shader-Framework Custom Unit Shader Framework]: Unit rendering with shaders
* [https://github.com/gajop/i18n i18n]: Translations library
* [https://github.com/gajop/liblobby LibLobby]: Spring Lobby protocol library
* [https://github.com/gajop/Lua-Class-System LCS]: OOP (classes) in Lua
* [https://github.com/jk3064/lups LUPS]: Lua Particle System for Spring [[LUPS | docs]]
* [https://github.com/gajop/springmon springmon]: Spring file monitor and autoreloader
* [https://github.com/gajop/spring-wrapper-connector spring-wrapper-connector]: Wrapper program communication provider

==Single file libraries==
There is also a number of single file libraries that don't have their own repository but can technically still be considered libraries.

Library files:
* [https://github.com/SpringMCLegacy/SpringMCLegacy/blob/master/LuaRules/Gadgets/api_vector.lua Vector]: Small utility for vector operations
* [https://github.com/Spring-SpringBoard/SpringBoard-Core/blob/master/libs_sb/json.lua JSON]: Serializing to the JSON format
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_delay.lua Delay]: Delaying gadget calls
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/network.lua Network]: Delta compression for binary strings
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/camera.lua Camera]: Camera state serialization
* Deferred rendering [http://imolarpg.dyndns.org/svn/branches/BAR/shaders/deferred_lighting.glsl Shader] & [http://imolarpg.dyndns.org/svn/branches/BAR/luaui/widgets/gfx_deferred_rendering.lua Widget]: Deferred rendering (projectile) based lights

[[Category:Lua]] [[Category:Libraries]]

Lua Libraries

2018-10-13T10:45:38Z

Gajop: better json.lua link

=Lua libraries=
This page lists all common Lua libraries that can be used in Spring game and map archives.

If you want to extend this page, please only add working, well-documented libraries and frameworks, and their official links.
It's possible to add early work, but try to make sure it has some documentation, and keep it in its separate repository.

Libraries:
* [https://github.com/jk3064/chiliui ChiliUI]: UI framework [[Chili | docs]]
* [https://github.com/jk3064/lups LUPS]: Lua Particle System for Spring [[LUPS | docs]]
* [https://github.com/jk3064/Custom-Unit-Shader-Framework Custom Unit Shader Framework]: Unit rendering with shaders
* [https://github.com/gajop/liblobby LibLobby]: Spring Lobby protocol library
* [https://github.com/gajop/i18n i18n]: Translations library
* [https://github.com/gajop/Lua-Class-System LCS]: OOP (classes) in Lua
* [https://github.com/gajop/analytics analytics]: Usage analytics reporting [WIP]
* [https://github.com/gajop/chilifx ChiliFX]: Chili effects [WIP]
* [https://github.com/gajop/chotify Chotify]: Notification library in Chili [WIP]

==Single file libraries==
There is also a number of single file libraries that don't have their own repository but can technically still be considered libraries.

Library files:
* [https://github.com/SpringMCLegacy/SpringMCLegacy/blob/master/LuaRules/Gadgets/api_vector.lua Vector]: Small utility for vector operations
* [https://github.com/Spring-SpringBoard/SpringBoard-Core/blob/master/libs_sb/json.lua JSON]: Serializing to the JSON format
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_delay.lua Delay]: Delaying gadget calls
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/network.lua Network]: Delta compression for binary strings
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/camera.lua Camera]: Camera state serialization
* Deferred rendering [http://imolarpg.dyndns.org/svn/branches/BAR/shaders/deferred_lighting.glsl Shader] & [http://imolarpg.dyndns.org/svn/branches/BAR/luaui/widgets/gfx_deferred_rendering.lua Widget]: Deferred rendering (projectile) based lights

[[Category:Lua]] [[Category:Libraries]]

Lua Performance

2018-10-13T09:59:52Z

Gajop: remove ugly code blocks

=Overview=

This page is copied from the [http://trac.caspring.org/wiki/LuaPerformance CA wiki]. The widget used in the performance tests is available from the [http://trac.caspring.org/browser/trunk/mods/ca-sandbox/LuaUI/Widgets/performance.lua CA SVN].

=Other Considerations=

It is a well known axiom in computing that

<blockquote>"We should forget about small efficiencies, say about 97% of the time: '''premature optimization is the root of all evil'''"</blockquote>

- [http://en.wikipedia.org/wiki/Donald_Knuth Donald Knuth]

Lua coders should keep that in mind, and especially when visiting this page. Readability and maintainability are in most cases just as important, and optimizing code for every last ounce of performance can severely impact those qualities. On the other hand, some of the optimizations suggested have little bearing on readability and should generally always be applied, e.g. localization of API functions, or actually make for neater code e.g. the use of <code>or</code> rather than a nil-check. Generally speaking, optimize only once you are sure that there is or will be a performance bottleneck.

=Performance Tests=

==TEST 1: Localize==

'''Code:'''

<pre> local min = math.min</pre>

'''Results:'''

:Non-local: 0.719 (158%)
:Localized: 0.453 (100%)

'''Conclusion:'''

:Yes, we should localize all standard Lua and Spring API functions.

==TEST 2: Localized Class-Methods (with only 3 accesses!)==

'''Code 1:'''

<pre> for i=1,1000000 do
local x = class.test()
local y = class.test()
local z = class.test()
end</pre>

'''Code 2:'''

<pre> for i=1,1000000 do
local test = class.test
local x = test()
local y = test()
local z = test()
end</pre>

'''Results:'''

:Normal way: 1.203 (102%)
:Localized: 1.172 (100%)

'''Conclusion:'''

:No, it isn't faster to localize a class method IN the function call.

==TEST 3: Unpack A Table==

'''Code 1:'''
<pre> for i=1,1000000 do
local x = min( a[1],a[2],a[3],a[4] )
end</pre>

'''Code 2:'''
<pre> local unpack = unpack
for i=1,1000000 do
local x = min( unpack(a) )
end</pre>

'''Code 3:'''
<pre> local function unpack4(a)
return a[1],a[2],a[3],a[4]
end
for i=1,1000000 do
local x = min( unpack4(a) )
end</pre>

'''Results:'''

:with [ ]: 0.485 (100%)
:unpack(): 1.093 (225%)
:custom unpack4: 0.641 (131%)

'''Conclusion:'''

:Don't use <code>unpack()</code> in time critical code!

==TEST 4: Determine Maximum And Set It ('>' vs. max)==

'''Code 1:'''
<pre> local max = math.max
for i=1,1000000 do
x = max(random(cnt),x)
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
local r = random(cnt)
if (r>x) then x = r end
end</pre>

'''Results:'''

:math.max: 0.437 (156%)
:'if > then': 0.282 (100%)

'''Conclusion:'''

:Don't use <code>math.[max|min]()</code> in time critical code!

==TEST 5: Nil Checks ('if' vs. 'or')==

'''Code 1:'''
<pre> for i=1,1000000 do
local y,x
if (random()>0.5) then y=1 end
if (y==nil) then x=1 else x=y end
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
local y
if (random()>0.5) then y=1 end
local x=y or 1
end</pre>

'''Results:'''

:nil-check: 0.297 (106%)
:a=x or y: 0.281 (100%)

'''Conclusion:'''

:The <code>or</code>-operator is faster than a nil-check. Use it!

==TEST 6: 'x^2' vs. 'x*x'==

'''Code 1:'''
<pre> for i=1,1000000 do
local y = x^2
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
local y = x*x
end</pre>

'''Results:'''

:x^2: 1.422 (110%)
:x*x: 1.297 (100%) 

'''Conclusion:'''

:The second syntax is marginally faster

==TEST 7: Modulus Operators (math.mod vs. %)==

'''Code 1:'''
<pre> local fmod = math.fmod
for i=1,1000000 do
if (fmod(i,30)<1) then
local x = 1
end
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
if ((i%30)<1) then
local x = 1
end
end</pre>

'''Results:'''

:math.mod: 0.281 (355%)
:%: 0.079 (100%) 

'''Conclusion:'''

:Don't use <code>math.fmod()</code> for positive numbers (for negative ones <code>%</code> and <code>fmod()</code> have different results!)

==TEST 8: Functions As Param For Other Functions==

'''Code 1:'''
<pre> local func1 = function(a,b,func)
return func(a+b)
end

for i=1,1000000 do
local x = func1(1,2,function(a) return a*2 end)
end</pre>

'''Code 2:'''
<pre> local func1 = function(a,b,func)
return func(a+b)
end
local func2 = function(a)
return a*2
end

for i=1,1000000 do
local x = func1(1,2,func2)
end</pre>

'''Results:'''

:defined in function param: 3.890 (1144%)
:defined as local: 0.344 (100%) 

'''Conclusion:'''

:REALLY, LOCALIZE YOUR FUNCTIONS ALWAYS BEFORE SENDING THEM INTO ANOTHER FUNCTION!!! i.e if you use gl.BeginEnd(), gl.CreateList(), ...!!!

==TEST 9: for-loops==

'''Code 1:'''
<pre> for i=1,1000000 do
for j,v in pairs(a) do
x=v
end
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
for j,v in ipairs(a) do
x=v
end
end</pre>

'''Code 3:'''
<pre> for i=1,1000000 do
for i=1,100 do
x=a[i]
end
end</pre>

'''Code 4:'''
<pre> for i=1,1000000 do
for i=1,#a do
x=a[i]
end
end</pre>

'''Code 5:'''
<pre> for i=1,1000000 do
local length = #a
for i=1,length do
x=a[i]
end
end</pre>

'''Results:'''

:pairs: 3.078 (217%)
:ipairs: 3.344 (236%)
:for i=1,x do: 1.422 (100%)
:for i=1,#atable do 1.422 (100%)
:for i=1,atable_length do: 1.562 (110%)

'''Conclusion:'''

:Don't use <code>pairs()</code> or <code>ipairs()</code> in critical code! Try to save the table-size somewhere and use <code>for i=1,x do</code>!

==TEST 10: Array Access (with [ ]) vs. Object Access (with .method)==

'''Code 1:'''
<pre> for i=1,1000000 do
x = a["foo"]
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
x = a.foo
end</pre>

'''Results:'''

:atable["foo"]: 1.125 (100%)
:atable.foo: 1.141 (101%)

'''Conclusion:'''

:No difference.

==TEST 11: Buffered Table Item Access==

'''Code 1:'''
<pre> for i=1,1000000 do
for n=1,100 do
a[n].x=a[n].x+1
end
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
for n=1,100 do
local y = a[n]
y.x=y.x+1
end
end</pre>

'''Results:'''

:'a[n].x=a[n].x+1': 1.453 (127%)
:'local y=a[n]; y.x=y.x+1': 1.140 (100%) 

'''Conclusion:'''

:Buffering can speed up table item access.

==TEST 12: Adding Table Items (table.insert vs. [ ])==

'''Code 1:'''
<pre> local tinsert = table.insert
for i=1,1000000 do
tinsert(a,i)
end</pre>

'''Code 2:'''
<pre> for i=1,1000000 do
a[i]=i
end</pre>

'''Code 3:'''
<pre> for i=1,1000000 do
a[#a+1]=i
end</pre>

'''Code 4:'''
<pre> local count = 1
for i=1,1000000 do
d[count]=i
count=count+1
end</pre>

'''Results:'''

:table.insert: 1.250 (727%)
:a[i]: 0.172 (100%)
:a[#a+1]=x: 0.453 (263%)
:a[count++]=x: 0.203 (118%)

'''Conclusion:'''
:Don't use <code>table.insert</code>!!! Try to save the table-size somewhere and use <code>a[count+1]=x</code>!

==TEST 12: Adding Table Items (mytable ={} vs. mytable={...})==

When you write {true, true, true} , Lua knows beforehand that the table will need three slots in its array part, so Lua creates the table with that size. Similarly, if you write
{x = 1, y = 2, z = 3}, Lua will create a table with four slots in its hash part.

As an example, the next loop runs in 2.0 seconds:

<code>for i = 1, 1000000 do

local a = {}

a[1] = 1; a[2] = 2; a[3] = 3

end
</code>

If we create the tables with the right size, we reduce the run t
ime to 0.7 seconds:

<code>
for i = 1, 1000000 do

local a = {true, true, true}

a[1] = 1; a[2] = 2; a[3] = 3

end
</code>

If you write something like {[1] = true, [2] = true, [3] = true}, however, Lua is not smart enough to detect that the given expressions (literal numbers, in this case) describe array indices, so it creates a table with four slots in its hash part, wasting memory and CPU time

[http://www.lua.org/gems/sample.pdf]

=Test 13=
Table initialisation with local members and static intialisation.
<pre>
local x = os.clock()
T={}
print(string.format("start time: %.2f\n", os.clock() - x))
local CachedTable= {"abc","def","ghk"}
for i=1 , 10000000, 1 do
T[i] = CachedTable
end
print(string.format("elapsed time: %.2f\n", os.clock() - x))
</pre>
<pre>
local x = os.clock()
A={}
print(string.format("start time: %.2f\n", os.clock() - x))
for i=1 , 10000000, 1 do
A[i] = {"abc","def","ghk"}
end
print(string.format("elapsed time: %.2f\n", os.clock() - x))
</pre>
Result:
local table initializer = 100 %
static intializer = 500 %

Analysis: Lua sucks at identifying static initializers, do not use them, use local initalizations instead.

=Lua Garbage Collection=
Forum thread about {{forumlink|topic=31049|title= Lua Garbage collection info}}

[[Category: Lua]]