Spring - User contributions [en]

LUPS

2014-12-06T19:18:57Z

Knorke: github link

Lua Particle System (LUPS)

Licensed under the terms of the GNU GPL, v2 or later.

== github ==
https://github.com/jk3064/lups

== Implementation ==
First, you need to differ between synced and unsynced FX,
so there are 2 LUPS instances running:
one in LuaUI (widget) and
one in LuaRules (gadget).
(To start a new instance simply include lups/lups.lua)

== Why differ between synced and unsynced FX? ==
LuaUI has only a limited access to engine values, so it
could never determine the unittype of enemy units in airlos,
nor is it able to catch weapon explosion or to interact with
cob.

== Which files are used by LUPS? ==
the core uses the following:
lups/*
bitmaps/GPL/lups/*
LuaUI/Widgets/lups_wrapper.lua
LuaRules/Gadgets/lups_wrapper.lua (only if you want synced
FX like shockwaves/nanolasers)
and there are the managers:
LuaUI/Widgets/gfx_lups_manager.lua
LuaRules/Gadgets/gfx_lups_manager.lua
the shockwaves gadget:
LuaRules/Gadgets/lups_shockwaves.lua

== What are those managers? ==
LUPS itself doesn't start any FX. It needs other lua files
to tell LUPS when it should start a new FX.
There are many widgets and gadgets, which start LUPS FXs,
but the most interesting ones are the managers (and perhaps
the shockwaves gadget).
Also the manager in LuaRules differ from that one in LuaUI.
The manager in LuaUI starts FXs everytime an new unit gets
finished or an enemy unit enters the LOS, so those FX only
vanish if the unit dies or leaves the LOS again.
The LuaRules manager is much less customizable, it creates
very special FXs like cloaking and it also manage parts of
the LUPS nano particle handling.

== How do I implement my own FX? ==
Okay, in the case you use the LuaUI manager and you want to
create a per-unit FX (like a fusion FX, airjets, ...):

1. open LuaUI/Widgets/gfx_lups_manager.lua
(don't shock the file seems huge, but most is only config,
and yeah it needs a cleanup ... someday :x)
2. scroll down (~50% scrollbar)
you will find the following table/array:
"local UnitEffects = {...}"
It holds the FX per-unitdef.
3. create a new sub-table like the following:
[UnitDefNames["%UNITDEF_NAME%"].id] = {
{class='%FXCLASS%',options=%MY_FXOPTIONS_TABLE%}
},

== What FXClasses exist and how do I know their options? ==
All FXClasses are located here:
/lups/ParticleClasses/*
If you open on of those files, you will see a function like this:

function ShieldSphereParticle.GetInfo()
return {
name = "ShieldSphere",
}
end

That returned name is what you fill in %FXCLASS% (uppercase
doesn't matter), also it is in most cases same as the filename.
To see possible options of the FXClass scroll a bit down, you
will find a table like this:

ShieldSphereParticle.Default = {
pos = {0,0,0}, -- start pos
layer = -23,
life = 0, --in frames
size = 0,
sizeGrowth = 0,
margin = 1,
colormap1 = { {0, 0, 0, 0} },
colormap2 = { {0, 0, 0, 0} },
repeatEffect = false,
}

The table contains all options and their default values.
So an example fx placed in LuaUI/Widgets/gfx_lups_manager.lua
could look like this:
[UnitDefNames["armcom"].id] = {
{class='ShieldSphere',options={ life=3000, repeatEffect=true, size=300, colormap1={1,0,0,0.5}, colormap2={0,1,0,0.5} } }
},

== How do I start my own FX from my widget/gadget? ==
First, you need a link to the interface, to do so you need
to access the global shared table of the widget-/gadgetHandler.
for LuaUI:
local LupsApi = WG.Lups
for LuaRules:
local LupsApi = GG.Lups
(nil check those, it is possible that Lups hasn't started yet!)

That Api contains the following functions:
LupsApi.GetStats()
LupsApi.GetErrorLog(minPriority)
-> LupsApi.AddParticles(class,options) //returns a fxID
-> LupsApi.RemoveParticles(fxID)
LupsApi.AddParticlesArray({ {class=className, ..FX options..},{class=className, ..FX options..},.. } )
LupsApi.HasParticleClass(className)
and
LupsApi.Config = {...} //contains the options of lups.cfg

== Example usage of AddParticles() ==
LupsApi.AddParticles('ShieldSphere', {
unit=unitID,
piece="head",
pos={0,100,0},
life=3000,
repeatEffect=true,
size=300,
colormap1={1,0,0,0.5},
colormap2={0,1,0,0.5}
})

== How do I bind a FX to an unit/unitpiece? ==
There are some special options tags, those are:
unit := binds fx to unitID
piece:= binds fx to pieceNAME
pos := worldspace coord or offset coord from the unit/unitpiece center
onActive := only show FX if the unit is active (e.g. used for airjets - a plane is active, if it flies)

== Can I modify FX on runtime? ==
Sure you can. There is only one issue in 76b1 (it will
be fixed in the next spring release):
you can't modify widgets if they are in a .sdd, so you
have to copy it to your local widgets folder,
then you can run:
/luaui reload
each time you modified the file.

== I heard some options can contain Lua code? ==
Yeah, but only the SimpleParticles class support them and
_only_ in the "partpos" param:

LupsApi.AddParticles('SimpleParticles', {
...
partpos = "r*cos(beta)*sin(alpha),r*cos(alpha),r*sin(beta)*sin(alpha) | r=random()*20, alpha=2*math.pi*random(), beta=2*math.pi*random()"
...
})

The syntax is a bit extended so it looks similar to the
definitions of a mathical sets, but it can still contain
any lua code.

Valid examples are:
"x,y,z | x=10,y=30,z=0"
"10,30,0"
"random(),random(),random()"
"x,y,z | r=random(), if (r>10) then x=10; y=30; z=0; else x=-10; y=-30; z=-0; end"

[[Category:Libraries]]

User:Knorke/Sandbox3

2014-11-08T03:55:41Z

Knorke: /* Lua rocks */ pic

__TOC__

{{Caution|The Lua examples on this page has been tested and ''should'' work. However there is always the possibility that between copying from script into this text sometimes has been lost. If you notice something missing/wrong or something absolutely does not work then please tell in forum.}}

=Introduction=
This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

And then it will suddendly fall down! (Look at above gif and watch the small countdown)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we always test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<code><pre>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:Circle_of_Rocks.jpg]]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<code><pre>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

=Complete Pifffp widget=
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

Now we have created ourselves a quick way to put features onto map with Lua.

=Making a map? How to turn LuaRules into LuaGaia!=
"LuaRules" is meant for games while maps should use "LuaGaia". {{FIXME}} maybe link to some more detailed explaination of LuaStates.

So if you want to move the scripts from the test-mutator (or other game archive) into a map then some minor changes are needed.

The folder structure should be like:

<code>LuaGaia\gadgets\MyMapGadget.lua</code>

Also include two "base files" like this:

<pre>LuaGaia\draw.lua</pre> with content:

<code>VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)</code>

<pre>LuaGaia\main.lua</pre> with content:

<code>VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)</code>

For reloading this LuaGaia Lua type: /luagaia reload

Everything else stays the same.

User:Knorke/Sandbox3

2014-11-08T01:56:43Z

Knorke: wiki images work again

__TOC__

{{Caution|The Lua examples on this page has been tested and ''should'' work. However there is always the possibility that between copying from script into this text sometimes has been lost. If you notice something missing/wrong or something absolutely does not work then please tell in forum.}}

=Introduction=
This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

And then it will suddendly fall down! (Look at above gif and watch the small countdown)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we always test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<code><pre>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:CircleOfRocks.jpg]]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<code><pre>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

=Complete Pifffp widget=
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

Now we have created ourselves a quick way to put features onto map with Lua.

=Making a map? How to turn LuaRules into LuaGaia!=
"LuaRules" is meant for games while maps should use "LuaGaia". {{FIXME}} maybe link to some more detailed explaination of LuaStates.

So if you want to move the scripts from the test-mutator (or other game archive) into a map then some minor changes are needed.

The folder structure should be like:

<code>LuaGaia\gadgets\MyMapGadget.lua</code>

Also include two "base files" like this:

<pre>LuaGaia\draw.lua</pre> with content:

<code>VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)</code>

<pre>LuaGaia\main.lua</pre> with content:

<code>VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)</code>

For reloading this LuaGaia Lua type: /luagaia reload

Everything else stays the same.

File:TreesSpawnedRandomly.jpg

2014-11-08T01:55:30Z

Knorke: a rectangular area has been filled with trees as result of a Lua. the commander is looking at the forest. for use in Lua/mapping tutorial.

a rectangular area has been filled with trees as result of a Lua.
the commander is looking at the forest.
for use in Lua/mapping tutorial.

File:TreesSpawnedOnHill.jpg

2014-11-08T01:54:34Z

Knorke: several trees have been spawned on a hill by a Lua. the commander is looking at the trees or maybe just at the hill. for use in Lua/mapping tutorial.

several trees have been spawned on a hill by a Lua.
the commander is looking at the trees or maybe just at the hill.
for use in Lua/mapping tutorial.

File:TreeSpiralWithGeovent.jpg

2014-11-08T01:53:42Z

Knorke: A spiral of trees with a smoking geovent in the center was created by a Lua. for use in Lua/mapping tutorial.

A spiral of trees with a smoking geovent in the center was created by a Lua.
for use in Lua/mapping tutorial.

File:Pifffp ResultFeatures.jpg

2014-11-08T01:53:08Z

Knorke: some features sit on the map as result of a Lua. for use in Lua/mapping tutorial.

some features sit on the map as result of a Lua.
for use in Lua/mapping tutorial.

File:Pifffp Markers.jpg

2014-11-08T01:52:34Z

Knorke: several markers, some with text, are used to mark coordinates where features will be created. for use in Lua/mapping tutorial.

several markers, some with text, are used to mark coordinates where features will be created.
for use in Lua/mapping tutorial.

File:OneTreeOnHill.jpg

2014-11-08T01:51:47Z

Knorke: one tree stands on a hill. for use in Lua/mapping tutorial.

one tree stands on a hill.
for use in Lua/mapping tutorial.

File:MapMarkerCoordinatesToChat.jpg

2014-11-08T01:51:22Z

Knorke: map markers and their coordinates in chat for use in Lua/mapping tutorial.

map markers and their coordinates in chat
for use in Lua/mapping tutorial.

File:FeaturesFallAtGameStart.gif

2014-11-08T01:50:50Z

Knorke: a feature floats in midair before the game starts, physics kick in, and it falls downwards. for use in Lua/mapping tutorial.

a feature floats in midair before the game starts, physics kick in, and it falls downwards.
for use in Lua/mapping tutorial.

File:Circle of Rocks.jpg

2014-11-08T01:50:05Z

Knorke: a circle of rocks features. a commander is looking at the rocks. for use in Lua/mapping tutorial.

a circle of rocks features.
a commander is looking at the rocks.
for use in Lua/mapping tutorial.

User:Knorke/Sandbox3

2014-11-08T00:58:05Z

Knorke: LuaRules / LuaGaia

__TOC__

{{FIXME}} remove off-site links for images once uploading works again http://springrts.com/mantis/view.php?id=4612

{{Caution|The Lua examples on this page has been tested and ''should'' work. However there is always the possibility that between copying from script into this text sometimes has been lost. If you notice something missing/wrong or something absolutely does not work then please tell in forum.}}

=Introduction=
This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

[File:http://abload.de/img/onetreeonhillpcs0m.jpg]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

[File:http://abload.de/img/featuresfallatgamestaaesnm.gif]

And then it will suddendly fall down! (Look at above gif and watch the small countdown)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

[File:http://abload.de/img/treesspawnedonhill74shj.jpg]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we always test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<code><pre>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

[File:http://abload.de/img/treesspawnedrandomlyf3snt.jpg]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:CircleOfRocks.jpg]]
[File:http://abload.de/img/circle_of_rockso5stt.jpg]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<code><pre>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

[File:http://abload.de/img/treespiralwithgeoventu1swc.jpg]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

[File:http://abload.de/img/mapmarkercoordinatestnwsng.jpg]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

=Complete Pifffp widget=
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

[File:http://abload.de/img/pifffp_markers7lsq1.jpg]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

[File:http://abload.de/img/pifffp_resultfeaturesiisdi.jpg]

Now we have created ourselves a quick way to put features onto map with Lua.

=Making a map? How to turn LuaRules into LuaGaia!=
"LuaRules" is meant for games while maps should use "LuaGaia". {{FIXME}} maybe link to some more detailed explaination of LuaStates.

So if you want to move the scripts from the test-mutator (or other game archive) into a map then some minor changes are needed.

The folder structure should be like:

<code>LuaGaia\gadgets\MyMapGadget.lua</code>

Also include two "base files" like this:

<pre>LuaGaia\draw.lua</pre> with content:

<code>VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)</code>

<pre>LuaGaia\main.lua</pre> with content:

<code>VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)</code>

For reloading this LuaGaia Lua type: /luagaia reload

Everything else stays the same.

User:Knorke/Sandbox3

2014-11-08T00:01:33Z

Knorke:

User:Knorke/Sandbox3

2014-11-07T23:54:42Z

Knorke: lame disclaimer

__TOC__

{{FIXME}} remove off-site links for images once uploading works again http://springrts.com/mantis/view.php?id=4612

{{Caution|The Lua examples on this page has been tested and ''should'' work. However there is always the possibility that between copying from script into this text sometimes has been lost. If you notice something missing/wrong or something absolutely does not work then please tell in forum.}}

=Introduction=
This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

[File:http://abload.de/img/onetreeonhillpcs0m.jpg]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

[File:http://abload.de/img/featuresfallatgamestaaesnm.gif]

And then it will suddendly fall down! (Look at above gif and watch the small countdown)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

[File:http://abload.de/img/treesspawnedonhill74shj.jpg]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we always test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<code><pre>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

[File:http://abload.de/img/treesspawnedrandomlyf3snt.jpg]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:CircleOfRocks.jpg]]
[File:http://abload.de/img/circle_of_rockso5stt.jpg]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<code><pre>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

[File:http://abload.de/img/treespiralwithgeoventu1swc.jpg]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

[File:http://abload.de/img/mapmarkercoordinatestnwsng.jpg]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

==Complete Pifffp widget==
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

[File:http://abload.de/img/pifffp_markers7lsq1.jpg]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

[File:http://abload.de/img/pifffp_resultfeaturesiisdi.jpg]

Now we have created ourselves a quick way to put features onto map with Lua.

User:Knorke/Sandbox3

2014-11-07T23:24:43Z

Knorke: /* A forest is many, many, many trees */

{{FIXME}} remove off-site links for images once uploading works again http://springrts.com/mantis/view.php?id=4612

This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

[File:http://abload.de/img/onetreeonhillpcs0m.jpg]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

[File:http://abload.de/img/featuresfallatgamestaaesnm.gif]

And then it will suddendly fall down! (Look at above gif and watch the small countdown)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

[File:http://abload.de/img/treesspawnedonhill74shj.jpg]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we always test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<code><pre>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

[File:http://abload.de/img/treesspawnedrandomlyf3snt.jpg]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:CircleOfRocks.jpg]]
[File:http://abload.de/img/circle_of_rockso5stt.jpg]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<code><pre>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

[File:http://abload.de/img/treespiralwithgeoventu1swc.jpg]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

[File:http://abload.de/img/mapmarkercoordinatestnwsng.jpg]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

==Complete Pifffp widget==
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

[File:http://abload.de/img/pifffp_markers7lsq1.jpg]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

[File:http://abload.de/img/pifffp_resultfeaturesiisdi.jpg]

Now we have created ourselves a quick way to put features onto map with Lua.

User:Knorke/Sandbox3

2014-11-07T23:12:17Z

Knorke: /* Deleting all features from map */

{{FIXME}} remove off-site links for images once uploading works again http://springrts.com/mantis/view.php?id=4612

This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

[File:http://abload.de/img/onetreeonhillpcs0m.jpg]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

[File:http://abload.de/img/featuresfallatgamestaaesnm.gif]

And then it will suddendly fall down! (Look at above gif and watch the small countdown)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

[File:http://abload.de/img/treesspawnedonhill74shj.jpg]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we always test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<pre><code>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

[File:http://abload.de/img/treesspawnedrandomlyf3snt.jpg]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:CircleOfRocks.jpg]]
[File:http://abload.de/img/circle_of_rockso5stt.jpg]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<pre><code>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

[File:http://abload.de/img/treespiralwithgeoventu1swc.jpg]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

[File:http://abload.de/img/mapmarkercoordinatestnwsng.jpg]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

==Complete Pifffp widget==
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

[File:http://abload.de/img/pifffp_markers7lsq1.jpg]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

[File:http://abload.de/img/pifffp_resultfeaturesiisdi.jpg]

Now we have created ourselves a quick way to put features onto map with Lua.

User:Knorke/Sandbox3

2014-11-07T23:10:57Z

Knorke:

{{FIXME}} remove off-site links for images once uploading works again http://springrts.com/mantis/view.php?id=4612

This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

[File:http://abload.de/img/onetreeonhillpcs0m.jpg]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

[File:http://abload.de/img/featuresfallatgamestaaesnm.gif]

And then it will suddendly fall down! (Look at above gif and watch the small countdown)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

[File:http://abload.de/img/treesspawnedonhill74shj.jpg]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we also test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<pre><code>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

[File:http://abload.de/img/treesspawnedrandomlyf3snt.jpg]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:CircleOfRocks.jpg]]
[File:http://abload.de/img/circle_of_rockso5stt.jpg]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<pre><code>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

[File:http://abload.de/img/treespiralwithgeoventu1swc.jpg]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

[File:http://abload.de/img/mapmarkercoordinatestnwsng.jpg]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

==Complete Pifffp widget==
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

[File:http://abload.de/img/pifffp_markers7lsq1.jpg]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

[File:http://abload.de/img/pifffp_resultfeaturesiisdi.jpg]

Now we have created ourselves a quick way to put features onto map with Lua.

User:Knorke/Sandbox3

2014-11-07T23:06:31Z

Knorke: first version of LuaMapStuff

This text talks about how to put features onto the map, using Lua.

The text can be read in two ways:
*As a Lua tutorial that expands on [[Lua:Tutorial_GettingStarted]] and {{FIXME}} that other page in sandbox
*For mappers as way to put features onto their map.
**In this case you can skip some of the "finer details" and just copypaste what seems interessting.

To follow the examples you can either...
* ...use your WIP map in .sdd format
* ...or unpack an existing map
* ...or use the test-mutator example from previous tutorial.

This text will be based around the map '''"DesertTriad"'''

=Creating a feature: Spring.CreateFeature=

Again we use our test-hill in the bottom right corner, of which we already know the coordinates:

[[File:DesertTriadHillCoordinates.jpg]]

'''We want to create a feature on this hill.'''

Create a file: <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code>

At [[Lua_SyncedCtrl#Feature_Handling]] we find the function <code>Spring.CreateFeature</code>

We need the parameters: ''featurename'' and ''x,y,z'' coordinates. The other parameters do not matter for now.

The map "DesertTriad" already includes some rock features that we could use. If using the test-mutator then we can also use whatever features the game includes, usually that is mostly wrecks of destroyed units.

Another group of features that we can use are the ones hardcoded in the engine: Geovents and trees.

We use a feature named "treetype0", it is a tree that comes with Spring engine.

Putting feature name and coordinates as parameters:

<code>Spring.CreateFeature ("treetype0", 3830, 390, 3600)</code>

==GameStart() or Initialize() or GamePreload() ?==
Where should we put the CreateFeature code?

There are three callin functions that appear suitable:

'''GameStart() Initialize() GamePreload() - can callin can I take?'''

* <code>GameStart()</code> is called as soon as the game begins.
**However, it is not yet called when the players are ingame but have not readied up yet.
** => If this callin was used then features would not appear until the game is started. Thus players could not see while choosing their start positions etc.

* <code>GamePreload()</code> is called as soon as soon the "game is ingame."
**Features spawned in this function will be visible before readying up.
**However, it is only called once: Right after the game has finished loading.
***That means if we want to test our Lua by typing ''/luarules reload'' then it will not trigger again.

* <code>Initialize()</code> is called when the gadget is initialized.
**Features spawned in this function will be visible before readying up.
**When typing ''/luarules reload'' the gadgets get initialized again and the function gets called again.
***This makes it suitable for testing.

=> Both <code>Initialize()</code> and <code>GamePreload()</code> can be used to spawn features without "delay."

=> Maybe <code>GamePreload()</code> is a bit "more technical correct" but <code>Initialize()</code> is more suited for testing, so we use that.

=complete gadget that plants a tree=
Thus the gadget now looks like this:

<code><pre>
function gadget:GetInfo()
return {
name = "lua map stuff",
desc = "create some features",
author = "youe name",
date = "the day a lua was made",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if not gadgetHandler:IsSyncedCode() then

function gadget:Initialize()
Spring.CreateFeature ("treetype0", 3830, 390, 3600)
end

else --unsynced part below

end
</pre></code>

The result:

[[File:OneTreeOnHill.jpg]]

[File:http://abload.de/img/onetreeonhillpcs0m.jpg]

{{Tip|'''Such simple code is really all it takes to put features on a map.'''

If one wanted one could now replaces the featurename and coordinates and use it to populate a map. In fact some maps do just that.}}

{{Tip|If you need to remove the tree for testing purposes, then reclaim it with the Commander or a constructor. (We will learn a better way soon)}}

==If a tree falls from the sky... does it make a sound?==
One interessting thing is that Spring physics do not get activated until the game actually starts.

Why is that relevant for spawning features?

If we use a too high y-coordinate (vertical axis / height) then the tree will hover in the air until the game starts.

[[File:FeaturesFallAtGameStart.gif]]

[File:http://abload.de/img/lfs2014-10-1818-14-44swfl9.gif]

And then it will suddendly fall down! (Look at above gif)

Similiar if we use too low y-coordinate then the tree will be created underground and only "pop" above ground once the game starts!

{{Tip|It is important to spawn features (and units) at the correct y-coordinate.}}

===GetGroundHeight===
Instead of reading the ground height from the tooltip we can also use the function <code>Spring.GetGroundHeight</code>:

<code><pre>
function gadget:Initialize()
x = 3830
z = 3600
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end
</pre></code>

=Functional forest=
We can put our tree-spawner code into a function and call it from <code>Initialize()</code> multiple times with different coordinates:
<code><pre>
function PlantTree (x,z)
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("treetype0", x,y,z)
end

function gadget:Initialize()
PlantTree (3830,3600)
PlantTree (3850,3650)
PlantTree (3800,3650)
PlantTree (3810,320)
end
</pre></code>

Result:

[[File:TreesSpawnedOnHill.jpg]]

[File:http://abload.de/img/treesspawnedonhill74shj.jpg]

{{Tip|For practice try to make a function that spawns geothermal spots! The featurename is "geovent".}}

=Deleting all features from map=
Sometimes one might want to test the spawning of features again & again, on a clean plate.
The function below deletes all features on the map:
<code><pre>
function DestroyAllFeatures ()
local features = Spring.GetAllFeatures ()
for i in pairs(features) do
Spring.DestroyFeature (features[i])
end
end</pre></code>

It can be called in <code>Initialize()</code> ''before'' we spawn our features, to ensure we also test on an empty map.

When packing the map for release, one might want to comment it out again.

=A forest is many, many, many trees=
A handful of trees is often not enough for a map. Let's turn the whole bottom left corner of the map into a forest.

But planting a whole forest by typing coordinates of many trees seems very cumbersome?

What about randomizing the placement of the tree?

We look up the coordinates of that area: x-coordinate we want 3500 to 4000, for z-coordinate we want 3000 to 4000.

...and put it into a random number generator function.

<code><pre>
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)</pre></code>

We want to plant many trees. Instead of copy-pasting those lines 100 times, we use a loop:
<pre><code>
function gadget:Initialize()
DestroyAllFeatures ()
for i=1,100 do
x = math.random (3500,4000)
z = math.random (3000,4000)
PlantTree (x,z)
end
end</pre></code>

The result:

[[File:TreesSpawnedRandomly.jpg]]

[File:http://abload.de/img/treesspawnedrandomlyf3snt.jpg]

{{Tip|Forests are perfect for such random placement because the excact position of an indiviual tree does not matter much.}}

==Spawning features in patterns==
With a little creativity one can quickly fill the map in interessting ways.

For example try to create a function that spawns small clusters of trees.

Or imagine a function that spawns a big mineral crystal, surrounded by smaller rocks.

Or imagine an ore-mining facility with pieces of ore spread around it.

etc

Below is some examples that are hopefully understandable without too lenghty explainations.

==Lua rocks==
<code><pre>
function Rock (x,z)
local featureName = "pdrock" .. math.random (1, 4)
Spring.CreateFeature (featureName, x,Spring.GetGroundHeight (x,z),z, math.random (0,32000))
end

function rockCircle (x,z, radius, numberOfRocks)
for d = 0,360, 360/numberOfRocks do
local x = x + (math.sin (math.rad(d)) * radius)
local z = z + (math.cos (math.rad(d)) * radius)
Rock (x, z)
end
end
</pre></code>
Example usage:
<code><pre>rockCircle (2000,2000, 240, 25)</pre></code>

Result:

[[File:CircleOfRocks.jpg]]
[File:http://abload.de/img/circle_of_rockso5stt.jpg]

*Note 1: <code>local featureName = "pdrock" .. math.random (1, 4)</code>
The rock features included in map "DesertTriad" are named "pdrock1" to "pdrock4". So we take "pdrock" and append a random number in range of 1 to 4 to that base name.

*Note 2: The heading-parameter is used here too, randomized. The heading (rotation) of features is probally not measured 0 to 32000, but for this case that does not matter. If the number is too high it will simply "wrap around."

==In my maps I have seen rings of smoke through the trees...==
''...and the voices of those who stand looking.''

<code><pre>
function TreeSpiral (x,z)
for d = 0,720, 20 do
local x = x + (math.sin (math.rad(d)) * d/2)
local z = z + (math.cos (math.rad(d)) * d/2)
PlantTree (x,z)
end
y = Spring.GetGroundHeight (x,z)
Spring.CreateFeature ("geovent", x,y,z)
end
</pre></code>

Example usage:
<pre><code>TreeSpiral (2000,2000)</pre></code>

Result:

A geothermal vent in the middle of a spiral of trees.

[[File:TreeSpiralWithGeovent.jpg]]

[File:http://abload.de/img/treespiralwithgeoventu1swc.jpg]

=Typing so many coordinates sucks!=
We saw how some typing could be saved by using loops or random placement.
But surely there must be another way?

We could try to save the coordinates of all features of the map into a file.

If we wanted to do that, we would preferably save the coordinates in a way that can also be read back by another script.
For now that seems too difficult so we think of another way.

* think * think * think *

==Coordinates Helper widget==
Spring allows players to mark tactical locations on the map by holding ~ or ^ and clicking the mousewheel.

That might also be useful for marking locations of features, if we can just save those coordinates?

Let's see if we can create a small '''helper widget''' for that purpose.

Create a file <code>LuaUI\widgets\MapMarkerCoordinatesLogger.lua</code>

==MapDrawCmd: 1,2,3 testing!==
For start let's just see if we can print the coordinates of a map marker to the console.

We discover the callin: <code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

<code><pre>
function widget:GetInfo()
return {
name = "MapMarkerCoordinatesLogger",
desc = "prints map marker coordinates",
author = "this lame tutorial or something",
date = "9 Nov 2010",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
Spring.Echo (px, py,pz)
end</pre></code>

Result:

[[File:MapMarkerCoordinatesToChat.jpg]]

[File:http://abload.de/img/mapmarkercoordinatestnwsng.jpg]

We see that the coordinates of the markers get printed to chat. (and thus to infolog.txt, too)

Not bad, but could be less bad.

==Turning test into something useful==

One obvious issue is that it does not just log placing markers but also outputs numbers when drawing lines or deleting.

Let's upgrade the widget so that:
#It only logs placing markers but not erasing or lines.
#instead of coordinates it outputs a whole function call like <code>PlantTree (3830,3600)</code>
#writes to a file instead of chat
#The functionname that gets written should be changeable from within game
#It has a cooler name

{{Tip|'''Before reading onwards: Try figure out a solution by yourself!'''

1) Sadly the wiki does not tell us how we know the difference between marker/lines/erasing. We must figure it out!

<code>MapDrawCmd(playerID, cmdType, px, py, pz, label)</code>

The paremter ''cmdType'' looks interessting. Let's just print that one too:
<code><pre>Spring.Echo (px, py,pz, cmdType)</pre></code>

We see that cmdType has the value "point" when placing markers and other values when doing other things.

So if cmdType is of wrong value we just return and do nothing:
<code><pre>
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
...
</pre></code>

2) Creating the complete function call like "PlantTree (3830,3600)" is just a matter of appending some strings:
<code><pre>
local functionName = "PlantTree"
local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)
</pre></code>

Note that we only save the X and Z coordinates because the Y-coordinate we can later get anyway with Spring.GetGroundHeight

3) About writing to file we can find many tutorials on web if we google something like "Lua write to file" or similiar.

The result:
<code><pre>
local file = io.open("myCoordinatesFile.txt", "a")
file:write(s)
file:flush()
file:close()
</pre></code>

4) Markers can have a label text attached to them. Let's use that to allow user to change the functionname.
<code><pre>if label ~= "" then functionName = label end</pre></code>

5) Since the widget writes points into files for features placement, we name it: '''Pifffp'''

==Complete Pifffp widget==
Putting everything together we get:

<code><pre>
function widget:GetInfo()
return {
name = "Pifffp aka MapMarkerCoordinatesLogger",
desc = "prints Lua functions for placing featues",
author = "this lame tutorial or something",
date = "today",
license = "GNU GPL, v2",
layer = -5,
enabled = true,
}
end

local functionName = "PlantTree"
function widget:MapDrawCmd(playerID, cmdType, px, py, pz, label)
if cmdType ~= "point" then return end
if label ~= "" then functionName = label end
--Spring.Echo (px, py,pz, cmdType, "-"..label.."-")

local s = functionName .. " (" .. px ..", " .. pz .. ")"
Spring.Echo (s)

local file = io.open("myCoordinatesFile.txt", "a")
file:write(s .. "\n")
file:flush()
file:close()
end
</pre></code>

==Using the Pifffp tool as a user/mapper==
Activate the widget in F11 list.

Now start placing map markers. Every time you place a marker the coordinates get logged into '''myCoordinatesFile.txt''', already formated as parameters to a function call.

(The file should usually be written next to spring.exe)

To change the name of the function place a marker with a label text. All folling markers will then use that text, until a new label text is used.

Example usage:

[[File:Pifffp_Markers.jpg]]

[File:http://abload.de/img/pifffp_markers7lsq1.jpg]

Example output:

<code><pre>
PlantTree (1977, 3569)
PlantTree (1933, 3372)
PlantTree (1901, 3489)
PlantTree (1850, 3612)
PlantTree (2008, 3643)
PlantTree (2101, 3497)
PlantTree (2112, 3637)
PlantTree (2228, 3605)
PlantTree (2226, 3464)
PlantTree (2043, 3406)
PlantTree (2163, 3357)
PlantTree (2293, 3278)
PlantTree (2125, 3179)
PlantTree (1986, 3193)
Rock (1526, 3099)
Rock (1576, 3024)
Rock (1500, 2926)
Rock (1373, 3035)
Rock (1438, 3212)
Rock (1556, 3264)
Rock (1699, 3122)
Rock (1670, 2919)
Rock (1398, 2918)
Geovent (1818, 3298)
rockCircle (2308, 2788)
</pre></code>

We recognize these functions from the beginning of the tutorial.

Hopefully still have them ready in our <code>LuaRules\gadgets\MyLuaFeatureTesting.lua</code> file so that we only need to paste the Pifffp output into <code>Initialize</code>

(I you are making a real map you might want to use a better filename like "spawnMyFeatures.lua")

Note that for the function rockCircle we still need to fill in the parameters radius and amount of rocks like so:
<code><pre>
rockCircle (2308, 2788, 200, 25)</pre></code>

Example result:

[[File:Pifffp_ResultFeatures.jpg]]

[File:ttp://abload.de/img/pifffp_resultfeaturesiisdi.jpg]

Now we have created ourselves a quick way to put features onto map with Lua.

User:Knorke/Sandbox2

2014-11-07T19:15:51Z

Knorke: voOOOoolcanooOooo

This text describes making gadgets.

=Gadgets must be in a map or game=
For getting started with a widget, we could just put the file in the spring folder and start coding.
Unlike widgets, gadgets can not be used "locally" like this: They must be contained in a game or map archive.
So we must find a way to put the gadget into the game or map.

{{Tip|If you just want to know "How to set up a test-folder" then skip directly to next chapter.}}

The problem is that games and maps usually come in form of zipped archives, or in case of lobby downloaders as many small files.

[[File:rapid_pool_filedust.png]]

That makes adding new files cumbersome:
#Unpack the archive
#Add the new script file or edit it
#Repack the archive

So we must turn a map or game into an .sdd archive.

That is explain in more detail in general modding tutorial: ADDLINK FIXME

For first experiment it does not matter if the gadget is in the map or in the game.

Another way is to create a test-mutator. That is basically a game that "includes" another game, like an add-on.
The advantages are:
* No need to edit existing game and maybe run into problems.
* The test-game filesize stays small enough to share easily with others, to get help.
* One can still use all the units, features & effects of the original game. That is useful for testing.

Personally I recommend the test-mutator.
XTA is a good canidate as base-game choice because:
*in some ways it is more basic
*the unitnames are human-readable. For example "arm_windgenerator" instead of "armwingntor"
*Some games try to hide as much engine GUI as possible, however for testing that is not so useful.

=The Test Mutator folder=
1) Create folder: games\MyLuaStuff.sdd

2) Create file: games\MyLuaStuff.sdd\modinfo.lua ( [[Modinfo.lua]] )

With this content:
<code><pre>
return {
name='XTA LuaStuff',
description='lolool',
URL='http://code.google.com/p/xta-springrts/',
shortname='XTA',
version = '9.744',
mutator='LuaStuff',
game='Total Annihilation',
shortGame='TA',
depend = {"XTA 9.744"},
modtype=1,
}
</pre></code>
{{FIXME}} mutator details, can it work with any xta version

3) Test with spring.exe if the mutator shows in game list and can be played

=First gadget: Welcome, new unit!=

1) Create folders: games\MyLuaStuff.sdd\LuaRules\gadgets

2) Create file: games\MyLuaStuff.sdd\LuaRules\gadgets\mytestgadget.lua

3) For first widget we had done an empty widget that did nothing. In the widget-selector-menu we could still check if things were working right.
So we just take the Hello-Unit widget example and turn it into a gadget:
<code><pre>
function gadget:GetInfo()
return {
name = "test gadget",
desc = "testing Lua things",
author = "your name",
date = "today",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if gadgetHandler:IsSyncedCode() then

function gadget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("Welcome, new unit!")
end

else --unsynced below

end</pre></code>

We notice it looks very similiar to the widget, except instead of widget::xxx there is gadget:xxx

The GetInfo()-thing again contains some informations about the script, but is otherwise not interessting and to save space will be left out when posting code.

4) Load the game and build a few units. The gadget should welcome each unit.

=Volcano example=
An example of the process when making gadget.

Pretend you are making a map and want to add a volcano.
[[File:thinkingAboutVulcano.png]]

{{Tip|If we wanted, at this point we could move the Lua into a map-archive. But for testing it is easier to continue using the test-mutator-game.}}

==Define volcano problem==
We want to make a volcano. Now need to think ''what excactly is this volcano is supposed to do.''
*Should the volcano damage near units?
*Should it throw burning rocks across the map?
*Should it merely be a visual effect, just some smoke on a hill?

For this tutorial we chose the last option. (superlame!)

==How to make smoke==
Now that we know we want to make smoke, the new question is: How to make smoke?
One way is to use Spring's particle system called [[CEG:Main]]
Games can use these CEGS to create explosion, muzzle flashes, fire and so on.

Since our test-mutator is based on XTA, we can use all its effects.

Here we are going to use the effect "BERTHASHOT" which is defined in the file <code>gamedata\explosions\berthashot.tdf</code>

As the name implies, that effect is usually used when a "Big Bertha" cannon fires a shot. We pick it because it might vaguely look like a smoking volcano.

==How to spawn the CEG?==
So how can we make this "BERTHASHOT" effect appear on our volcano hill? Surely there must be some function call...

We clicked arond the [[CEG:Main]] page a bit and discover [[CEG:Calls]]

It seems there are various ways to use CEGs, for example weapons can use them.

Since we already decided we want to make a gadget, the relevant part is [[CEG:Calls#Synced_Lua_Gadget_CEGs]] which brings us to
[[Lua_SyncedCtrl#Other]]

==Spring.SpawnCEG==
On [[Lua_SyncedCtrl#Other]] we discover the function Spring.SpawnCEG and its parameter list:
<code><pre>
( 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
</pre></code>

*It seems to expect the name of the CEG as first parameter.
**We already got a CEG name: "BERTHASHOT"
*The posX,posY,posZ parameters seem to be the coordinates where the effect appears.
**Note to self: Find coordinates of some hill that looks like it needs some smoke.
*We have the effectname and where it should appear. The other parameters seems useless to our purpose so we ignore them.
**They will use default values.

==Location, location, location==
We decide to use the map '''"DesertTriad"'''.

At the bottom right corner there seems a be small hill, perfect volcano material:

[[File:DesertTriadHillCoordinates.jpg]]

1) The hill where we want smoke to appear.

2) The tooltip that shows the coordinates, when we mouse pointer onto the hill.

Protip: Look at [[Gamedev:UnitsOfMeasurement]] to learn about coordinates system!

==Putting parameters into Spawn.CEG==
Putting it together:
<code><pre>Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)</pre></code>

Where in the gadget should we put that?
Into <code>gadget:UnitFinished()</code> callin, like with the Hello-Unit example?
Then the volcano would only smoke when a new unit is created.

We need to find a better callin-function from the [[Lua:Callins]] page!

Some callin that gets triggered regularly... so we can have nice constant smoking.

We find:

GameFrame(frame) - ''Called for every game simulation frame (30 per second). ''

...thus we write:
<code><pre>
if gadgetHandler:IsSyncedCode() then

function gadget:GameFrame (f)
if (f%10 == 0) then
Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)
end
end

else --unsynced below

end
</pre></code>

<code>if (f%10 == 0) then</code> is added so that a new effect is only spawned every 10 frames.

Also see http://answers.springlobby.info/questions/412/gadgetgameframe-modulo-operation-explained - oh 404! {{FIXME}}

==Smoke in your eyes==
Save, start spring, look at the mountain.

Do you see smoke? Likely not because this smoke-effect is only visible when units have vision on it.

So either move a unit to the hill or type into chat:
<code><pre>
/cheat
/globallos
</pre></code>

Now we finally see the smoke:

[[File:DesertTriadVulcano.gif]]

==What did we learn?==
Writting the script is just part one part of making gadget.

From programming perspective, the volcano example is quite simple.

The harder part was...
*finding a starting point
*setting up an editable archive
*finding the right functions
*learning about CEGs
*figuring out general "Spring stuff" like coordinates.

For example had we not known that some particle-effects require vision to be visible, we might have been wondering forever why the volcano does not work - even if everything in the script was correct.

Luckily, after a while this general "Spring stuff" becomes more familiar.

{{FIXME}} wording

User:Knorke/Sandbox2

2014-11-05T17:47:00Z

Knorke: templates for tips,fixmes

This text describes making gadgets.

=Gadgets must be in a map or game=
For getting started with a widget, we could just put the file in the spring folder and start coding.
Unlike widgets, gadgets can not be used "locally" like this: They must be contained in a game or map archive.
So we must find a way to put the gadget into the game or map.

{{Tip|If you just want to know "How to set up a test-folder" then skip directly to next chapter.}}

The problem is that games and maps usually come in form of zipped archives, or in case of lobby downloaders as many small files.

[[File:rapid_pool_filedust.png]]

That makes adding new files cumbersome:
#Unpack the archive
#Add the new script file or edit it
#Repack the archive

So we must turn a map or game into an .sdd archive.

That is explain in more detail in general modding tutorial: ADDLINK FIXME

For first experiment it does not matter if the gadget is in the map or in the game.

Another way is to create a test-mutator. That is basically a game that "includes" another game, like an add-on.
The advantages are:
* No need to edit existing game and maybe run into problems.
* The test-game filesize stays small enough to share easily with others, to get help.
* One can still use all the units, features & effects of the original game. That is useful for testing.

Personally I recommend the test-mutator.
XTA is a good canidate as base-game choice because:
*in some ways it is more basic
*the unitnames are human-readable. For example "arm_windgenerator" instead of "armwingntor"
*Some games try to hide as much engine GUI as possible, however for testing that is not so useful.

=The Test Mutator folder=
1) Create folder: games\MyLuaStuff.sdd

2) Create file: games\MyLuaStuff.sdd\modinfo.lua ( [[Modinfo.lua]] )

With this content:
<code><pre>
return {
name='XTA LuaStuff',
description='lolool',
URL='http://code.google.com/p/xta-springrts/',
shortname='XTA',
version = '9.744',
mutator='LuaStuff',
game='Total Annihilation',
shortGame='TA',
depend = {"XTA 9.744"},
modtype=1,
}
</pre></code>
{{FIXME}} mutator details, can it work with any xta version

3) Test with spring.exe if the mutator shows in game list and can be played

=First gadget: Welcome, new unit!=

1) Create folders: games\MyLuaStuff.sdd\LuaRules\gadgets

2) Create file: games\MyLuaStuff.sdd\LuaRules\gadgets\mytestgadget.lua

3) For first widget we had done an empty widget that did nothing. In the widget-selector-menu we could still check if things were working right.
So we just take the Hello-Unit widget example and turn it into a gadget:
<code><pre>
function gadget:GetInfo()
return {
name = "test gadget",
desc = "testing Lua things",
author = "your name",
date = "today",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if gadgetHandler:IsSyncedCode() then

function gadget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("Welcome, new unit!")
end

else --unsynced below

end</pre></code>

We notice it looks very similiar to the widget, except instead of widget::xxx there is gadget:xxx

The GetInfo()-thing again contains some informations about the script, but is otherwise not interessting and to save space will be left out when posting code.

4) Load the game and build a few units. The gadget should welcome each unit.

=Vulcano example=
An example of the process when making gadget.

Pretend you are making a map and want to add a vulcano.
[[File:thinkingAboutVulcano.png]]

{{Tip|If we wanted, at this point we could move the Lua into a map-archive. But for testing it is easier to continue using the test-mutator-game.}}

==Define vulcano problem==
We want to make a vulcano. Now need to think ''what excactly is this vulcano is supposed to do.''
*Should the vulcano damage near units?
*Should it throw burning rocks across the map?
*Should it merely be a visual effect, just some smoke on a hill?

For this tutorial we chose the last option. (superlame!)

==How to make smoke==
Now that we know we want to make smoke, the new question is: How to make smoke?
One way is to use Spring's particle system called [[CEG:Main]]
Games can use these CEGS to create explosion, muzzle flashes, fire and so on.

Since our test-mutator is based on XTA, we can use all its effects.

Here we are going to use the effect "BERTHASHOT" which is defined in the file <code>gamedata\explosions\berthashot.tdf</code>

As the name implies, that effect is usually used when a "Big Bertha" cannon fires a shot. We pick it because it might vaguely look like a smoking vulcano.

==How to spawn the CEG?==
So how can we make this "BERTHASHOT" effect appear on our vulcano hill? Surely there must be some function call...

We clicked arond the [[CEG:Main]] page a bit and discover [[CEG:Calls]]

It seems there are various ways to use CEGs, for example weapons can use them.

Since we already decided we want to make a gadget, the relevant part is [[CEG:Calls#Synced_Lua_Gadget_CEGs]] which brings us to
[[Lua_SyncedCtrl#Other]]

==Spring.SpawnCEG==
On [[Lua_SyncedCtrl#Other]] we discover the function Spring.SpawnCEG and its parameter list:
<code><pre>
( 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
</pre></code>

*It seems to expect the name of the CEG as first parameter.
**We already got a CEG name: "BERTHASHOT"
*The posX,posY,posZ parameters seem to be the coordinates where the effect appears.
**Note to self: Find coordinates of some hill that looks like it needs some smoke.
*We have the effectname and where it should appear. The other parameters seems useless to our purpose so we ignore them.
**They will use default values.

==Location, location, location==
We decide to use the map '''"DesertTriad"'''.

At the bottom right corner there seems a be small hill, perfect vulcano material:

[[File:DesertTriadHillCoordinates.jpg]]

1) The hill where we want smoke to appear.

2) The tooltip that shows the coordinates, when we mouse pointer onto the hill.

Protip: Look at [[Gamedev:UnitsOfMeasurement]] to learn about coordinates system!

==Putting parameters into Spawn.CEG==
Putting it together:
<code><pre>Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)</pre></code>

Where in the gadget should we put that?
Into <code>gadget:UnitFinished()</code> callin, like with the Hello-Unit example?
Then the vulcano would only smoke when a new unit is created.

We need to find a better callin-function from the [[Lua:Callins]] page!

Some callin that gets triggered regularly... so we can have nice constant smoking.

We find:

GameFrame(frame) - ''Called for every game simulation frame (30 per second). ''

...thus we write:
<code><pre>
if gadgetHandler:IsSyncedCode() then

function gadget:GameFrame (f)
if (f%10 == 0) then
Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)
end
end

else --unsynced below

end
</pre></code>

<code>if (f%10 == 0) then</code> is added so that a new effect is only spawned every 10 frames.

Also see http://answers.springlobby.info/questions/412/gadgetgameframe-modulo-operation-explained - oh 404! {{FIXME}}

==Smoke in your eyes==
Save, start spring, look at the mountain.

Do you see smoke? Likely not because this smoke-effect is only visible when units have vision on it.

So either move a unit to the hill or type into chat:
<code><pre>
/cheat
/globallos
</pre></code>

Now we finally see the smoke:

[[File:DesertTriadVulcano.gif]]

==What did we learn?==
Writting the script is just part one part of making gadget.

From programming perspective, the vulcano example is quite simple.

The harder part was...
*finding a starting point
*setting up an editable archive
*finding the right functions
*learning about CEGs
*figuring out general "Spring stuff" like coordinates.

For example had we not known that some particle-effects require vision to be visible, we might have been wondering forever why the vulcano does not work - even if everything in the script was correct.

Luckily, after a while this general "Spring stuff" becomes more familiar.

{{FIXME}} wording

User:Knorke/Sandbox2

2014-11-05T15:20:09Z

Knorke: typos

This text describes making gadgets.

=Gadgets must be in a map or game=
For getting started with a widget, we could just put the file in the spring folder and start coding.
Unlike widgets, gadgets can not be used "locally" like this: They must be contained in a game or map archive.
So we must find a way to put the gadget into the game or map.

'''>>> If you just want to know "How to do this" then skip directly to next chapter. <<<'''

The problem is that games and maps usually come in form of zipped archives, or in case of lobby downloaders as many small files.

[[File:rapid_pool_filedust.png]]

That makes adding new files cumbersome:
#Unpack the archive
#Add the new script file or edit it
#Repack the archive

So we must turn a map or game into an .sdd archive.

That is explain in more detail in general modding tutorial: ADDLINK FIXME

For first experiment it does not matter if the gadget is in the map or in the game.

Another way is to create a test-mutator. That is basically a game that "includes" another game, like an add-on.
The advantages are:
* No need to edit existing game and maybe run into problems.
* The test-game filesize stays small enough to share easily with others, to get help.
* One can still use all the units, features & effects of the original game. That is useful for testing.

Personally I recommend the test-mutator.
XTA is a good canidate as base-game choice because:
*in some ways it is more basic
*the unitnames are human-readable. For example "arm_windgenerator" instead of "armwingntor"
*Some games try to hide as much engine GUI as possible, however for testing that is not so useful.

=The Test Mutator folder=
1) Create folder: games\MyLuaStuff.sdd

2) Create file: games\MyLuaStuff.sdd\modinfo.lua ( [[Modinfo.lua]] )

With this content:
<code><pre>
return {
name='XTA LuaStuff',
description='lolool',
URL='http://code.google.com/p/xta-springrts/',
shortname='XTA',
version = '9.744',
mutator='LuaStuff',
game='Total Annihilation',
shortGame='TA',
depend = {"XTA 9.744"},
modtype=1,
}
</pre></code>
FIXME: mutator details, can it work with any xta version

3) Test with spring.exe if the mutator shows in game list and can be played

=First gadget: Welcome, new unit!=

1) Create folders: games\MyLuaStuff.sdd\LuaRules\gadgets

2) Create file: games\MyLuaStuff.sdd\LuaRules\gadgets\mytestgadget.lua

3) For first widget we had done an empty widget that did nothing. In the widget-selector-menu we could still check if things were working right.
So we just take the Hello-Unit widget example and turn it into a gadget:
<code><pre>
function gadget:GetInfo()
return {
name = "test gadget",
desc = "testing Lua things",
author = "your name",
date = "today",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if gadgetHandler:IsSyncedCode() then

function gadget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("Welcome, new unit!")
end

else --unsynced below

end</pre></code>

We notice it looks very similiar to the widget, except instead of widget::xxx there is gadget:xxx

The GetInfo()-thing again contains some informations about the script, but is otherwise not interessting and to save space will be left out when posting code.

4) Load the game and build a few units. The gadget should welcome each unit.

=Vulcano example=
An example of the process when making gadget.

Pretend you are making a map and want to add a vulcano.
[[File:thinkingAboutVulcano.png]]

''Note:'' If we wanted, at this point we could move the Lua into a map-archive. But for testing it is easier to continue using the test-mutator-game.

==Define vulcano problem==
We want to make a vulcano. Now need to think ''what excactly is this vulcano is supposed to do.''
*Should the vulcano damage near units?
*Should it throw burning rocks across the map?
*Should it merely be a visual effect, just some smoke on a hill?

For this tutorial we chose the last option. (superlame!)

==How to make smoke==
Now that we know we want to make smoke, the new question is: How to make smoke?
One way is to use Spring's particle system called [[CEG:Main]]
Games can use these CEGS to create explosion, muzzle flashes, fire and so on.

Since our test-mutator is based on XTA, we can use all its effects.

Here we are going to use the effect "BERTHASHOT" which is defined in the file <code>gamedata\explosions\berthashot.tdf</code>

As the name implies, that effect is usually used when a "Big Bertha" cannon fires a shot. We pick it because it might vaguely look like a smoking vulcano.

==How to spawn the CEG?==
So how can we make this "BERTHASHOT" effect appear on our vulcano hill? Surely there must be some function call...

We clicked arond the [[CEG:Main]] page a bit and discover [[CEG:Calls]]

It seems there are various ways to use CEGs, for example weapons can use them.

Since we already decided we want to make a gadget, the relevant part is [[CEG:Calls#Synced_Lua_Gadget_CEGs]] which brings us to
[[Lua_SyncedCtrl#Other]]

==Spring.SpawnCEG==
On [[Lua_SyncedCtrl#Other]] we discover the function Spring.SpawnCEG and its parameter list:
<code><pre>
( 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
</pre></code>

*It seems to expect the name of the CEG as first parameter.
**We already got a CEG name: "BERTHASHOT"
*The posX,posY,posZ parameters seem to be the coordinates where the effect appears.
**Note to self: Find coordinates of some hill that looks like it needs some smoke.
*We have the effectname and where it should appear. The other parameters seems useless to our purpose so we ignore them.
**They will use default values.

==Location, location, location==
We decide to use the map '''"DesertTriad"'''.

At the bottom right corner there seems a be small hill, perfect vulcano material:

[[File:DesertTriadHillCoordinates.jpg]]

1) The hill where we want smoke to appear.

2) The tooltip that shows the coordinates, when we mouse pointer onto the hill.

Protip: Look at [[Gamedev:UnitsOfMeasurement]] to learn about coordinates system!

==Putting parameters into Spawn.CEG==
Putting it together:
<code><pre>Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)</pre></code>

Where in the gadget should we put that?
Into <code>gadget:UnitFinished()</code> callin, like with the Hello-Unit example?
Then the vulcano would only smoke when a new unit is created.

We need to find a better callin-function from the [[Lua:Callins]] page!

Some callin that gets triggered regularly... so we can have nice constant smoking.

We find:

GameFrame(frame) - ''Called for every game simulation frame (30 per second). ''

...thus we write:
<code><pre>
if gadgetHandler:IsSyncedCode() then

function gadget:GameFrame (f)
if (f%10 == 0) then
Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)
end
end

else --unsynced below

end
</pre></code>

<code>if (f%10 == 0) then</code> is added so that a new effect is only spawned every 10 frames.

Also see http://answers.springlobby.info/questions/412/gadgetgameframe-modulo-operation-explained - oh 404! (FIXME)

==Smoke in your eyes==
Save, start spring, look at the mountain.

Do you see smoke? Likely not because this smoke-effect is only visible when units have vision on it.

So either move a unit to the hill or type into chat:
<code><pre>
/cheat
/globallos
</pre></code>

Now we finally see the smoke:

[[File:DesertTriadVulcano.gif]]

==What did we learn?==
Writting the script is just part one part of making gadget.

From programming perspective, the vulcano example is quite simple.

The harder part was...
*finding a starting point
*setting up an editable archive
*finding the right functions
*learning about CEGs
*figuring out general "Spring stuff" like coordinates.

For example had we not known that some particle-effects require vision to be visible, we might have been wondering forever why the vulcano does not work - even if everything in the script was correct.

Luckily, after a while this general "Spring stuff" becomes more familiar.

FIXME: wording

User:Knorke/Sandbox2

2014-11-05T00:55:42Z

Knorke: /* Vulcano example */

This text describes making gadgets.

=Gadgets must be in a map or game=
For getting started with a widget, we could just put the file in the spring folder and start coding.
Unlike widgets, gadgets can not be used "locally" like this: They must be contained in a game or map archive.
So we must find a way to put the gadget into the game or map.

'''>>> If you just want to know "How to do this" then skip directly to next chapter. <<<'''

The problem is that games and maps usually come in form of zipped archives, or in case of lobby downloaders as many small files.

[[File:rapid_pool_filedust.png]]

That makes adding new files cumbersome:
#Unpack the archive
#Add the new script file or edit it
#Repack the archive

So we must turn a map or game into an .sdd archive.

That is explain in more detail in general modding tutorial: ADDLINK FIXME

For first experiment it does not matter if the gadget is in the map or in the game.

Another way is to create a test-mutator. That is basically a game that "includes" another game, like an add-on.
The advantages are:
* No need to edit existing game and maybe run into problems.
* The test-game filesize stays small enough to share easily with others, to get help.
* One can still use all the units, features & effects of the original game. That is useful for testing.

Personally I recommend the test-mutator.
XTA is a good canidate as base-game choice because:
*in some ways it is more basic
*the unitnames are human-readable. For example "arm_windgenerator" instead of "armwingntor"
*Some games try to hide as much engine GUI as possible, however for testing that is not so useful.

=The Test Mutator folder=
1) Create folder: games\MyLuaStuff.sdd

2) Create file: games\MyLuaStuff.sdd\modinfo.lua ( [[Modinfo.lua]] )

With this content:
<code><pre>
return {
name='XTA LuaStuff',
description='lolool',
URL='http://code.google.com/p/xta-springrts/',
shortname='XTA',
version = '9.744',
mutator='LuaStuff',
game='Total Annihilation',
shortGame='TA',
depend = {"XTA 9.744"},
modtype=1,
}
</pre></code>
FIXME: mutator details, can it work with any xta version

3) Test with spring.exe if the mutator shows in game list and can be played

=First gadget: Welcome, new unit!=

1) Create folders: games\MyLuaStuff.sdd\LuaRules\gadgets

2) Create file: games\MyLuaStuff.sdd\LuaRules\gadgets\mytestgadget.lua

3) For first widget we had done an empty widget that did nothing. In the widget-selector-menu we could still check if things were working right.
So we just take the Hello-Unit widget example and turn it into a gadget:
<code><pre>
function gadget:GetInfo()
return {
name = "test gadget",
desc = "testing Lua things",
author = "your name",
date = "today",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if gadgetHandler:IsSyncedCode() then

function gadget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("Welcome, new unit!")
end

else --unsynced below

end</pre></code>

We notice it looks very similiar to the widget, except instead of widget::xxx there is gadget:xxx

The GetInfo()-thing again contains some informations about the script, but is otherwise not interessting and to save space will be left out when posting code.

4) Load the game and build a few units. The gadget should welcome each unit.

=Vulcano example=
An example of the process when making gadget.

Pretend you are making a map and want to add a vulcano.
[[File:thinkingAboutVulcano.png]]

''Note:'' If we wanted, at this point we could move the Lua into a map-archive. But for testing it is easier to continue using the test-mutator-game.

==Define vulcano problem==
We want to make a vulcano. Now need to think ''what excactly is this vulcano is supposed to do.''
*Should the vulcano damage near units?
*Should it throw burning rocks across the map?
*Should it merely be a visual effect, just some smoke on a hill?

For this tutorial we just the last option. (superlame!)

==How to make smoke==
Now that we know we want to make smoke, the new question is: How to make smoke?
One way is to use Spring's particle system called [[CEG:Main]]
Games can use these CEGS to create explosion, muzzle flashes, fire and so on.

Since our test-mutator is based on XTA, we can use all its effects.

Here we are going to use the effect "BERTHASHOT" which is defined in the file <code>gamedata\explosions\berthashot.tdf</code>

As the name implies, that effect is usually used when a "Big Bertha" cannon fires a shot. We pick it because it might vaguely look like a smoking vulcano.

==How to spawn the CEG?==
So how can we make this "BERTHASHOT" effect appear on our vulcano hill? Surely there must be some function call...

We clicked arond the [[CEG:Main]] page a bit and discover [[CEG:Calls]]

It seems there are various ways to use CEGs, for example weapons can use them.

Since we already decided we want to make a gadget, the relevant part is [[CEG:Calls#Synced_Lua_Gadget_CEGs]] which brings us to
[[Lua_SyncedCtrl#Other]]

==Spring.SpawnCEG==
On [[Lua_SyncedCtrl#Other]] we discover the function Spring.SpawnCEG and its parameter list:
<code><pre>
( 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
</pre></code>

*It seems to expect the name of the CEG as first parameter.
**We already got a CEG name: "BERTHASHOT"
*The posX,posY,posZ parameters seem to be the coordinates where the effect appears.
**Note to self: Find coordinates of some hill that looks like it needs some smoke.
*We have the effectname and where it should appear. The other parameters seems useless to our purpose so we ignore them.
**They will use default values.

==Location, location, location==
We decide to use the map '''"DesertTriad"'''.

At the bottom right corner there seems a be small hill, perfect vulcano material:

[[File:DesertTriadHillCoordinates.jpg]]

1) The hill where we want smoke to appear.

2) The tooltip that shows the coordinates, when we mouse pointer onto the hill.

Protip: Look at [[Gamedev:UnitsOfMeasurement]] to learn about coordinates system!

==Putting parameters into Spawn.CEG==
Putting it together:
<code><pre>Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)<code><pre>

Where in the gadget should we put that?
Into <code>gadget:UnitFinished()<code> callin, like with the Hello-Unit example?
Then the vulcano would only smoke when a new unit is created.

We need to find a better callin-function from the [[Lua:Callins]] page!

Some callin that gets triggered regularly... so we can have nice constant smoking.

We find:

GameFrame(frame) - ''Called for every game simulation frame (30 per second). ''

...thus we write:
<code><pre>
if gadgetHandler:IsSyncedCode() then

function gadget:GameFrame (f)
if (f%10 == 0) then
Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)
end
end

else --unsynced below

end
</pre></code>

<code>if (f%10 == 0) then</code> is added so that a new effect is only spawned every 10 frames.

Also see http://answers.springlobby.info/questions/412/gadgetgameframe-modulo-operation-explained - oh 404! (FIXME)

==Smoke in your eyes==
Save, start spring, look at the mountain.

Do you see smoke? Likely not because this smoke-effect is only visible when units have vision on it.

So either move a unit to the hill or type into chat:
<code><pre>
/cheat
/globallos
</pre></code>

Now we finally see the smoke:

[[File:DesertTriadVulcano.gif]]

==What did we learn?==
Writting the script is just part one part of making gadget.

From programming perspective, the vulcano example is quite simple.

The harder part was...
*finding a starting point
*setting up an editable archive
*finding the right functions
*learning about CEGs
*figuring out general "Spring stuff" like coordinates.

For example had we not known that some particle-effects require vision to be visible, we might have been wondering forever why the vulcano does not work - even if everything in the script was correct.

Luckily, after a while this general "Spring stuff" becomes more familiar.

FIXME: wording

User:Knorke/Sandbox2

2014-11-05T00:55:12Z

Knorke: /* What did we learn? */

This text describes making gadgets.

=Gadgets must be in a map or game=
For getting started with a widget, we could just put the file in the spring folder and start coding.
Unlike widgets, gadgets can not be used "locally" like this: They must be contained in a game or map archive.
So we must find a way to put the gadget into the game or map.

'''>>> If you just want to know "How to do this" then skip directly to next chapter. <<<'''

The problem is that games and maps usually come in form of zipped archives, or in case of lobby downloaders as many small files.

[[File:rapid_pool_filedust.png]]

That makes adding new files cumbersome:
#Unpack the archive
#Add the new script file or edit it
#Repack the archive

So we must turn a map or game into an .sdd archive.

That is explain in more detail in general modding tutorial: ADDLINK FIXME

For first experiment it does not matter if the gadget is in the map or in the game.

Another way is to create a test-mutator. That is basically a game that "includes" another game, like an add-on.
The advantages are:
* No need to edit existing game and maybe run into problems.
* The test-game filesize stays small enough to share easily with others, to get help.
* One can still use all the units, features & effects of the original game. That is useful for testing.

Personally I recommend the test-mutator.
XTA is a good canidate as base-game choice because:
*in some ways it is more basic
*the unitnames are human-readable. For example "arm_windgenerator" instead of "armwingntor"
*Some games try to hide as much engine GUI as possible, however for testing that is not so useful.

=The Test Mutator folder=
1) Create folder: games\MyLuaStuff.sdd

2) Create file: games\MyLuaStuff.sdd\modinfo.lua ( [[Modinfo.lua]] )

With this content:
<code><pre>
return {
name='XTA LuaStuff',
description='lolool',
URL='http://code.google.com/p/xta-springrts/',
shortname='XTA',
version = '9.744',
mutator='LuaStuff',
game='Total Annihilation',
shortGame='TA',
depend = {"XTA 9.744"},
modtype=1,
}
</pre></code>
FIXME: mutator details, can it work with any xta version

3) Test with spring.exe if the mutator shows in game list and can be played

=First gadget: Welcome, new unit!=

1) Create folders: games\MyLuaStuff.sdd\LuaRules\gadgets

2) Create file: games\MyLuaStuff.sdd\LuaRules\gadgets\mytestgadget.lua

3) For first widget we had done an empty widget that did nothing. In the widget-selector-menu we could still check if things were working right.
So we just take the Hello-Unit widget example and turn it into a gadget:
<code><pre>
function gadget:GetInfo()
return {
name = "test gadget",
desc = "testing Lua things",
author = "your name",
date = "today",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if gadgetHandler:IsSyncedCode() then

function gadget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("Welcome, new unit!")
end

else --unsynced below

end</pre></code>

We notice it looks very similiar to the widget, except instead of widget::xxx there is gadget:xxx

The GetInfo()-thing again contains some informations about the script, but is otherwise not interessting and to save space will be left out when posting code.

4) Load the game and build a few units. The gadget should welcome each unit.

=Vulcano example=
An example of the process when making gadget.

Pretend you are making a map and want to add a vulcano.
[[File::thinkingAboutVulcano.png]]

''Note:'' If we wanted, at this point we could move the Lua into a map-archive. But for testing it is easier to continue using the test-mutator-game.

==Define vulcano problem==
We want to make a vulcano. Now need to think ''what excactly is this vulcano is supposed to do.''
*Should the vulcano damage near units?
*Should it throw burning rocks across the map?
*Should it merely be a visual effect, just some smoke on a hill?

For this tutorial we just the last option. (superlame!)

==How to make smoke==
Now that we know we want to make smoke, the new question is: How to make smoke?
One way is to use Spring's particle system called [[CEG:Main]]
Games can use these CEGS to create explosion, muzzle flashes, fire and so on.

Since our test-mutator is based on XTA, we can use all its effects.

Here we are going to use the effect "BERTHASHOT" which is defined in the file <code>gamedata\explosions\berthashot.tdf</code>

As the name implies, that effect is usually used when a "Big Bertha" cannon fires a shot. We pick it because it might vaguely look like a smoking vulcano.

==How to spawn the CEG?==
So how can we make this "BERTHASHOT" effect appear on our vulcano hill? Surely there must be some function call...

We clicked arond the [[CEG:Main]] page a bit and discover [[CEG:Calls]]

It seems there are various ways to use CEGs, for example weapons can use them.

Since we already decided we want to make a gadget, the relevant part is [[CEG:Calls#Synced_Lua_Gadget_CEGs]] which brings us to
[[Lua_SyncedCtrl#Other]]

==Spring.SpawnCEG==
On [[Lua_SyncedCtrl#Other]] we discover the function Spring.SpawnCEG and its parameter list:
<code><pre>
( 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
</pre></code>

*It seems to expect the name of the CEG as first parameter.
**We already got a CEG name: "BERTHASHOT"
*The posX,posY,posZ parameters seem to be the coordinates where the effect appears.
**Note to self: Find coordinates of some hill that looks like it needs some smoke.
*We have the effectname and where it should appear. The other parameters seems useless to our purpose so we ignore them.
**They will use default values.

==Location, location, location==
We decide to use the map '''"DesertTriad"'''.

At the bottom right corner there seems a be small hill, perfect vulcano material:

[[File:DesertTriadHillCoordinates.jpg]]

1) The hill where we want smoke to appear.

2) The tooltip that shows the coordinates, when we mouse pointer onto the hill.

Protip: Look at [[Gamedev:UnitsOfMeasurement]] to learn about coordinates system!

==Putting parameters into Spawn.CEG==
Putting it together:
<code><pre>Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)<code><pre>

Where in the gadget should we put that?
Into <code>gadget:UnitFinished()<code> callin, like with the Hello-Unit example?
Then the vulcano would only smoke when a new unit is created.

We need to find a better callin-function from the [[Lua:Callins]] page!

Some callin that gets triggered regularly... so we can have nice constant smoking.

We find:

GameFrame(frame) - ''Called for every game simulation frame (30 per second). ''

...thus we write:
<code><pre>
if gadgetHandler:IsSyncedCode() then

function gadget:GameFrame (f)
if (f%10 == 0) then
Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)
end
end

else --unsynced below

end
</pre></code>

<code>if (f%10 == 0) then</code> is added so that a new effect is only spawned every 10 frames.

Also see http://answers.springlobby.info/questions/412/gadgetgameframe-modulo-operation-explained - oh 404! (FIXME)

==Smoke in your eyes==
Save, start spring, look at the mountain.

Do you see smoke? Likely not because this smoke-effect is only visible when units have vision on it.

So either move a unit to the hill or type into chat:
<code><pre>
/cheat
/globallos
</pre></code>

Now we finally see the smoke:

[[File:DesertTriadVulcano.gif]]

==What did we learn?==
Writting the script is just part one part of making gadget.

From programming perspective, the vulcano example is quite simple.

The harder part was...
*finding a starting point
*setting up an editable archive
*finding the right functions
*learning about CEGs
*figuring out general "Spring stuff" like coordinates.

For example had we not known that some particle-effects require vision to be visible, we might have been wondering forever why the vulcano does not work - even if everything in the script was correct.

Luckily, after a while this general "Spring stuff" becomes more familiar.

FIXME: wording

User:Knorke/Sandbox2

2014-11-05T00:52:58Z

Knorke: first version

This text describes making gadgets.

=Gadgets must be in a map or game=
For getting started with a widget, we could just put the file in the spring folder and start coding.
Unlike widgets, gadgets can not be used "locally" like this: They must be contained in a game or map archive.
So we must find a way to put the gadget into the game or map.

'''>>> If you just want to know "How to do this" then skip directly to next chapter. <<<'''

The problem is that games and maps usually come in form of zipped archives, or in case of lobby downloaders as many small files.

[[File:rapid_pool_filedust.png]]

That makes adding new files cumbersome:
#Unpack the archive
#Add the new script file or edit it
#Repack the archive

So we must turn a map or game into an .sdd archive.

That is explain in more detail in general modding tutorial: ADDLINK FIXME

For first experiment it does not matter if the gadget is in the map or in the game.

Another way is to create a test-mutator. That is basically a game that "includes" another game, like an add-on.
The advantages are:
* No need to edit existing game and maybe run into problems.
* The test-game filesize stays small enough to share easily with others, to get help.
* One can still use all the units, features & effects of the original game. That is useful for testing.

Personally I recommend the test-mutator.
XTA is a good canidate as base-game choice because:
*in some ways it is more basic
*the unitnames are human-readable. For example "arm_windgenerator" instead of "armwingntor"
*Some games try to hide as much engine GUI as possible, however for testing that is not so useful.

=The Test Mutator folder=
1) Create folder: games\MyLuaStuff.sdd

2) Create file: games\MyLuaStuff.sdd\modinfo.lua ( [[Modinfo.lua]] )

With this content:
<code><pre>
return {
name='XTA LuaStuff',
description='lolool',
URL='http://code.google.com/p/xta-springrts/',
shortname='XTA',
version = '9.744',
mutator='LuaStuff',
game='Total Annihilation',
shortGame='TA',
depend = {"XTA 9.744"},
modtype=1,
}
</pre></code>
FIXME: mutator details, can it work with any xta version

3) Test with spring.exe if the mutator shows in game list and can be played

=First gadget: Welcome, new unit!=

1) Create folders: games\MyLuaStuff.sdd\LuaRules\gadgets

2) Create file: games\MyLuaStuff.sdd\LuaRules\gadgets\mytestgadget.lua

3) For first widget we had done an empty widget that did nothing. In the widget-selector-menu we could still check if things were working right.
So we just take the Hello-Unit widget example and turn it into a gadget:
<code><pre>
function gadget:GetInfo()
return {
name = "test gadget",
desc = "testing Lua things",
author = "your name",
date = "today",
license = "GNU GPL, v2",
layer = 0,
enabled = true,
}
end

if gadgetHandler:IsSyncedCode() then

function gadget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("Welcome, new unit!")
end

else --unsynced below

end</pre></code>

We notice it looks very similiar to the widget, except instead of widget::xxx there is gadget:xxx

The GetInfo()-thing again contains some informations about the script, but is otherwise not interessting and to save space will be left out when posting code.

4) Load the game and build a few units. The gadget should welcome each unit.

=Vulcano example=
An example of the process when making gadget.

Pretend you are making a map and want to add a vulcano.
[[File::thinkingAboutVulcano.png]]

''Note:'' If we wanted, at this point we could move the Lua into a map-archive. But for testing it is easier to continue using the test-mutator-game.

==Define vulcano problem==
We want to make a vulcano. Now need to think ''what excactly is this vulcano is supposed to do.''
*Should the vulcano damage near units?
*Should it throw burning rocks across the map?
*Should it merely be a visual effect, just some smoke on a hill?

For this tutorial we just the last option. (superlame!)

==How to make smoke==
Now that we know we want to make smoke, the new question is: How to make smoke?
One way is to use Spring's particle system called [[CEG:Main]]
Games can use these CEGS to create explosion, muzzle flashes, fire and so on.

Since our test-mutator is based on XTA, we can use all its effects.

Here we are going to use the effect "BERTHASHOT" which is defined in the file <code>gamedata\explosions\berthashot.tdf</code>

As the name implies, that effect is usually used when a "Big Bertha" cannon fires a shot. We pick it because it might vaguely look like a smoking vulcano.

==How to spawn the CEG?==
So how can we make this "BERTHASHOT" effect appear on our vulcano hill? Surely there must be some function call...

We clicked arond the [[CEG:Main]] page a bit and discover [[CEG:Calls]]

It seems there are various ways to use CEGs, for example weapons can use them.

Since we already decided we want to make a gadget, the relevant part is [[CEG:Calls#Synced_Lua_Gadget_CEGs]] which brings us to
[[Lua_SyncedCtrl#Other]]

==Spring.SpawnCEG==
On [[Lua_SyncedCtrl#Other]] we discover the function Spring.SpawnCEG and its parameter list:
<code><pre>
( 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
</pre></code>

*It seems to expect the name of the CEG as first parameter.
**We already got a CEG name: "BERTHASHOT"
*The posX,posY,posZ parameters seem to be the coordinates where the effect appears.
**Note to self: Find coordinates of some hill that looks like it needs some smoke.
*We have the effectname and where it should appear. The other parameters seems useless to our purpose so we ignore them.
**They will use default values.

==Location, location, location==
We decide to use the map '''"DesertTriad"'''.

At the bottom right corner there seems a be small hill, perfect vulcano material:

[[File:DesertTriadHillCoordinates.jpg]]

1) The hill where we want smoke to appear.

2) The tooltip that shows the coordinates, when we mouse pointer onto the hill.

Protip: Look at [[Gamedev:UnitsOfMeasurement]] to learn about coordinates system!

==Putting parameters into Spawn.CEG==
Putting it together:
<code><pre>Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)<code><pre>

Where in the gadget should we put that?
Into <code>gadget:UnitFinished()<code> callin, like with the Hello-Unit example?
Then the vulcano would only smoke when a new unit is created.

We need to find a better callin-function from the [[Lua:Callins]] page!

Some callin that gets triggered regularly... so we can have nice constant smoking.

We find:

GameFrame(frame) - ''Called for every game simulation frame (30 per second). ''

...thus we write:
<code><pre>
if gadgetHandler:IsSyncedCode() then

function gadget:GameFrame (f)
if (f%10 == 0) then
Spring.SpawnCEG ("BERTHASHOT", 3830, 390, 3600)
end
end

else --unsynced below

end
</pre></code>

<code>if (f%10 == 0) then</code> is added so that a new effect is only spawned every 10 frames.

Also see http://answers.springlobby.info/questions/412/gadgetgameframe-modulo-operation-explained - oh 404! (FIXME)

==Smoke in your eyes==
Save, start spring, look at the mountain.

Do you see smoke? Likely not because this smoke-effect is only visible when units have vision on it.

So either move a unit to the hill or type into chat:
<code><pre>
/cheat
/globallos
</pre></code>

Now we finally see the smoke:

[[File:DesertTriadVulcano.gif]]

==What did we learn?==
Writting the script is just part one part of making gadget.

From programming perspective, the vulcano example is quite simple.

The harder part was...
*finding a starting point
*setting up an editable archive
*finding the right functions
*learning about CEGs
*figuring out general "Spring stuff" like coordinates.

Luckily, after a while this general "Spring stuff" becomes more familiar.
FIXME: wording

File:DesertTriadVulcano.gif

2014-11-05T00:34:50Z

Knorke: animation of lame vulcano made using Spawn.CEG commander is looking at the vulcano. for use in Lua tutorial

animation of lame vulcano made using Spawn.CEG
commander is looking at the vulcano.
for use in Lua tutorial

File:DesertTriadHillCoordinates.jpg

2014-11-05T00:33:46Z

Knorke: Hill on map DesertTriad The tooltip shows hill coordinates for use in Lua tutorial

Hill on map DesertTriad
The tooltip shows hill coordinates
for use in Lua tutorial

File:Rapid pool filedust.png

2014-11-05T00:32:53Z

Knorke: screenshot of pool folder. there is filedust to be seen. for use in Lua tutorial.

screenshot of pool folder.
there is filedust to be seen.
for use in Lua tutorial.

File:ThinkingAboutVulcano.png

2014-11-05T00:32:07Z

Knorke: a person thinking about a vulcano. for use in Lua tutorial.

a person thinking about a vulcano.
for use in Lua tutorial.

Lua Beginners FAQ

2014-09-27T09:46:46Z

Knorke: dead link, tutorial links more clear

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

This page only tries to answer general questions, for more specific Questions please ask in the forum.

==Q: I'm interested in learning to use Lua with Spring. Where should I start?==
A: You can start by reading general Lua tutorials [http://lua-users.org/wiki/LuaTutorial here].
After that, you can try following try using Lua in Spring, for example [[Lua:Tutorial_GettingStarted|by following this tutorial.]]

==Q: Where can I find documentation?==
A: On the [[Lua_Scripting|Lua_Scripting page.]]

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

A: You can't ...
*control the ground LOS (but you can set the los status of units!).

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

A: Notepad or any text editor might be enough. If you are using windows and the text is all garbled, try a programmer's editor. [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++] can read Lua files with syntax highlighting.

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

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

==Q: What is the difference between a widget and a gadget?==

A: A widget is a Lua script that works with LuaUI. A gadget works with LuaRules, LuaCob or LuaGaia. Widgets allow you to customize your interface, and must be unsynced. They can be bundled with the mod or you can save them in your "Spring/LuaUI/Wigets" directory. Gadgets can be synced or unsynced. LuaRules and LuaCob gadgets are usually part of a mod. LuaGaia gadgets should be part of a map. Gadgets can contain both synced and unsynced code.

==Q: Where can I find examples?==

A: The "Spring\examples\Widgets" directory contains many examples. More can be found in almost every game, especially in the [http://zero-k.info/ Zero-K] game.

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

Yes, you can type "/luaui reload" with "/cheats" enabled.
[http://answers.springlobby.info/questions/393/how-can-i-easily-test-my-mod More usefull commands.]

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

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

==Q: How do I print the "UnitDefs[unitDefID]" or "WeaponDefs[weaponDefID]" tables? "for k, v in ipairs(t) do print(k, v) end" does not behave as expected.==

A: Use "for k,v in UnitDefs[unitDefID]:pairs() do print(k, v) end" instead.

==Q: Where can I find help?==

A: There is a [http://springrts.com/phpbb/viewforum.php?f=23 Lua section] in the Spring forums. Probably the most effective way, though, is to join #lua on the lobby.

==Q: Who implemented LuaUI, LuaRules and LuaGaia?==

A: They were written by trepan.
[[Category: Lua]]

Lua:Tutorial GettingStarted

2014-09-25T11:42:11Z

Knorke: /* My first wupdget */ folder Widgets\ might not exist

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

==What this is==
This page explains how to get started making scripts for spring.

==What this is not==
This page does not explains how to make scripts for spring.

This page is not a Lua tutorial.

==Requirements==
* having played spring game for some days
* text editor with synthax coloring
* copy of [[SpringTutorialGame]]
* [http://springfiles.com/spring/spring-maps/aliendesert some small map] because those load faster
* Spring set to [[Springsettings.cfg#Fullscreen|windowed mode]] for easier switching between editor/game
* a very bit familiar with programing (variables, functions, loops, arrays = enough)
* read through [[TestingYourGame|this tips page]] once

==Wupget and friends==
In Spring games there are 3 kinds of Lua scripts.
Crude and simple explaination:
# gadgets: these are the "gameplay logic code."
# widgets: these are for interface.
# unit scripts: animate units & controll their weapons.

Making those 3 is not very different but widgets are the easiest to start with.

There is also 4) functionality provided by the engine.

'''Also look at this:'''

http://springrts.com/mediawiki/images/1/13/Gadgets_widgets_and_friends.png

All 4 are in a constant fight against each other.

==My first wupdget==
The [[SpringTutorialGame]] is simple and good for testing:
You can use any other game but some games block player widgets or are very confusing.

Create a txt file like this and there:
''Spring\LuaUI\Widgets\myfirstwidget.lua''

If the ''Widgets'' folder does not exist, then create it.

Alternative way:
If you already know how to edit game-archives then you can also put''myfirstwidget.lua'' inside the game-archive.

For example: ''SpringTutorialGame.sdd\LuaUI\Widgets\myfirstwidget.lua''

Copypaste this text into the myfirstwidget.lua :
-----
<code><pre>
function widget:GetInfo()
return {
name = "my first widget",
desc = "this is so awesome",
author = "horse 3000",
date = "2009",
license = "GNU GPL, v2 or later",
layer = -10,
enabled = true
}
end
</pre></code>
-----
For now it does not matter what excactly this does but here you can put informations about your widget.

What matters is that without such ''GetInfo()'' function Spring will not load the widget correctly.
It is usually not interessting and will be left out when code is posted, to save screen space.
Of course it must still be there.

Start spring.exe, load a game and press F11. The "widget menu" opens:

http://springrts.com/mediawiki/images/8/80/Widget_F11menu.png

It is likely already filled with some other widgets contained in the game.
Find your new widget in the list. Click on it to turn it on and off: The name in list should go green or red accordingly.

If that works - congratulation: You made a new widget that does excactly nothing.

="Hello unit" wupdget=
Add the following at the end of myfirstwidget.lua:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("a new unit was finished! It belongs to team " .. teamID)
end
</pre></code>

UnitFinished(...) is a [[Lua:Callins|callin function]] : Those are functions that the engine calls when certain events happen.
Captain Obvious has already figured out: This function gets called when a new unit is finished.

Spring.Echo is used to output text to the chat/console.
So this widget should tell when a new unit is made.

4)
Open the widget menu and disable then re-enable your widget: This will reload the widget.
Now build some units to test it.

===Finding errors and infolog.txt===
For test add an error like this:
Spring.Echo (100 + nil)
and reload the widget.
The widgets name is green but turns yellow as soon a unit is build: "nil" can not be used in math like that.

The error is also displayed in chat and [[infolog.txt]]
In that logfile you can look up all errors even if they have disappeared from chat.
Fix the error, reload the widget and it is green again. Oha.

FIXME: expand this

===widget sees you and only you and your allies===
Even if there is a bot/other player building stuff, the widget will not notify on all their new units if they are outside line of sight.
That is because widgets are limited in what they can "see."
The widget only sees what what the player who is running the widget can see, too. This is to prevent cheating.

=="Hello unit" 2 - with markers and advancement==
change the widget to this and guess what it does:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
local x,y,z = Spring.GetUnitPosition (unitID)
Spring.MarkerAddPoint (x,y,z, "a new unit! id=" .. unitID)
end
</pre></code>

It adds a marker point on every new unit!
Note how the unitID parameter from UnitFinished() is passed to GetUnitPosition()

===unitIDs===
Previous paragraph featured ''unitID'' variable.
Every unit, feature or weapon projectile in spring has an ID number:

http://springrts.com/mediawiki/images/3/3c/Units_features_projectiles.png

There are never two units with the same unitID at the same time.

<pre>#YOLO?</pre>
No YOLO: when a unit is destroyed its unitID might be reused later for a different unit.

=a boring counter widget=
A counter that is increased when units are made:

<code><pre>
local counter = 0
function widget:UnitFinished (unitID, unitDefID, teamID)
counter = counter +1
Spring.Echo ("now there are " .. counter .. " units")
if counter > 10 then
Spring.Echo ("wow, more than 10 units!")
end
end
</pre></code>

[[TestingYourGame#Lua|Reload the widget]] and note how the counter gets reseted.
That is how widgets roll: Their variables get cleared on reload.

===boring counter widget with tables===
Imagine you want a counter that stores for each factory how many units it has already produced. One variable will not be enought here but an array can store multiple things.

Arrays in Lua are tables. Read about tables: http://lua-users.org/wiki/TablesTutorial

<code><pre>
local buildCount = {}
function widget:UnitFromFactory(unitID, unitDefID, unitTeam, factoryID, factoryDefID, userOrders)
--read from table how many units this factory already built
local n = buildCount[factoryID]

--was the entry empty?
if n == nil then
n = 0 --if yes, start counting from 0
end
n = n +1 --increase n by 1 (best comment ever)
Spring.Echo ("This was unit number " .. n .. " from factory " .. factoryID)
--store new buildCount for this factory
buildCount[factoryID] = n
end
</pre></code>
UnitFromFactory is basically the same as UnitFinished, but has the usefull ''factoryID'' parameter.
'''Why the if n == nil?'''
In Lua everything not initialized is nil (=nothing) and nil can not be used in any math.

(n = n +1 is a math)

Btw a shorter version could be:
<code><pre>buildCount[factoryID] = (buildCount[factoryID] or 0) + 1</pre></code>

==I made enough "hello world" widgets. What now?==
On [[Lua_Scripting]] the most important are the pages under '''GameState''' and '''Client'''

See these [[TestingYourGame|pro-tips]] to make testing less frustrating.

While widgets are initially easiest to make, soon there is a problem:
widgets are for interface stuff.

That means widgets usually need to either...
* ...draw something on the screen. (for example the health of Commander)
and/or
* ...give orders to units. (for example make Commander automatically run away from danger)

Both graphics and the whole order-system can be bit tricky for starters.
Without graphics and orders, the awesomeness potential of a widget is small.

'''Pro tip:''' gadgets can be awesome without either!

==go go gadgets time!==
We learned widgets can only "look at" the gamestate or do things that players can do, for example ordering units to attack another unit.

On the other hand gadgets are scripts that are able to alter the state of the game.
With gadgets it is possible to implent new game logic like jumpjets, drop pods, tech tree systems, etc.

Unlike widgets, gadgets must be [[Gamedev:Structure#LuaRules.5C|included in a game or in a map.]]

To do so it is best to unpack the game file into an [[Gamedev:Archives|.sdd archive]]

Writing gadgets is similiar to widgets, except the getInfo() header and callin functions are prefixed with <code>gadget:xxx</code> instead of <code>widget:xxx</code>

===synced & unsynced===
Gadgets are split into a synced and into an unsynced part.

In simple terms that means the synced part is usually for controlling the game logic.
The unsynced part is for drawig graphics.

For example look at this lava tide gadget:

http://springrts.com/mediawiki/images/3/33/Beachbuggysuicidecult_lava_sync_unsync.gif

The '''synced''' part is responsible for ''damaging/destroying the units'' in the lava. It actually alters the gamestate.

The '''unsynced''' part is only for ''drawing'' the graphic of the lava. The graphic itself does not influence the gamestate in any way.

In code it looks like this:

<code><pre>
if (gadgetHandler:IsSyncedCode()) then
--synced code
..
damage all units that are underneath the lava tide level
..
else
--unsynced code
..
drawing the lava with GL-api functions
..
end
</pre></code>

Of course that also means that some functions or callins can only be used in synced or unsynced part. For example the synced part can not draw anything and the unsynced part can not spawn units.

Sometimes it is nessecary to transfer some data/information "across the sync-unsynced border" - but the scope of variables is only in the part they were declared in.
In lava-exampe that might be the current height of lava.
How this still works is explained here: [[LuaTutorials::InterCommunications]]

==Look at more examples==
Common hint for learning spring Lua is: ''"Look at some examples in other games."''

But a spring game usually has dozen of wupdgets and only a few are useful examples for beginners. Many scripts deal with some very specifique problem or are just way too long.
Or one has to be familiar with the game to even understand what the script even does.
Or if one wants to use the wupdget in ones own game, suddendly nothing works anymore because it depends on so many configs or other files.

Two simple examples are:

"Linked units" (hub dies, child-units explode too)
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435

"Moveable metal extractor"
http://springrts.com/phpbb/viewtopic.php?f=14&t=26877

---

==Feedback? Questions?==
This page is open for feedback {{forumlink|topic=32047|title=in the forum.}}

[[category: Lua]]

Lua:Callins

2014-07-11T14:53:37Z

Knorke: /* Units */ add: AllowBuilderHoldFire

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

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

== Common ==
{{LuaCallin
|name = Initialize
|params =
|return = none
|description = Called when the addon is (re)loaded.
}}

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

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|params = type, id
|return = number cmdID
|description = Used to set the default command when a unit is selected.
}}

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

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

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

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

{{LuaCallin
|name = GameSetup
|params = state, ready, playerStates
|return = bool success, bool newReady
|description = ???
}}

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

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

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

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

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

{{LuaCallin
|name = LoadProgress
|params = message, replaceLastLine
|return = none
|description = Only available to LuaIntro.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Drawing ===

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

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

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

{{LuaCallin
|name = DrawGenesis
|params =
|return = none
|description = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Synced - Unsynced Shared ==

=== Game ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = UnitCommand
|params = unitID, unitDefID, teamID, cmdID, cmdParams, cmdOptions
|return = none
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = AllowBuilderHoldFire
|params = unitID, unitDefID, action
|return = bool actionAllowed
|description = {{new|98.0}} {{Sourcelinkhash|5a82d750b89e72024bb0bb62cf05ea257737e0ac}} Called when a construction unit wants to "use his nano beams" action can be of following values: CMD.REPAIR, CMD.RECLAIM, CMD.RESTORE, CMD.RESURRECT, CMD.CAPTURE
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = AllowWeaponTarget
|params = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = bool allowed, number priority
|description = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value controls the priority of the target (maximum of <code>1.0</code>).
}}

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

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

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

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

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

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

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

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

{{LuaCallin
|name = ShieldPreDamaged
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = bool handleCollision
|description = Called before any engine shield-vs-projectile logic executes. If the return value is <code>true</code> the gadget handles the collision event and the engine does not remove the projectile.
}}

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

[[Category: Lua]]

EngineChangelogForContentDevs

2014-07-11T14:37:48Z

Knorke: 98.0 small things

==About this page==
This page holds informations about engine changes that are relevant to game/map makers.
The idea is to replace the "make your game ready for next release"-threads with a wiki page because unlike a forumpost, everybody can edit this.
So if you find a thread (or mantis post etc) that explains a fix, please add it here.
{{forumlink|topic=27777|title=Back-link to forum. Use for bumping.}}

==Spring 98.0==
slight changes:
* fix definitions of UnitDef::Is{Strafing,Hovering}AirUnit {{Sourcelinkhash|b95764cd25f1ad6e3972f5fb0d48cd2353a1d23f}}
* experience has slightly different effects: {{Sourcelinkhash|0f59e103731bb1fb7133cd0ea0693affa0372a4a}} , http://springrts.com/mantis/view.php?id=4446

==Spring 97.0==

==Spring 96.0==

==Spring 95.0==
NOT COMPLETE: interessting changes from 25 Aug backwards to Aug 09, 2013

* new folder structure: http://springrts.com/phpbb/viewtopic.php?f=12&t=30044

* the folder "mods" isn't supported any more: {{Sourcelinkhash|7d3830a01c7e81377c1fd3369658d95b82979612}}

'''Lua:'''

* change to weapon indexing in lua gadgets: {{Sourcelinkhash|ba9721b4e4a296f35efd9838a36c94ab7a9f476e}} (likely to cause index out of bounds errors in any gadgets using weapon related API calls) ALL weapon API functions are 1-based now!

* .moveData has been removed, use .moveDef instead {{Sourcelinkhash|4e58b8b0f7af04065878d34e5e17523246739b0c}} (detecting what type of unit a unit is, isCommander etc)

* Spring.GetUnitNearestEnemy doesn't return neutral units anymore

* {{Sourcelinkhash|90c897393de9dbb6ca9b5678c3efef201ee1231c}}
* add third return-value to Spring.GetUnitBlocking

''new functions:''

* {{Sourcelinkhash|90c897393de9dbb6ca9b5678c3efef201ee1231c}}
** add Spring.SetFeatureBlocking
** add Spring.GetFeatureBlockin
** add Spring.SetPieceProjectileParams
*add SetProjectileAlwaysVisible {{Sourcelinkhash|9435ac706c4955e7d7063600fa861d15b0c2bf40}}
* add callins FeatureDamaged and FeaturePreDamaged {{Sourcelinkhash|85779b57d7b45010b3f6e975ce65ca601e36747d}}
* add Spring.GetRadarErrorParams {{Sourcelinkhash|475828d8516e048680c7467cc00085f32867ee0e}}
* add Spring.SetRadarErrorParams see above
* add Spring.SetUnitPosErrorParams {{Sourcelinkhash|0f4ed485d7eeb56b54a1953edfc21512a2b8cb91}}
* add Spring.GetUnitPosErrorParams see above
* add Spring.GetUnitWeaponCanFireunitID, weaponNum {{Sourcelinkhash|66117e4c4d57b511b8818a7f1ad3e2f5d613ede6}}
* add LuaSyncedCtrl: add callouts SetFeatureVelocity and SetFeaturePhysics {{Sourcelinkhash|765994b40633798d88011ddd00cf3f4a8c5a4012}}

* add new Game.constants: Game.gameName, Game.gameVersion, ... {{Sourcelinkhash|a813447139a01deede046723db1194c929f8704c}} See [[Lua_ConstGame]]

'''Misc:'''

armordefs.lua MUST be updated. The fix is to simple the converter loop at end of file: [[Armordefs.lua#Example]]

* load only image formats which work on all platforms, current supported image formats are:
PNG, JPG, TGA, DDS, BMP (note: no more .jp2)

* make Gaia the default feature team, not -1/0

'''Sim'''
* sweepfiring beamlaser works (someone test?) {{Sourcelinkhash|b0295a72c42a828f4dcf9e4672dc1798c6a6abf2}}

'''Someone check if relevant:'''
{{Sourcelinkhash|66a2b96f71ff7f1e8838038f0aeb0d5f45990c22}}
something with startmoving/stopmoving?

{{Sourcelinkhash|e4dc43a3f1d622168a5634030842d6e609a5b30d}}
something startposition bla

==Spring 94.0 (or 93, or 92)==
* gadget:UnitPreDamaged has a new projectileId argument inserted in the middle, so attackerID, attackerDefID, attackerTeam shifted position
* Bomb weapons need a range, or they won't be fired
* Spring.AddUnitDamage requires a weaponDefID (may be a bug, may be corrected for 95) http://springrts.com/mantis/view.php?id=3841
* QueryNanoPiece is called much less often

==Spring 86.0, 87.0==
* {{forumlink|topic=27749|title=movedefs: depthmod is now a subtable.}}
* toairweapon tag has been removed, use onlytargetcategory instead

* {{forumlink|topic=27773&start=45|title=ERROR_TYPE in WeaponDefs __index}} when looping over WeaponDefs - causes several fails.
[http://springrts.com/mantis/view.php?id=3019 mantis 3019] 
fixed in next release.

* builders stop reclaiming sometimes.

fixed for next engine release: http://springrts.com/mantis/view.php?id=3012 
want it to work right now: {{forumlink|topic=27816|title=use a gadget as workaround}}

==Spring 0.83, 84.0, 85.0==
* {{forumlink|topic=26358|title=Make your game ready for the next release!}}
* {{forumlink|topic=27057|title=instant infolog.txt}}

* [http://springrts.com/mantis/view.php?id=2877 Changing of unit's max velocity is no longer possible]
* {{forumlink|topic=23992|title=Announcement: game end condition moved to Lua}}
* {{forumlink|topic=26993|title=Announcement: gui_buildspacing & minimap_startbox removed (0.83)}}
* {{forumlink|topic=26302|title=To Game-Devs: The "n" entry in array-like tables was removed}}
* AttachUnit obeys cantbetransported http://springrts.com/phpbb/viewtopic.php?f=23&t=30468

==Spring 0.82==
* {{forumlink|topic=21883|title= Engine will stop spawning start units and resources.}} Now needs a Lua gadget.

[[Category:Game Dev]]

Armordefs.lua

2014-07-11T14:25:05Z

Knorke: mantis 4450: [PR] Shields having entries in armorDefs

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

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

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

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

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

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

infantry = {
"dude",
},
}

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

return armorDefs</pre></code>

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

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

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

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

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

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

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

[[Category:gamedata]]

Lua SyncedCtrl

2014-06-20T20:23:29Z

Knorke: /* Teams */ AssignPlayerToTeam

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

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

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

= RulesParams =
string values are new since 95.0

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

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

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

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

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

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


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

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

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

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


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

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

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


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

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


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

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

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

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

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

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

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

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

'''Spring.SetUnitFuel'''
( number unitID, number fuel ) -> nil

'''Spring.SetUnitCrashing''' {{new|83.0}}
( number unitID, boolean crashing ) -> boolean success

'''Spring.SetUnitLineage''' Removed from version 83.0 
( number unitID, number teamID [, boolean isRoot] ) -> nil

'''Spring.SetUnitNeutral'''
( number unitID, boolean neutral ) -> nil

'''Spring.SetUnitTarget''' userTarget & sucess new in version 95.0
( number unitID,
number enemyUnitID | number x, number y, number z,
[ boolean dgun = false ], [ boolean userTarget = false ] ) -> success

'''Spring.SetUnitBlocking''' crushable new in version 85.0
( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil

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

'''Spring.SetUnitMetalExtraction'''
( number unitID, number depth [,number range] ) -> nil

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

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

'''Spring.SetUnitArmored''' armorMultiple new in version 0.83.x
( number unitID, boolean armored [, number armorMultiple] ) -> nil

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

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

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,]
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}

'''Spring.SetUnitCollisionVolumeData'''
( number unitID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_NUM_TYPES // number of non-disabled collision volume types
};
enum COLVOL_TESTS {
COLVOL_TEST_DISC = 0,
COLVOL_TEST_CONT = 1,
COLVOL_NUM_TESTS = 2 // number of tests
};
enum COLVOL_AXES {
COLVOL_AXIS_X = 0,
COLVOL_AXIS_Y = 1,
COLVOL_AXIS_Z = 2,
COLVOL_NUM_AXES = 3 // number of collision volume axes
};


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

'''Spring.SetUnitTravel'''
( number unitID, number travel [, number travelPeriod] ) -> nil

'''Spring.SetUnitMoveGoal''' used by default commands to get in build-,attackrange etc.
(number unitID, number goalx, number goaly, number goalz
[, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )
{{new|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]

'''Spring.SetUnitPhysics''' drag new in version 95.0
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
number dragx, number dragy, number dragz,
) -> nil

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

'''Spring.SetUnitDirection''' {{new|90.0}}
( number unitID, number x, number y, number z ) -> nil

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

'''Spring.SetUnitRotation'''
( number unitID, number rotx, number roty, number rotz ) -> nil

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

'''Spring.AddUnitSeismicPing'''
( number unitID, number pingSize ) -> nil

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

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


mpx, mpy, mpz: new middle position of unit

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

relative: are the new coordinates relative to world or unit coordinates?


'''Spring.SetUnitRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

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

== Unit LOS ==
'''Spring.SetUnitCloak'''
( number unitID,
boolean cloaked | number scriptCloak,
[ number decloakDistance | boolean decloakAbs ] ) -> nil


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

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

'''Spring.SetUnitSonarStealth'''
( number unitID, boolean sonarStealth ) -> nil

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

'''Spring.SetUnitAlwaysVisible'''
( number unitID, boolean alwaysVisible ) -> nil

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

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

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

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

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

== Unit Resourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil

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


'''Spring.AddUnitResource'''
( number unitID, string "m" | "e", number amount ) -> nil

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

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

'''Spring.DestroyFeature'''
( number featureID ) -> nil

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

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

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

'''Spring.SetFeatureResurrect'''
( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil

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


'''Spring.SetFeaturePosition'''
( number featureID, number x, number y, number z [, boolean snapToGround]) -> nil

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

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

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

(like their feature counterparts at [[Lua_SyncedCtrl#Unit_Control]])

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

'''Spring.SetFeatureAlwaysVisible'''
( number featureID, boolean enable ) -> nil

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

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

check Spring.SetUnitMidAndAimPos for further explanation of the arguments

'''Spring.SetFeatureRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

'''Spring.SetFeatureBlocking'''
(number featureID, boolean blocking, boolean collidable) --> boolean

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

= Lua to COB =
'''Spring.CallCOBScript'''
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number retArg1, number retArg2, ...

'''Spring.CallCOBScriptCB''' 
broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

'''Spring.GetCOBScriptID'''
( number unitID, string funcName ) -> nil | number funcID

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

'''Spring.GetUnitCOBValue'''
( number unitID [, boolean splitData=false], number COBValue
[, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
-> number result | number result1, number result2
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
 also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]

'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
 also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]

= Give Order =
options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation) 
see [[Lua CMDs]] for relevant constants


'''Spring.GiveOrderToUnit'''
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

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

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

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

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

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

'''Spring.RemoveGrass'''
( number x, number z ) -> nil

== Heightmap ==
Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is Game.squareSize.

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

'''Spring.AdjustHeightMap''' (heightmap[x][z] += height;)
( number x1, number z1 [, number x2, number z2], number height ) -> nil

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

'''Spring.SetHeightMapFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
Example code:<code><pre>
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for x=0,Game.mapSizeX, Game.squareSize do
Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
end
end
end)
</pre></code>
'''Spring.AddHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
the terraform argument is a scaling factor:
so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.

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

'''Spring.SetSmoothMeshFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
'''Spring.AddSmoothMesh''' can only be called in SetSmoothMeshFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetSmoothMesh''' can only be called in SetSmoothMeshFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff

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

== MetalAmount ==
'''Spring.SetMetalAmount''' {{new|83.0}}
( number x, number z, number metalAmount)
x & z coords are in worldspace/16 metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua)

= Command Descriptions =
Doesn't work in unsynced code! 

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil

structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}


'''Spring.InsertUnitCmdDesc'''
( number unitID [, number cmdDescID ] , table cmdArray ) -> nil

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

= Other =
'''Spring.SetNoPause'''
( boolean noPause ) -> nil

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

an ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag)
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]


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

expGrade defines how often UnitExperience() will be called,
it is based on the following equation:
(int) [exp/(exp+1)] / expGrade
If this integer differs from the one before the experience change
it will call UnitExperience().
Also those 3 last params are only available in .cheat


'''Spring.SpawnCEG'''
( string "cegname" | number cegID,
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil | boolean success, cegID
cegID new in 95.0

= Projectiles =
'''Spring.SpawnProjectile'''
( number weaponDefID, table projectileParams ) -> nil | number projectileID
possible keys of projectileParams are:
pos = {number x, number y, number z},
end = {number x, number y, number z},
speed = {number x, number y, number z},
spread = {number x, number y, number z},
error = {number x, number y, number z},
owner = number,
team = number,
ttl = number,
gravity = number,
tracking = number,
maxRange = number,
startAlpha = number,
endAlpha = number,
model = string,
cegTag = string,


'''Spring.SetProjectileTarget'''

Pre 95.0: ( number projectileID,
[ number targetID, string targetTypeStr ] | [ number posX, number posY, number posZ ] )
-> nil | boolean validTarget

Post 95.0: ( number projectileID,
[ number targetID [, number targetType]] | [number posX, number posY, number posZ])
--> nil | boolean validTarget
targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE


'''Spring.SetProjectileMoveControl''' (disables engine movecontrol, so lua can fully control the physics)
( number projID, boolean enable ) -> nil
'''Spring.SetProjectilePosition'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileVelocity'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
( number projID ) -> nil
'''Spring.SetProjectileGravity'''
( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle''' {{new|95.0}} Deprecated
( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed''' {{new|95.0}} Deprecated
( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec''' {{new|95.0}} Deprecated
( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
( number projID, string ceg_name ) -> nil

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

'''Spring.SetProjectileAlwaysVisible''' {{new|95.0}}
(number projectileID, boolean alwaysVisible) --> nil
[[category: Lua]]

Lua UnsyncedRead

2014-06-20T19:52:01Z

Knorke: /* Unsynced Read */ GetClipboard

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

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetReplayLength''' {{new|92.0}}
( ) -> nil | number (in gameframes)
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

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

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] | [number sortType], [bool showPathingPlayers] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}
if pingTime is == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z

'''Spring.TraceScreenRay'''
( number mouseX, number mouseY [, boolean onlyCoords
[, boolean useMinimap [, boolean includeSky [, boolean ignoreWater ] ] ] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

'''Spring.GetPixelDir''' {{New|95.0}}
( number x, number y ) -> number dirx, number diry, number dirz

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean midPos = false ] ) -> nil | number x, number y, number z
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count
== Projectiles ==
'''Spring.GetVisibleProjectiles''' {{New|95.0}}
([ number allyTeamID = -1
[ , boolean addSyncedProjectiles = true
[ , boolean addWeaponProjectiles = true
[ , boolean addPieceProjectiles = true ]]]]
) --> nil | {[1] = projectileID, ...}

== UI ==

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "pathTraversability" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> nil | {
[1] = {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}, ...
}
'''Spring.GetActiveCmdDesc'''
( number index ) -> nil | {
id=number,
type=number,
name=string,
action=string,
tooltip=string,
texture=string,
cursor=string,
hidden=boolean,
disabled=boolean,
showUnique=boolean,
onlyTexture=boolean,
params = { [1] = string, .. }
}
'''Spring.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''
( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed
'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number] = boolean,
...
}
'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

== Config ==
'''Spring.GetConfigParams''' same information as <code>spring --list-config-vars</code>
( ) -> table {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit

== Time ==
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.DiffTimers'''
( timer cur, timer ago, [boolean inMilliseconds]) -> number seconds
{{New|95.0}} optional third argument (boolean) to return dt in milliseconds

== Rendering ==

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

== Logging ==
'''Spring.GetLogSections'''
( ) -> table { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }

== Misc ==
'''Spring.GetClipboard''' {{new|98.0}}
( ) -> string text

[[category: Lua]]

Lua UnsyncedCtrl

2014-06-20T19:51:16Z

Knorke: /* Misc */ Set...

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

<div class="note">
NOTE: 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 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)
( 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
[, number x, number y, number z ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream currently running.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Spring.SetDrawGroundDeferred''' {{New|95.0}}
(boolean) -> nil
'''Spring.SetDrawModelsDeferred''' {{New|95.0}}
(boolean) -> 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.

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

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

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

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

'''Spring.GetConfigInt''' (needs ModUICtrl)
( string name [, number default [, boolean setInOverlay = false]] ) -> nil | number
'''Spring.SetConfigInt''' (needs ModUICtrl)
( string name, number value [, boolean useOverlay = false] ) -> nil
'''Spring.GetConfigString''' (needs ModUICtrl)
( string name [, string default [, boolean setInOverlay = false]] ) -> nil | string
'''Spring.SetConfigString''' (needs ModUICtrl)
( string name, string value [, boolean useOverlay = false] ) -> nil

= World Primitives =
outdated! use opengl api instead!

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

= Sun =
'''Spring.SetSunManualControl'''
( boolean setManualControl ) - > nil

'''Spring.SetSunParameters'''
( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

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

= Misc =

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

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

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

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

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

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

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

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

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

= Rendering =
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,
}

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

[[category: Lua]]

Lua UnsyncedCtrl

2014-06-20T19:47:20Z

Knorke: /* Misc */ GetClipboard

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

<div class="note">
NOTE: 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 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)
( 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
[, number x, number y, number z ]] ) -> nil | boolean true
Allow you to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once 
'''Spring.StopSoundStream'''
( ) -> nil
Terminates any SoundStream currently running.
'''Spring.PauseSoundStream'''
( ) -> nil
'''Spring.SetSoundStreamVolume'''
( number volume ) -> nil

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Spring.SetDrawGroundDeferred''' {{New|95.0}}
(boolean) -> nil
'''Spring.SetDrawModelsDeferred''' {{New|95.0}}
(boolean) -> 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.

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

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

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

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

'''Spring.GetConfigInt''' (needs ModUICtrl)
( string name [, number default [, boolean setInOverlay = false]] ) -> nil | number
'''Spring.SetConfigInt''' (needs ModUICtrl)
( string name, number value [, boolean useOverlay = false] ) -> nil
'''Spring.GetConfigString''' (needs ModUICtrl)
( string name [, string default [, boolean setInOverlay = false]] ) -> nil | string
'''Spring.SetConfigString''' (needs ModUICtrl)
( string name, string value [, boolean useOverlay = false] ) -> nil

= World Primitives =
outdated! use opengl api instead!

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

= Sun =
'''Spring.SetSunManualControl'''
( boolean setManualControl ) - > nil

'''Spring.SetSunParameters'''
( number dirX, number dirY, number dirZ, number dist, number startTime, number orbitTime ) -> nil

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

= Misc =

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

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

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

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

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

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

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

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

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

= Rendering =
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,
}

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

[[category: Lua]]

Lua SyncedCtrl

2014-06-20T19:38:26Z

Knorke: /* Unit Control */ SetUnitMoveGoal: moveRaw

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

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

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

= RulesParams =
string values are new since 95.0

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

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

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

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

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

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


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

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

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

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


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

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


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

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


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

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

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

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

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

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

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

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

'''Spring.SetUnitFuel'''
( number unitID, number fuel ) -> nil

'''Spring.SetUnitCrashing''' {{new|83.0}}
( number unitID, boolean crashing ) -> boolean success

'''Spring.SetUnitLineage''' Removed from version 83.0 
( number unitID, number teamID [, boolean isRoot] ) -> nil

'''Spring.SetUnitNeutral'''
( number unitID, boolean neutral ) -> nil

'''Spring.SetUnitTarget''' userTarget & sucess new in version 95.0
( number unitID,
number enemyUnitID | number x, number y, number z,
[ boolean dgun = false ], [ boolean userTarget = false ] ) -> success

'''Spring.SetUnitBlocking''' crushable new in version 85.0
( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil

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

'''Spring.SetUnitMetalExtraction'''
( number unitID, number depth [,number range] ) -> nil

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

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

'''Spring.SetUnitArmored''' armorMultiple new in version 0.83.x
( number unitID, boolean armored [, number armorMultiple] ) -> nil

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

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

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,]
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}

'''Spring.SetUnitCollisionVolumeData'''
( number unitID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_NUM_TYPES // number of non-disabled collision volume types
};
enum COLVOL_TESTS {
COLVOL_TEST_DISC = 0,
COLVOL_TEST_CONT = 1,
COLVOL_NUM_TESTS = 2 // number of tests
};
enum COLVOL_AXES {
COLVOL_AXIS_X = 0,
COLVOL_AXIS_Y = 1,
COLVOL_AXIS_Z = 2,
COLVOL_NUM_AXES = 3 // number of collision volume axes
};


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

'''Spring.SetUnitTravel'''
( number unitID, number travel [, number travelPeriod] ) -> nil

'''Spring.SetUnitMoveGoal''' used by default commands to get in build-,attackrange etc.
(number unitID, number goalx, number goaly, number goalz
[, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )
{{new|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]

'''Spring.SetUnitPhysics''' drag new in version 95.0
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
number dragx, number dragy, number dragz,
) -> nil

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

'''Spring.SetUnitDirection''' {{new|90.0}}
( number unitID, number x, number y, number z ) -> nil

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

'''Spring.SetUnitRotation'''
( number unitID, number rotx, number roty, number rotz ) -> nil

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

'''Spring.AddUnitSeismicPing'''
( number unitID, number pingSize ) -> nil

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

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


mpx, mpy, mpz: new middle position of unit

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

relative: are the new coordinates relative to world or unit coordinates?


'''Spring.SetUnitRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

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

== Unit LOS ==
'''Spring.SetUnitCloak'''
( number unitID,
boolean cloaked | number scriptCloak,
[ number decloakDistance | boolean decloakAbs ] ) -> nil


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

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

'''Spring.SetUnitSonarStealth'''
( number unitID, boolean sonarStealth ) -> nil

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

'''Spring.SetUnitAlwaysVisible'''
( number unitID, boolean alwaysVisible ) -> nil

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

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

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

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

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

== Unit Resourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil

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


'''Spring.AddUnitResource'''
( number unitID, string "m" | "e", number amount ) -> nil

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

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

'''Spring.DestroyFeature'''
( number featureID ) -> nil

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

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

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

'''Spring.SetFeatureResurrect'''
( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil

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


'''Spring.SetFeaturePosition'''
( number featureID, number x, number y, number z [, boolean snapToGround]) -> nil

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

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

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

(like their feature counterparts at [[Lua_SyncedCtrl#Unit_Control]])

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

'''Spring.SetFeatureAlwaysVisible'''
( number featureID, boolean enable ) -> nil

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

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

check Spring.SetUnitMidAndAimPos for further explanation of the arguments

'''Spring.SetFeatureRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

'''Spring.SetFeatureBlocking'''
(number featureID, boolean blocking, boolean collidable) --> boolean

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

= Lua to COB =
'''Spring.CallCOBScript'''
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number retArg1, number retArg2, ...

'''Spring.CallCOBScriptCB''' 
broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

'''Spring.GetCOBScriptID'''
( number unitID, string funcName ) -> nil | number funcID

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

'''Spring.GetUnitCOBValue'''
( number unitID [, boolean splitData=false], number COBValue
[, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
-> number result | number result1, number result2
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
 also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]

'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
 also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]

= Give Order =
options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation) 
see [[Lua CMDs]] for relevant constants


'''Spring.GiveOrderToUnit'''
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

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

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

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

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

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

'''Spring.RemoveGrass'''
( number x, number z ) -> nil

== Heightmap ==
Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is Game.squareSize.

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

'''Spring.AdjustHeightMap''' (heightmap[x][z] += height;)
( number x1, number z1 [, number x2, number z2], number height ) -> nil

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

'''Spring.SetHeightMapFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
Example code:<code><pre>
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for x=0,Game.mapSizeX, Game.squareSize do
Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
end
end
end)
</pre></code>
'''Spring.AddHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
the terraform argument is a scaling factor:
so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.

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

'''Spring.SetSmoothMeshFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
'''Spring.AddSmoothMesh''' can only be called in SetSmoothMeshFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetSmoothMesh''' can only be called in SetSmoothMeshFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff

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

== MetalAmount ==
'''Spring.SetMetalAmount''' {{new|83.0}}
( number x, number z, number metalAmount)
x & z coords are in worldspace/16 metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua)

= Command Descriptions =
Doesn't work in unsynced code! 

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil

structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}


'''Spring.InsertUnitCmdDesc'''
( number unitID [, number cmdDescID ] , table cmdArray ) -> nil

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

= Other =
'''Spring.SetNoPause'''
( boolean noPause ) -> nil

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

an ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag)
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]


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

expGrade defines how often UnitExperience() will be called,
it is based on the following equation:
(int) [exp/(exp+1)] / expGrade
If this integer differs from the one before the experience change
it will call UnitExperience().
Also those 3 last params are only available in .cheat


'''Spring.SpawnCEG'''
( string "cegname" | number cegID,
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil | boolean success, cegID
cegID new in 95.0

= Projectiles =
'''Spring.SpawnProjectile'''
( number weaponDefID, table projectileParams ) -> nil | number projectileID
possible keys of projectileParams are:
pos = {number x, number y, number z},
end = {number x, number y, number z},
speed = {number x, number y, number z},
spread = {number x, number y, number z},
error = {number x, number y, number z},
owner = number,
team = number,
ttl = number,
gravity = number,
tracking = number,
maxRange = number,
startAlpha = number,
endAlpha = number,
model = string,
cegTag = string,


'''Spring.SetProjectileTarget'''

Pre 95.0: ( number projectileID,
[ number targetID, string targetTypeStr ] | [ number posX, number posY, number posZ ] )
-> nil | boolean validTarget

Post 95.0: ( number projectileID,
[ number targetID [, number targetType]] | [number posX, number posY, number posZ])
--> nil | boolean validTarget
targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE


'''Spring.SetProjectileMoveControl''' (disables engine movecontrol, so lua can fully control the physics)
( number projID, boolean enable ) -> nil
'''Spring.SetProjectilePosition'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileVelocity'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
( number projID ) -> nil
'''Spring.SetProjectileGravity'''
( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle''' {{new|95.0}} Deprecated
( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed''' {{new|95.0}} Deprecated
( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec''' {{new|95.0}} Deprecated
( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
( number projID, string ceg_name ) -> nil

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

'''Spring.SetProjectileAlwaysVisible''' {{new|95.0}}
(number projectileID, boolean alwaysVisible) --> nil
[[category: Lua]]

Games

2014-05-18T09:24:52Z

Knorke: /* Open Source */ removed ST

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| align="center" width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| align="center" width="300px" | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| align="center" | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| align="center" | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| align="center" valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| align="center" | <h2>'''[http://notadota.com/ On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| align="center" | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://notadota.com}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games (P.U.R.E.) include large GPL-friendly content collections.''

{|
|-
| align="center" width="300px" | <h2>[http://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter]</h2>
| width=40 |
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=http://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| align="center" width="300px" | <h2>[http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation]</h2>
| width=40 |
| align="center" width="300px" | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| align="center" |{{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|}

{|
|-
| align="center" width="300px" | <h2>[http://springfiles.com/spring/games/nota-37 NOTA]</h2>
| width=40 |
| align="center" width="300px" | <h2>[[XTA]]</h2>
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://springfiles.com/spring/games/nota-37}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| align="justify" valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
|
| align="justify" valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Spring Tanks

2014-05-18T05:17:57Z

Knorke: {{deprecated}}

{{deprecated}}

= About =
'''Spring Tanks''' started as an experiment.

[http://springrts.com/media.php?tag=game%3A+Spring+Tanks Some screenshots] can seen be in the media section

{{navimgx|xsize=200|ysize=140|image=Springtanks_TVicon.png|link=http://www.youtube.com/watch?v=xlgV64CEE7Q}}
[http://www.youtube.com/watch?v=xlgV64CEE7Q '''Click here for a video!''']

You can play it in both Single & Multiplayer. The Singleplayer is not so much fun because the AI is not very good.

The lobbychannel is '''#springtanks''' (type ''/join #springtanks'' into lobby chat)

The forum is [http://springrts.com/phpbb/viewforum.php?f=68 here]

= Gameplay Description =
Capture the Flag with Tanks. How cool is that?
[http://h-4.abload.de/img/springtanksctfcomic_jpgtbe.jpg So cool that there is a comic about it.]

Each player starts with a squad of tanks, a base and two flags.

Outmanouver the enemy and pick up his flags by touching them with a unit and carry them to your base to score.
Defend your own flags.

The player or team with the highest score after a set timelimit wins.

One could say the gameplay is a strategy game mixed with elements from first person shooters and sports like football.

== Squad System & Wave Respawn ==
Every 30 seconds all destroyed units are respawned.

The respawn timer is shown as a countdown and progress bar in the top right corner.
You can not get more units than your initial squad.

= The Units: =
[[Image:Knorke_Springtanks_startsquadwithnames.pngâ€Ž]]

== Blitz - Car ==
The Blitz Car is unarmed and '''fragile'''.
With its high '''speed''' and good maneuverability it is perfect for sneaky flag capture runs and scouting.

== TakTak - Medium Tank ==
This unit is the '''basis of your squad'''.
It is armed with an automatic dual cannon that offers a high rate of fire.
Armor and mobility are average.

== Thulsa - Heavy Tank ==
A very cumbersome unit.
With the '''large cannon and heavy armor''' this tank dominates the battlefield.
Downside are the low speed and slow turret rotation.
One hit destroys a Blitz Car - if the Thulsa can catch it.

== Flag ==
Drive near an enemy flag to '''pick it up''' then bring it to your Base to score a point.
If the flag carrier is destroyed, the flag falls to the ground.
There it can be picked up again or the flag owner can touch it to return it to his base.
Protect your flags!
Flags are indestructible.

== Base ==
The base is a '''respawn point''' for destroyed units and flags.
You also have to bring enemy flags here to score a point.
The Base is indestructible.

=The Maps=
Only the the listed maps are playable with Spring Tanks.
On other maps no units will be spawned at gamestart.

'''Desert Cliffs''' - 1v1 
http://springfiles.com/spring/spring-maps/desertcliffsv1

'''Aquatic Divide''' - 1v1 
http://springfiles.com/spring/spring-maps/aquaticdividetnm05-v2

'''Eye_Of_Horus_v2''' - 1v1, 3ffa, 4ffa, 2v2 
http://springfiles.com/spring/spring-maps/eye-horus-v2

'''Saltrock Colony''' - 1v1, 3ffa 
http://springfiles.com/spring/spring-maps/saltrockcolonyv2

'''Canyon Crossing''' - 1v1, 3ffa, 4ffa, 2v2 
http://springfiles.com/spring/spring-maps/canyon-crossing

'''Into Battle''' - 1v1 
http://springfiles.com/spring/spring-maps/battle-v3

'''Castles''' - 1v1, 3ffa, 4ffa, 2v2 
http://springfiles.com/spring/spring-maps/castles

'''Mount Dustmore v3''' - 1v1, 3ffa, 4ffa, 2v2 
http://springfiles.com/spring/spring-maps/mountdustmorev3

= Basic Gameplay Tips =
*Pay attention to the respawn timer:
If there are only few seconds left and you rush for the flag, chances are enemy units will respawn near you and destroy your flag carrier.
Sometimes it is better to wait until the enemy has left his respawn area and then go for an easy flag grab.
**Similiar, the timer can help you decide if you need to retreat to protect your flag or if the respawning reinforcements will clear the situation.
*When you play with the "place start position ingame" option, chose carefully.
**If your units respawn all the time in craters or in trees, you only got yourself to blame. So chose a spot with flat land, clear of obstacles.
**If a unit still gets stuck, you can selfdestruct it: select unit and press crtl+d to make it respawn in the next wave.

= Battle Tactics =
*Thulsa Tanks have splash damage and kill a TakTak with 2 hits, only 1 hit is needed for a Blitz Car.
*A slowly retreating Thulsa Tank can kill a large number of TakTaks that attack in a line.
*If you need to kill a Thulsa with TakTaks, swarm it and do not get picked off one by one.
*Lure the enemy away from his base so that you can go for the flag with Blitz Cars from the flank or from the back.
*Pay attention to your attention: If a battle is lost and no advantage can be gained, do no bother with it.
Instead concentrate on the units that can make a difference.

= Advice for Hosting =
*The modoption "gametimelimit" decides how long a game lasts. You can select from 1 to 90 minutes.

*To spawn your own autohost, write this in private to a springie bot:
!spawn mod=springtanks:stable,title=awesome game!,password=

= Playing vs Single Player AI =
Spring Tanks has a build in Single Player menu. 
To open it: 
1) Start Spring.exe, select
*Mod: Spring Tanks
*Map: does not matter (smaller=loads faster but w/e)

2) Click "Test the game"

3) Now the Spring Tanks Single Player Menu should come up.

4) Select one of the challenges and click "Start Game"

5) Spring restarts and you can play!

6) Can you find the easter egg after winning 3 challenges?

'''=>''' You can go back to the menu by pressing ESC.

'''Single Player by hosting a battle in a lobby:'''
*Dont. Try the pre setup matchups first.
*The only AI that knows how to play Spring Tanks is the "Borked Advancer" AI.
*Pay attention to what [http://springrts.com/wiki/Spring_Tanks#The_Maps maps] work.

= Get the game =
Easiest way is to to join the Spring Tanks autohost with your existing spring engine install and whatever lobby you chose to use. The lobby will then download the game file.
==Manual download==
First of, the [http://springrts.com/wiki/Download Spring engine] must already be installed.

'''Game file:''' http://packages.springrts.com/builds/springtanks-RC6.1.sdz

If you know how to use [http://springrts.com/wiki/Dev:LobbyDownloadSystems#Rapid rapid], the rapid tag is: '''springtanks:stable'''

'''Mappack:''' [http://knorke.darkstars.co.uk/springtanks/SpringTanks_mappack2_unzip_to_mapfolder.zip download]

Absolutely needed for single player!

= Hotkeys =
hotkeys specific to Spring Tanks:
v select units carrying a flag
b send unit to home base
esc single player only: open/close the Spring Tanks single player menu
Usefull default hotkeys, regular Spring players will not need to read this.
Most important are:
return/enter chat
tab toggle complete map view (zooms out to show complete map)
s stop. selected unit stops shoting and moving.
shift+clicking make waypoints
f fight: while traveling to destination, unit will engage all enemies on its path
a attack / shot ground
crtl+d blew up selected unit (ie if stuck)
c cockpit view: controll the unit in (buggy) first person mode
ctrl+z select all units of the same type as current selection
p patrol. set up waypoints for a patrol route that the unit will circle on
shif+esc bring up exit menu
F6 sound on/off
pause pause the game. its the key next to print & scroll lock.

= Trouble? =
Such a little troublemaker!

low fps? lol. should not use more cpu/gpu than any other spring game.

If there is a ~1 seconde stutter at game start, that is because of the texture being loaded. Cant do much about it.

If the game game crashes when starting a new game in Single Player, make sure you have the map. (next version will have a check)

Some usefull commands to be entered in chat:
/advshading 0 no reflections on units. can give large fps boost
/advshading 1 turn reflections on units on
/shadows 0 no shadows
/shadows 1 full shadows
/shadows 2 only shadows from units, no terrain shadows
/water 0 most basic water graphics

==Can't Fix==
Starting new games with Single player menu does not work on Mac OS.

= TL;DR =
Tanks. Capture The Flag. Get the map pack. glhf.

Single Player: Read ''Playing vs AI''

=Credits & Making Of=
Credits: http://www.pastebin.com/Wpub9wWw

==Used tools==
Wings 3D, notepad++, [[Upspring]], Irfanview, MS Paint, Audiacity, Fraps, Windows Movie Maker, 7zip, DXTbmp, VirtualDub

=Status=
playing: <del>completly playable on latest stable engine version: 0.82.7.1</del> 
<del>needs fixing to work with newest Spring release 84.0 (will eventually be done)<del> 
development: {{forumlink|thread=26937|title=see forum:}} and http://springrts.com/mantis/view.php?id=4329

paused due to other things being more interessting.

Animation-LuaCallouts

2014-05-03T20:53:20Z

Knorke: /* Localized functions for less typing */ some

== Introduction ==

The new callouts are defined in the Spring.UnitScript table.

Types for arguments are only shown where they're ambiguous. For a number of (common) arguments, the types are:

* unitID: number
* piece: number
* axis: number (1 = x axis, 2 = y axis, 3 = z axis)
* destination: number ([[elmo]]s (linear), [[radian]]s (angular))
* speed: number ([[elmo]]s per second (linear), [[radian]]s per second (angular))
* accel/decel: number ([[radian]]s per second per frame)

== Animation ==

'''Spring.UnitScript.SetPieceVisibility''' ( piece, boolean visible ) -> nil 
'''Spring.UnitScript.Show''' ( piece ) -> nil 
'''Spring.UnitScript.Hide''' ( piece ) -> nil

These may be used to show/hide pieces of the unit's model.

'''Spring.UnitScript.Move''' ( piece, axis, destination[, speed][, updateMatrix]] ) -> nil

Move piece along axis to the destination position. If speed is given, the piece isn't moved immediately, but will move there at the desired speed. The X axis is mirrored compared to BOS/COB scripts, to match the direction of the X axis in Spring world space. The 5th param was introduced in 95.0 and instantly updates the piece position matrix (rather than waiting for the next frame).

'''Spring.UnitScript.Turn''' ( piece, axis, destination[, speed][, updateMatrix]] ) -> nil

Turn piece around axis to the destination angle. If speed is given, the piece isn't rotated immediately, but will turn at the desired angular velocity. Angles are in radians.
Always uses the shortest angular towards destination degree, and if at exactly 180 degrees opposite, will go counter-clockwise. The 5th param was introduced in 95.0 and instantly updates the piece rotation matrix (rather than waiting for the next frame).

'''Spring.UnitScript.Spin''' ( piece, axis, speed[, accel] ) -> nil

Makes piece spin around axis at the desired angular velocity. If accel is given, the piece does not start at this velocity at once, but will accelerate to it. Both negative and positive angular velocities are supported. Accel should always be positive, even if speed is negative.

Beware gimbal lock: http://en.wikipedia.org/wiki/Gimbal_lock

'''Spring.UnitScript.StopSpin''' ( piece, axis[, decel] ) -> nil

Stops a piece from spinning around the given axis. If decel is given, the piece does not stop at once, but will decelerate to it. Decel should always be positive. This function is similar to Spin(piece, axis, 0, decel), however, StopSpin also frees up the animation record.

'''Spring.UnitScript.IsInTurn''' (number piece, number axis) -> boolean 
'''Spring.UnitScript.IsInMove''' (number piece, number axis) -> boolean 
'''Spring.UnitScript.IsInSpin''' (number piece, number axis) -> boolean

Returns true if such an animation exists, false otherwise.

'''Spring.UnitScript.GetPieceTranslation''' ( piece ) -> number x, y, z 
'''Spring.UnitScript.GetPieceRotation''' ( piece ) -> number x, y, z

Get the current translation/rotation of a piece. The returned numbers match the values passed into Move and Turn.

'''Spring.UnitScript.GetPiecePosDir''' ( piece ) -> number px, py, pz, dx, dy, dz

Get the piece's position (px, py, pz) and direction (dx, dy, dz) in '''unit space'''. This is quite similar to ''Spring.GetUnitPiecePosDir'', however that function returns in '''world space'''.

== Threads ==

'''Spring.UnitScript.StartThread''' ( function fun, ... ) -> nil

Starts a new (animation) thread, which will execute the function 'fun'. All arguments except the function to run are passed as-is as arguments to 'fun'. [[Animation-CobThreads|COB-Threads]] has a decent description on COB threads, which are mimicked here in Lua using coroutines.

'''Spring.UnitScript.SetSignalMask''' ( number mask ) -> nil 
'''Spring.UnitScript.Signal''' ( number signal ) -> nil

These two support functions offer a powerful way to kill running threads. SetSignalMask assigns a mask to the currently running thread (any new threads started by this one will inherit the signal mask). Signal immediately stops all threads of this unit for which the bitwise and of mask and signal is not zero.

[http://springrts.com/phpbb/viewtopic.php?f=14&t=26274&start=2| What signal will stop which threads?]

'''Spring.UnitScript.WaitForMove''' ( piece, axis ) -> nil 
'''Spring.UnitScript.WaitForTurn''' ( piece, axis ) -> nil

Waits until the piece has stopped moving along / turning around the axis. If the piece is not animating, this functions return at once. You can not wait for a spin, because a spin does never finish.

'''Spring.UnitScript.Sleep''' ( number milliseconds ) -> nil

Waits a number of milliseconds before returning.

== Effects ==

'''Spring.UnitScript.EmitSfx''' ( piece, number id ) -> nil

Emits a [[CEG]] effect or weapon from the given piece. The id is based on one of the effect or weapon ids defined in the units unitdef. 

If the piece has no geometry, then the sfx is emitted in the +z direction from the origin of the piece.

If the piece has 1 vertex, the emit dir is the vector from the origin to the the position of the first vertex the emit position is the origin of the piece.

If there is more than one vertex in the piece, then the emit vector is the vector pointing from v[0] to v[1], and the emit position is v[0].

Example:

<pre>
--get the id of the CEG effects:
local smokecloud = SFX.CEG --the first effect from the list in the unitdef
local smokecloud2 = SFX.CEG +1 --the second effect from the list in the unitdef
local fire = SFX.CEG +2 --the third effect from the list in the unitdef
--get the id of the emiter piece:
local turret = piece "turret"
EmitSfx(turret, smokecloud) --emit the first effect
</pre>

'''Spring.UnitScript.ShowFlare''' ( number piece ) -> nil

Same as COB's show _inside_ FireWeaponX.

'''Spring.UnitScript.Explode''' ( piece, number flags ) -> nil

Explodes a piece, optionally creating a particle which flies off. Typically used inside Killed. Explode does not hide the piece by itself; if using it outside Killed you may want to Hide the piece immediately after. The flags may be any combination of:
* '''SFX.NONE''': do nothing after creating a heatcloud. Other flags have no effect, except NO_HEATCLOUD. If that is given too, the call is a no-op.
* '''SFX.SHATTER''': shatter the piece in many fragments. Only the NO_HEATCLOUD flag has any effect if this is present.
* '''SFX.EXPLODE''' | '''SFX.EXPLODE_ON_HIT''': the piece that flies of should explode when it hits something.
* '''SFX.FALL''': the piece should be affected by gravity (this is currently always forced on by Spring, to prevent pieces that float in air indefinitely).
* '''SFX.SMOKE''': leave smoke trail.
* '''SFX.FIRE''': the piece is on fire when it flies off.
* '''SFX.NO_CEG_TRAIL''': disable a CEG trail, if present.
* '''SFX.NO_HEATCLOUD''': suppress the heat cloud that's shown by default.

== Other ==

'''Spring.UnitScript.AttachUnit''' ( piece, passengerID ) -> nil 
'''Spring.UnitScript.DropUnit''' ( passengerID ) -> nil

Attaches or detaches another unit (a passenger, as this is designed for transports) to this unit. For AttachUnit, piece specifies the attachment point. Attaching to piece <code>-1</code> makes the passenger unit enter a void state whereby it will never:

# take damage, even from Lua (but can be killed by Lua)
# be rendered through any engine path (nor their icons)
# be intersect-able by either synced or unsynced rays
# block any other objects from existing on top of them
# be selectable

'''Spring.UnitScript.GetUnitValue''' ( ... ) -> number | number, number 
'''Spring.UnitScript.SetUnitValue''' ( ... ) -> nil

This may be used instead of COB's get and set codes. It is recommended however, to use dedicated Lua functions (e.g. Spring.GetUnitHealth(unitID) instead of GetUnitValue(4)): these functions should be considered a relic of the past.

Note that these are identical to Spring.GetUnitCOBValue and Spring.SetUnitCOBValue (see also [[Lua_SyncedCtrl#Lua_to_COB]] for the signature of those functions), except that an unitID argument shouldn't be passed to the versions in the Spring.UnitScript table.

'''Spring.UnitScript.GetLongestReloadTime''' ( unitID ) -> number reloadTime

Returns max(reload time) of all the unit's weapons in milliseconds. This utility function exists to aid in porting BOS scripts, which have a SetMaxReloadTime call-in that is called immediately after Create.

== Internal ==

You generally shouldn't need any of the following call-outs, they are provided by the engine to allow the Lua framework to do it's work.

'''Spring.UnitScript.CreateScript''' ( unitID, table callIns ) -> nil

This deletes the unit's current script (whether it's a COB or Lua script doesn't matter), and sets it up with a brand new Lua unit script, initially registering the call-ins given in the table as (string, function) pairs.

'''Spring.UnitScript.UpdateCallIn''' ( unitID, string name[, function callIn] ) -> nil

This updates a single call-in for the unit's current '''Lua''' unit script. If the unit does not currently have a Lua unit script, an error is raised. If the callIn argument is not given (or nil), the call-in with the given name is removed.

'''Spring.UnitScript.CallAsUnit''' ( unitID, function fun, ... ) -> nil

As none of the call-outs takes a unitID, the engine needs to know the ''active unit'' when one of those is called. Using this function another function can be called with the active unit set arbitrarily.

'''Spring.UnitScript.SetDeathScriptFinished''' ( [number wreckLevel] )

Tells Spring the Killed script finished, and which wreckLevel to use. If wreckLevel is not given no wreck is created. May only be called after Killed has been called. DO NOT USE, the framework handles this transparently (it passes the return value of Killed into this function.)

== Localized functions for less typing ==
In unitscript enviroment some of the '''Spring.UnitScript.xxxxx()''' functions are already localized.
So unless doing anything special, you can save type:
Show (piece)
instead of the longer:
Spring.UnitScript.Show (piece)

[[Category:Animation]]
[[Category:Lua]]

Animation-LuaCallouts

2014-05-01T07:32:38Z

Knorke: Localized functions for less typing

== Introduction ==

The new callouts are defined in the Spring.UnitScript table.

Types for arguments are only shown where they're ambiguous. For a number of (common) arguments, the types are:

* unitID: number
* piece: number
* axis: number (1 = x axis, 2 = y axis, 3 = z axis)
* destination: number ([[elmo]]s (linear), [[radian]]s (angular))
* speed: number ([[elmo]]s per second (linear), [[radian]]s per second (angular))
* accel/decel: number ([[radian]]s per second per frame)

== Animation ==

'''Spring.UnitScript.SetPieceVisibility''' ( piece, boolean visible ) -> nil 
'''Spring.UnitScript.Show''' ( piece ) -> nil 
'''Spring.UnitScript.Hide''' ( piece ) -> nil

These may be used to show/hide pieces of the unit's model.

'''Spring.UnitScript.Move''' ( piece, axis, destination[, speed][, updateMatrix]] ) -> nil

Move piece along axis to the destination position. If speed is given, the piece isn't moved immediately, but will move there at the desired speed. The X axis is mirrored compared to BOS/COB scripts, to match the direction of the X axis in Spring world space. The 5th param was introduced in 95.0 and instantly updates the piece position matrix (rather than waiting for the next frame).

'''Spring.UnitScript.Turn''' ( piece, axis, destination[, speed][, updateMatrix]] ) -> nil

Turn piece around axis to the destination angle. If speed is given, the piece isn't rotated immediately, but will turn at the desired angular velocity. Angles are in radians.
Always uses the shortest angular towards destination degree, and if at exactly 180 degrees opposite, will go counter-clockwise. The 5th param was introduced in 95.0 and instantly updates the piece rotation matrix (rather than waiting for the next frame).

'''Spring.UnitScript.Spin''' ( piece, axis, speed[, accel] ) -> nil

Makes piece spin around axis at the desired angular velocity. If accel is given, the piece does not start at this velocity at once, but will accelerate to it. Both negative and positive angular velocities are supported. Accel should always be positive, even if speed is negative.

Beware gimbal lock: http://en.wikipedia.org/wiki/Gimbal_lock

'''Spring.UnitScript.StopSpin''' ( piece, axis[, decel] ) -> nil

Stops a piece from spinning around the given axis. If decel is given, the piece does not stop at once, but will decelerate to it. Decel should always be positive. This function is similar to Spin(piece, axis, 0, decel), however, StopSpin also frees up the animation record.

'''Spring.UnitScript.IsInTurn''' (number piece, number axis) -> boolean 
'''Spring.UnitScript.IsInMove''' (number piece, number axis) -> boolean 
'''Spring.UnitScript.IsInSpin''' (number piece, number axis) -> boolean

Returns true if such an animation exists, false otherwise.

'''Spring.UnitScript.GetPieceTranslation''' ( piece ) -> number x, y, z 
'''Spring.UnitScript.GetPieceRotation''' ( piece ) -> number x, y, z

Get the current translation/rotation of a piece. The returned numbers match the values passed into Move and Turn.

'''Spring.UnitScript.GetPiecePosDir''' ( piece ) -> number px, py, pz, dx, dy, dz

Get the piece's position (px, py, pz) and direction (dx, dy, dz) in '''unit space'''. This is quite similar to ''Spring.GetUnitPiecePosDir'', however that function returns in '''world space'''.

== Threads ==

'''Spring.UnitScript.StartThread''' ( function fun, ... ) -> nil

Starts a new (animation) thread, which will execute the function 'fun'. All arguments except the function to run are passed as-is as arguments to 'fun'. [[Animation-CobThreads|COB-Threads]] has a decent description on COB threads, which are mimicked here in Lua using coroutines.

'''Spring.UnitScript.SetSignalMask''' ( number mask ) -> nil 
'''Spring.UnitScript.Signal''' ( number signal ) -> nil

These two support functions offer a powerful way to kill running threads. SetSignalMask assigns a mask to the currently running thread (any new threads started by this one will inherit the signal mask). Signal immediately stops all threads of this unit for which the bitwise and of mask and signal is not zero.

[http://springrts.com/phpbb/viewtopic.php?f=14&t=26274&start=2| What signal will stop which threads?]

'''Spring.UnitScript.WaitForMove''' ( piece, axis ) -> nil 
'''Spring.UnitScript.WaitForTurn''' ( piece, axis ) -> nil

Waits until the piece has stopped moving along / turning around the axis. If the piece is not animating, this functions return at once. You can not wait for a spin, because a spin does never finish.

'''Spring.UnitScript.Sleep''' ( number milliseconds ) -> nil

Waits a number of milliseconds before returning.

== Effects ==

'''Spring.UnitScript.EmitSfx''' ( piece, number id ) -> nil

Emits a [[CEG]] effect or weapon from the given piece. The id is based on one of the effect or weapon ids defined in the units unitdef. 

If the piece has no geometry, then the sfx is emitted in the +z direction from the origin of the piece.

If the piece has 1 vertex, the emit dir is the vector from the origin to the the position of the first vertex the emit position is the origin of the piece.

If there is more than one vertex in the piece, then the emit vector is the vector pointing from v[0] to v[1], and the emit position is v[0].

Example:

<pre>
--get the id of the CEG effects:
local smokecloud = SFX.CEG --the first effect from the list in the unitdef
local smokecloud2 = SFX.CEG +1 --the second effect from the list in the unitdef
local fire = SFX.CEG +2 --the third effect from the list in the unitdef
--get the id of the emiter piece:
local turret = piece "turret"
EmitSfx(turret, smokecloud) --emit the first effect
</pre>

'''Spring.UnitScript.ShowFlare''' ( number piece ) -> nil

Same as COB's show _inside_ FireWeaponX.

'''Spring.UnitScript.Explode''' ( piece, number flags ) -> nil

Explodes a piece, optionally creating a particle which flies off. Typically used inside Killed. Explode does not hide the piece by itself; if using it outside Killed you may want to Hide the piece immediately after. The flags may be any combination of:
* '''SFX.NONE''': do nothing after creating a heatcloud. Other flags have no effect, except NO_HEATCLOUD. If that is given too, the call is a no-op.
* '''SFX.SHATTER''': shatter the piece in many fragments. Only the NO_HEATCLOUD flag has any effect if this is present.
* '''SFX.EXPLODE''' | '''SFX.EXPLODE_ON_HIT''': the piece that flies of should explode when it hits something.
* '''SFX.FALL''': the piece should be affected by gravity (this is currently always forced on by Spring, to prevent pieces that float in air indefinitely).
* '''SFX.SMOKE''': leave smoke trail.
* '''SFX.FIRE''': the piece is on fire when it flies off.
* '''SFX.NO_CEG_TRAIL''': disable a CEG trail, if present.
* '''SFX.NO_HEATCLOUD''': suppress the heat cloud that's shown by default.

== Other ==

'''Spring.UnitScript.AttachUnit''' ( piece, passengerID ) -> nil 
'''Spring.UnitScript.DropUnit''' ( passengerID ) -> nil

Attaches or detaches another unit (a passenger, as this is designed for transports) to this unit. For AttachUnit, piece specifies the attachment point. Attaching to piece <code>-1</code> makes the passenger unit enter a void state whereby it will never:

# take damage, even from Lua (but can be killed by Lua)
# be rendered through any engine path (nor their icons)
# be intersect-able by either synced or unsynced rays
# block any other objects from existing on top of them
# be selectable

'''Spring.UnitScript.GetUnitValue''' ( ... ) -> number | number, number 
'''Spring.UnitScript.SetUnitValue''' ( ... ) -> nil

This may be used instead of COB's get and set codes. It is recommended however, to use dedicated Lua functions (e.g. Spring.GetUnitHealth(unitID) instead of GetUnitValue(4)): these functions should be considered a relic of the past.

Note that these are identical to Spring.GetUnitCOBValue and Spring.SetUnitCOBValue (see also [[Lua_SyncedCtrl#Lua_to_COB]] for the signature of those functions), except that an unitID argument shouldn't be passed to the versions in the Spring.UnitScript table.

'''Spring.UnitScript.GetLongestReloadTime''' ( unitID ) -> number reloadTime

Returns max(reload time) of all the unit's weapons in milliseconds. This utility function exists to aid in porting BOS scripts, which have a SetMaxReloadTime call-in that is called immediately after Create.

== Internal ==

You generally shouldn't need any of the following call-outs, they are provided by the engine to allow the Lua framework to do it's work.

'''Spring.UnitScript.CreateScript''' ( unitID, table callIns ) -> nil

This deletes the unit's current script (whether it's a COB or Lua script doesn't matter), and sets it up with a brand new Lua unit script, initially registering the call-ins given in the table as (string, function) pairs.

'''Spring.UnitScript.UpdateCallIn''' ( unitID, string name[, function callIn] ) -> nil

This updates a single call-in for the unit's current '''Lua''' unit script. If the unit does not currently have a Lua unit script, an error is raised. If the callIn argument is not given (or nil), the call-in with the given name is removed.

'''Spring.UnitScript.CallAsUnit''' ( unitID, function fun, ... ) -> nil

As none of the call-outs takes a unitID, the engine needs to know the ''active unit'' when one of those is called. Using this function another function can be called with the active unit set arbitrarily.

'''Spring.UnitScript.SetDeathScriptFinished''' ( [number wreckLevel] )

Tells Spring the Killed script finished, and which wreckLevel to use. If wreckLevel is not given no wreck is created. May only be called after Killed has been called. DO NOT USE, the framework handles this transparently (it passes the return value of Killed into this function.)

== Localized functions for less typing ==
In unitscript enviroment the '''Spring.UnitScript.xxxxx()''' functions are already localized.
So unless doing anything special, you can save type:
Show (piece)
instead of the longer:
Spring.UnitScript.Show (piece)

[[Category:Animation]]
[[Category:Lua]]

Gamedev:Main

2014-04-29T23:23:45Z

Knorke: /* Engine Related */ add links: EngineChangelogForContentDevs and EngineSource_for_GameDevs

[[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]] Particle effects (explosions etc)

; '''Lua API & Libraries''' (excerpt)
* [[Lua_Scripting|Lua API Documentation]]
* [[LUPS]] - Lua Particle System
* [[Chili]] - A GUI Framework
* {{forumlink|topic=28341|title=ChangePiece}} - Switch piece geometry

; '''Animation of units'''
Lua Animations
*[[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]]
**<strike>{{forumlink|topic=132943#132943|title=GPL COB Examples}}</strike> - thread is gone

; '''Models & Textures'''
* [[About_s3o|.s3o]]
* [[Assimp]]
* [[3DModels:Textures]]

; '''Misc'''
* [[Gamedev:Archives]] - packing game/map
* [[Gamedev:Buildpics]]
* [[Gamedev:CollisionVolumes]]
* [[Gamedev:Glossary]]
* [[Gamedev:MouseCursors]]
* [[Gamedev:Sidepics]]
* [[Gamedev:Structure]]
* [[VirtualFileSystem]]

= Tools =
== In-Game Tools ==
*[[ToolBox]] - A Collection of Game Development Tools
*[[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]]

EngineSource for GameDevs

2014-04-29T23:21:32Z

Knorke: /* Intro */ bit clearer

==Intro==
During creation of a Spring game you will soon notice that not every detail is documented.
The most common things can be done without ever looking at the engine. But sometimes there are some specifique questions where one wants more details.

Fortunately, the engine is open source and thus some things can be figured out by looking at it. Wait, isn't that like, super cryptic? Yes, scroll past those parts. A few things are comprehensible.

==Downloading source and opening the files==
Download this https://github.com/spring/spring/zipball/master and unpack the zip file.

==Text==
For example the code to load UnitDefs can be found here:
https://github.com/spring/spring/blob/develop/rts/Sim/Units/UnitDef.cpp

Scroll down to about line 270: 
Notice how there are lines like for example this:

<code>metalStorage = udTable.GetFloat("metalStorage", 0.0f);</code>

The word in double quotes ("metalStorage") is the UnitDef tag as it is read from the unit file.

If a tag can not be found in this file in this form, it is very likely that it does nothing and you can remove it from the unit file.

GetFloat means that this tag is a float number.
The number, in this case 0.0f, is the default value that is used, when the tag can not be found in the unit file.

Since the engine expects a number (eg 100.0) it is understandable that metalStorage = "a lot", or metalStorage=false will not work.

Beside '''GetFloat''' there are:

'''GetBool''' - true or false

'''GetInt''' - an integer number

'''GetString''' - a string, that means a word eg a unit name or a file name

'''GetFloat3''' - 3 floats, for example coordinates in case of "modelCenterOffset" or a vector in case of "flareDropVector"

==Searching text in files==
It is usefull to have an text editor that can search for text in multiple files at once, for example this one: http://notepad-plus-plus.org/

==Interesting files==
Most things outside "Sim" folder are uninteresting.

The files where XY'''defs''' get loaded:

https://github.com/spring/spring/blob/develop/rts/Sim/Units/UnitDef.cpp

https://github.com/spring/spring/blob/develop/rts/Sim/Weapons/WeaponDefHandler.cpp

https://github.com/spring/spring/blob/develop/rts/Sim/Features/FeatureHandler.cpp

https://github.com/spring/spring/blob/develop/rts/Sim/MoveTypes/MoveInfo.cpp

Unit actions (damage, kill, experience,...): 
https://github.com/spring/spring/blob/develop/rts/Sim/Units/Unit.cpp

[[Category:Game Dev]]

Lua:Main

2014-04-24T20:10:02Z

Knorke: /* Tutorials */ add Lua:Tutorial_GettingStarted

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

=Lua FAQ=
[[Lua_Beginners_FAQ]] 
[http://springrts.com/phpbb/viewtopic.php?f=23&t=15596 Forum topic with some basic information about gadgets] 
[http://springrts.com/phpbb/viewtopic.php?f=23&t=16223 Forum topic with a manual on Spring lua scripting]

=Interfaces {{HeaderNotice|(last update: 95.0-dev)}}=
[[:Category:Lua]] (shows which interfaces are loaded by LuaUI,LuaRules,etc.) 
{{LuaInterfaces}}

=Tutorials=
* [[Lua:Tutorial_GettingStarted|Getting Started]] (beginner guide)

* [[LuaTutorials::InterCommunications]] (i.e. synced <-> unsynced communications)

=Other useful information=
* [[Lua:Callins]]
* [[Lua_Performance | Lua performance tips]]
* [http://springrts.com/wiki/COB_Constants#Custom_Variables COB Custom Variables]
* [http://springrts.com/phpbb/viewtopic.php?f=12&t=19560 Font Drawing System]
* [[UI_commands]]
* [[Animation-LuaScripting | Unit animation scripting with Lua]]
* [[LUA ComonPitfalls]]

=Official Lua documentation=
[http://www.lua.org/pil/ 'Programming in Lua' book online] 
[http://www.lua.org/manual/5.1/ Lua 5.1 Reference manual] 
[http://lua-users.org/wiki/TutorialDirectory Lua tutorials]
[[Category: Lua]]

=Widget Database=
[[WidgetDatabaseFAQ]] 
[http://widgets.springrts.de/ Web-Interface]

Lua:Tutorial GettingStarted

2014-04-24T20:08:21Z

Knorke: copy over from User:Knorke/Sandbox1‎ into real page

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

==What this is==
This page explains how to get started making scripts for spring.

==What this is not==
This page does not explains how to make scripts for spring.

This page is not a Lua tutorial.

==Requirements==
* having played spring game for some days
* text editor with synthax coloring
* copy of [[SpringTutorialGame]]
* [http://springfiles.com/spring/spring-maps/aliendesert some small map] because those load faster
* Spring set to [[Springsettings.cfg#Fullscreen|windowed mode]] for easier switching between editor/game
* a very bit familiar with programing (variables, functions, loops, arrays = enough)
* read through [[TestingYourGame|this tips page]] once

==Wupget and friends==
In Spring games there are 3 kinds of Lua scripts.
Crude and simple explaination:
# gadgets: these are the "gameplay logic code."
# widgets: these are for interface.
# unit scripts: animate units & controll their weapons.

Making those 3 is not very different but widgets are the easiest to start with.

There is also 4) functionality provided by the engine.

'''Also look at this:'''

http://springrts.com/mediawiki/images/1/13/Gadgets_widgets_and_friends.png

All 4 are in a constant fight against each other.

==My first wupdget==
The [[SpringTutorialGame]] is simple and good for testing:
You can use any other game but some block player widgets or are very confusing.

Create a txt file like this and there:
Spring\LuaUI\Widgets\myfirstwidget.lua

and copypaste this text into it:
-----
<code><pre>
function widget:GetInfo()
return {
name = "my first widget",
desc = "this is so awesome",
author = "horse 3000",
date = "2009",
license = "GNU GPL, v2 or later",
layer = -10,
enabled = true
}
end
</pre></code>
-----
For now it does not matter what excactly this does but here you can put informations about your widget.

What matters is that without such GetInfo() function Spring will not load the widget correctly.
(Since it takes up screen-space it will be left out when code is posted. Of course it must still be there.)

Start spring.exe and press F11. The "widget menu" opens:

http://springrts.com/mediawiki/images/8/80/Widget_F11menu.png

It is likely already filled with some other widgets contained in the game.
Find your new widget in the list. Click on it to turn it on and off: The name in list should go green or red accordingly.

If that works - congratulation: You made a new widget that does excactly nothing.

="Hello unit" wupdget=
Add the following at the end of myfirstwidget.lua:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("a new unit was finished! It belongs to team " .. teamID)
end
</pre></code>

UnitFinished(...) is a [[Lua:Callins|callin function]] : Those are functions that the engine calls when certain events happen.
Captain Obvious has already figured out: This function gets called when a new unit is finished.

Spring.Echo is used to output text to the chat/console.
So this widget should tell when a new unit is made.

4)
Open the widget menu and disable then re-enable your widget: This will reload the widget.
Now build some units to test it.

===Finding errors and infolog.txt===
For test add an error like this:
Spring.Echo (100 + nil)
and reload the widget.
The widgets name is green but turns yellow as soon a unit is build: "nil" can not be used in math like that.

The error is also displayed in chat and [[infolog.txt]]
In that logfile you can look up all errors even if they have disappeared from chat.
Fix the error, reload the widget and it is green again. Oha.

FIXME: expand this

===widget sees you and only you and your allies===
Even if there is a bot/other player building stuff, the widget will not notify on all their new units if they are outside line of sight.
That is because widgets are limited in what they can "see."
The widget only sees what what the player who is running the widget can see, too. This is to prevent cheating.

=="Hello unit" 2 - with markers and advancement==
change the widget to this and guess what it does:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
local x,y,z = Spring.GetUnitPosition (unitID)
Spring.MarkerAddPoint (x,y,z, "a new unit! id=" .. unitID)
end
</pre></code>

It adds a marker point on every new unit!
Note how the unitID parameter from UnitFinished() is passed to GetUnitPosition()

===unitIDs===
Previous paragraph featured ''unitID'' variable.
Every unit, feature or weapon projectile in spring has an ID number:

http://springrts.com/mediawiki/images/3/3c/Units_features_projectiles.png

There are never two units with the same unitID at the same time.

<pre>#YOLO?</pre>
No YOLO: when a unit is destroyed its unitID might be reused later for a different unit.

=a boring counter widget=
A counter that is increased when units are made:

<code><pre>
local counter = 0
function widget:UnitFinished (unitID, unitDefID, teamID)
counter = counter +1
Spring.Echo ("now there are " .. counter .. " units")
if counter > 10 then
Spring.Echo ("wow, more than 10 units!")
end
end
</pre></code>

[[TestingYourGame#Lua|Reload the widget]] and note how the counter gets reseted.
That is how widgets roll: Their variables get cleared on reload.

===boring counter widget with tables===
Imagine you want a counter that stores for each factory how many units it has already produced. One variable will not be enought here but an array can store multiple things.

Arrays in Lua are tables. Read about tables: http://lua-users.org/wiki/TablesTutorial

<code><pre>
local buildCount = {}
function widget:UnitFromFactory(unitID, unitDefID, unitTeam, factoryID, factoryDefID, userOrders)
--read from table how many units this factory already built
local n = buildCount[factoryID]

--was the entry empty?
if n == nil then
n = 0 --if yes, start counting from 0
end
n = n +1 --increase n by 1 (best comment ever)
Spring.Echo ("This was unit number " .. n .. " from factory " .. factoryID)
--store new buildCount for this factory
buildCount[factoryID] = n
end
</pre></code>
UnitFromFactory is basically the same as UnitFinished, but has the usefull ''factoryID'' parameter.
'''Why the if n == nil?'''
In Lua everything not initialized is nil (=nothing) and nil can not be used in any math.

(n = n +1 is a math)

Btw a shorter version could be:
<code><pre>buildCount[factoryID] = (buildCount[factoryID] or 0) + 1</pre></code>

==I made enough "hello world" widgets. What now?==
On [[Lua_Scripting]] the most important are the pages under '''GameState''' and '''Client'''

See these [[TestingYourGame|pro-tips]] to make testing less frustrating.

While widgets are initially easiest to make, soon there is a problem:
widgets are for interface stuff.

That means widgets usually need to either...
* ...draw something on the screen. (for example the health of Commander)
and/or
* ...give orders to units. (for example make Commander automatically run away from danger)

Both graphics and the whole order-system can be bit tricky for starters.
Without graphics and orders, the awesomeness potential of a widget is small.

'''Pro tip:''' gadgets can be awesome without either!

==go go gadgets time!==
We learned widgets can only "look at" the gamestate or do things that players can do, for example ordering units to attack another unit.

On the other hand gadgets are scripts that are able to alter the state of the game.
With gadgets it is possible to implent new game logic like jumpjets, drop pods, tech tree systems, etc.

Unlike widgets, gadgets must be [[Gamedev:Structure#LuaRules.5C|included in a game or in a map.]]

To do so it is best to unpack the game file into an [[Gamedev:Archives|.sdd archive]]

Writing gadgets is similiar to widgets, except the getInfo() header and callin functions are prefixed with <code>gadget:xxx</code> instead of <code>widget:xxx</code>

===synced & unsynced===
Gadgets are split into a synced and into an unsynced part.

In simple terms that means the synced part is usually for controlling the game logic.
The unsynced part is for drawig graphics.

For example look at this lava tide gadget:

http://springrts.com/mediawiki/images/3/33/Beachbuggysuicidecult_lava_sync_unsync.gif

The '''synced''' part is responsible for ''damaging/destroying the units'' in the lava. It actually alters the gamestate.

The '''unsynced''' part is only for ''drawing'' the graphic of the lava. The graphic itself does not influence the gamestate in any way.

In code it looks like this:

<code><pre>
if (gadgetHandler:IsSyncedCode()) then
--synced code
..
damage all units that are underneath the lava tide level
..
else
--unsynced code
..
drawing the lava with GL-api functions
..
end
</pre></code>

Of course that also means that some functions or callins can only be used in synced or unsynced part. For example the synced part can not draw anything and the unsynced part can not spawn units.

Sometimes it is nessecary to transfer some data/information "across the sync-unsynced border" - but the scope of variables is only in the part they were declared in.
In lava-exampe that might be the current height of lava.
How this still works is explained here: [[LuaTutorials::InterCommunications]]

==Look at more examples==
Common hint for learning spring Lua is: ''"Look at some examples in other games."''

But a spring game usually has dozen of wupdgets and only a few are useful examples for beginners. Many scripts deal with some very specifique problem or are just way too long.
Or one has to be familiar with the game to even understand what the script even does.
Or if one wants to use the wupdget in ones own game, suddendly nothing works anymore because it depends on so many configs or other files.

Two simple examples are:

"Linked units" (hub dies, child-units explode too)
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435

"Moveable metal extractor"
http://springrts.com/phpbb/viewtopic.php?f=14&t=26877

---

==Feedback? Questions?==
This page is open for feedback {{forumlink|topic=32047|title=in the forum.}}

[[category: Lua]]

EvoGreenLitFAQ

2014-04-24T13:21:13Z

Knorke: /* Cannot start command: Downloading Engine 96.0: assign: The parameter is incorrect */ win xp into title

__NOTOC__

'''EvolutionRTS emergency FAQ'''
----

'''Before you ask a question in chat, please see if it is already answered on this list.'''

==Playable at the moment?==
Looks like it!

http://www.vemags.de/wp-content/uploads/2012/06/Status_LSA_gruen1.jpg

There seem to be at least 1, often 2 and more team games running all the time.

==Engine download stuck==

First of all, make sure that your automatic windows updates are enabled. If you disabled them, then most likely you don't have the KB2533623 update that is necessary. Either reenable windows update or install KB2533623 separately if you're a power user.

http://support.microsoft.com/kb/2533623

Close the lobby and start it again.

Look for common\EvolutionRTS\evo_data in your steam folder. If evo_data is not empty, copy everything in it into Documents\My games\Spring\

==Downloads fail (because windows user name has special characters)==
http://i.imgur.com/6qZTQOZ.png

If the lobby states it is downloading the engine but nothing happens:

Check if your windows account name contains any "funny" characters or umlauts like Ã¶Ã¼Ã¤Ã´Ã¡ etc.

As a workaround use a windows account name without such characters. This is will be fixed of course.

==Singleplayer?==
'''Solution:''' Create a multiplayer battleroom with the button at the bottom and make it private by giving it a password. The lobby will download the necessary files and once it's done, you can play. See below for adding bots.

Or go to the Singleplayer tab and create a custom battle (NOT launch game directly) with engine 96.0 and the latest version of Evolution RTS you can find in the list.

==Windows XP: Cannot start command: Downloading Engine 96.0: assign: The parameter is incorrect==

Are you on windows XP? Unfortunately the lobby does not work with Windows XP. You can use the Java Weblobby version by visiting http://www.weblobby.evolutionrts.info directly or you can try a different lobby: http://steamcommunity.com/app/291150/discussions/0/540738051772337468/

==Automatic download of game files does not work==
NOTE: the GAME file, not the engine.

Best idea is to wait a bit, the lobby should eventually download it.
If it really absolutely does not work:
1. Go to http://packages.springrts.com/builds/
2. download the .sdz with the latest evolutionRTS version. (Currently that is 7.37 but check vs what is played in lobby)
3. Put the .sdz file into: Documents/My Games/Spring/games
Do not unzip it, just move it there. When you're done, close and reopen the lobby.

As said, that is only for advanced users and should not be necessary.

==AI does not work!==
The evolutionRTS AI is the "Survial Spawner AI."
It spawns random enemies for you to shot at.

The NullAI bot can also be used: It does ''nothing'' which is nice to try out the game without enemies.

==Sandbox mode? I want to try the game without being rushed!==
Start a singleplayer game against the NullAI bot.

==Missions?==
Not there yet.

==It crashed!==
There is a logfile: [[Infolog.txt]]

The page also explains how to find and share it. You can post it in forum, on steam or in chat.

==Which maps should I play?==
Eye of Horus is a good map that works for team games, free-for-all, 1v1 and with bots.

==Why so many problems?==
Surprised by so many players.

==Hooray, I am ingame! How to play?==
http://www.wiki.evolutionrts.info/doku.php/evolution_rts:quick_start_guide

Or just try out things :)

==How to chat ingame?==
Press the RETURN key and type your message.

==Graphics problems! / the game runs very bad!==
Some problems can probally be solved by the general spring-engine FAQ: [[FAQ:trouble]]

==Cursor is painfully slow!==
Click Settings (the wrench) > Interface > Mouse Cursor > enable Hardware Cursor

==As a player, how can I help?==

1. '''If you have bugs to report''': It is okay to do so in the steam forum: http://steamcommunity.com/app/291150

(Or if you know how to use the google.code bugtracker: https://code.google.com/p/evolutionrts/issues/list )

'''Give as much ''info'' as possible:'''
*Operation system

*computer hardware (laptop or desktop, cpu, ram, graphics card,..)

*This logfile: [[Infolog.txt]]

*Lobby logfile: /Documents/My games/Spring/weblobby/'''weblobby.log''' , share via pastebin.com

*Screenshots can be uploaded to imgur.com or similiar

After a while check back on your post, devs might need more informations from you!

Reporting bugs in chat is pretty much useless, there get overlooked there or forgotten.

2. '''If you can play:''' help others players with their problems in chat.

3. Be patient :)

==More Information About Common Bugs==
https://code.google.com/p/springweblobby/wiki/EvoSteamBugs

User:Knorke/Sandbox1

2014-04-23T22:23:01Z

Knorke:

==What this is==
This page explains how to get started making scripts for spring.

==What this is not==
This page does not explains how to make scripts for spring.

This page is not a Lua tutorial.

==Requirements==
* having played spring game for some days
* text editor with synthax coloring
* copy of [[SpringTutorialGame]]
* [http://springfiles.com/spring/spring-maps/aliendesert some small map] because those load faster
* Spring set to [[Springsettings.cfg#Fullscreen|windowed mode]] for easier switching between editor/game
* a very bit familiar with programing (variables, functions, loops, arrays = enough)
* read through [[TestingYourGame|this tips page]] once

==Wupget and friends==
In Spring games there are 3 kinds of Lua scripts.
Crude and simple explaination:
# gadgets: these are the "gameplay logic code."
# widgets: these are for interface.
# unit scripts: animate units & controll their weapons.

Making those 3 is not very different but widgets are the easiest to start with.

There is also 4) functionality provided by the engine.

'''Also look at this:'''

http://springrts.com/mediawiki/images/1/13/Gadgets_widgets_and_friends.png

All 4 are in a constant fight against each other.

==My first wupdget==
The [[SpringTutorialGame]] is simple and good for testing:
You can use any other game but some block player widgets or are very confusing.

Create a txt file like this and there:
Spring\LuaUI\Widgets\myfirstwidget.lua

and copypaste this text into it:
-----
<code><pre>
function widget:GetInfo()
return {
name = "my first widget",
desc = "this is so awesome",
author = "horse 3000",
date = "2009",
license = "GNU GPL, v2 or later",
layer = -10,
enabled = true
}
end
</pre></code>
-----
For now it does not matter what excactly this does but here you can put informations about your widget.

What matters is that without such GetInfo() function Spring will not load the widget correctly.
(Since it takes up screen-space it will be left out when code is posted. Of course it must still be there.)

Start spring.exe and press F11. The "widget menu" opens:

http://springrts.com/mediawiki/images/8/80/Widget_F11menu.png

It is likely already filled with some other widgets contained in the game.
Find your new widget in the list. Click on it to turn it on and off: The name in list should go green or red accordingly.

If that works - congratulation: You made a new widget that does excactly nothing.

="Hello unit" wupdget=
Add the following at the end of myfirstwidget.lua:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("a new unit was finished! It belongs to team " .. teamID)
end
</pre></code>

UnitFinished(...) is a [[Lua:Callins|callin function]] : Those are functions that the engine calls when certain events happen.
Captain Obvious has already figured out: This function gets called when a new unit is finished.

Spring.Echo is used to output text to the chat/console.
So this widget should tell when a new unit is made.

4)
Open the widget menu and disable then re-enable your widget: This will reload the widget.
Now build some units to test it.

===Finding errors and infolog.txt===
For test add an error like this:
Spring.Echo (100 + nil)
and reload the widget.
The widgets name is green but turns yellow as soon a unit is build: "nil" can not be used in math like that.

The error is also displayed in chat and [[infolog.txt]]
In that logfile you can look up all errors even if they have disappeared from chat.
Fix the error, reload the widget and it is green again. Oha.

FIXME: expand this

===widget sees you and only you and your allies===
Even if there is a bot/other player building stuff, the widget will not notify on all their new units if they are outside line of sight.
That is because widgets are limited in what they can "see."
The widget only sees what what the player who is running the widget can see, too. This is to prevent cheating.

=="Hello unit" 2 - with markers and advancement==
change the widget to this and guess what it does:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
local x,y,z = Spring.GetUnitPosition (unitID)
Spring.MarkerAddPoint (x,y,z, "a new unit! id=" .. unitID)
end
</pre></code>

It adds a marker point on every new unit!
Note how the unitID parameter from UnitFinished() is passed to GetUnitPosition()

===unitIDs===
Previous paragraph featured ''unitID'' variable.
Every unit, feature or weapon projectile in spring has an ID number:

http://springrts.com/mediawiki/images/3/3c/Units_features_projectiles.png

There are never two units with the same unitID at the same time.

<pre>#YOLO?</pre>
No YOLO: when a unit is destroyed its unitID might be reused later for a different unit.

=a boring counter widget=
A counter that is increased when units are made:

<code><pre>
local counter = 0
function widget:UnitFinished (unitID, unitDefID, teamID)
counter = counter +1
Spring.Echo ("now there are " .. counter .. " units")
if counter > 10 then
Spring.Echo ("wow, more than 10 units!")
end
end
</pre></code>

[[TestingYourGame#Lua|Reload the widget]] and note how the counter gets reseted.
That is how widgets roll: Their variables get cleared on reload.

===boring counter widget with tables===
Imagine you want a counter that stores for each factory how many units it has already produced. One variable will not be enought here but an array can store multiple things.

Arrays in Lua are tables. Read about tables: http://lua-users.org/wiki/TablesTutorial

<code><pre>
local buildCount = {}
function widget:UnitFromFactory(unitID, unitDefID, unitTeam, factoryID, factoryDefID, userOrders)
--read from table how many units this factory already built
local n = buildCount[factoryID]

--was the entry empty?
if n == nil then
n = 0 --if yes, start counting from 0
end
n = n +1 --increase n by 1 (best comment ever)
Spring.Echo ("This was unit number " .. n .. " from factory " .. factoryID)
--store new buildCount for this factory
buildCount[factoryID] = n
end
</pre></code>
UnitFromFactory is basically the same as UnitFinished, but has the usefull ''factoryID'' parameter.
'''Why the if n == nil?'''
In Lua everything not initialized is nil (=nothing) and nil can not be used in any math.

(n = n +1 is a math)

Btw a shorter version could be:
<code><pre>buildCount[factoryID] = (buildCount[factoryID] or 0) + 1</pre></code>

==I made enough "hello world" widgets. What now?==
On [[Lua_Scripting]] the most important are the pages under '''GameState''' and '''Client'''

See these [[TestingYourGame|pro-tips]] to make testing less frustrating.

While widgets are initially easiest to make, soon there is a problem:
widgets are for interface stuff.

That means widgets usually need to either...
* ...draw something on the screen. (for example the health of Commander)
and/or
* ...give orders to units. (for example make Commander automatically run away from danger)

Both graphics and the whole order-system can be bit tricky for starters.
Without graphics and orders, the awesomeness potential of a widget is small.

'''Pro tip:''' gadgets can be awesome without either!

==go go gadgets time!==
We learned widgets can only "look at" the gamestate or do things that players can do, for example ordering units to attack another unit.

On the other hand gadgets are scripts that are able to alter the state of the game.
With gadgets it is possible to implent new game logic like jumpjets, drop pods, tech tree systems, etc.

Unlike widgets, gadgets must be [[Gamedev:Structure#LuaRules.5C|included in a game or in a map.]]

To do so it is best to unpack the game file into an [[Gamedev:Archives|.sdd archive]]

Writing gadgets is similiar to widgets, except the getInfo() header and callin functions are prefixed with <code>gadget:xxx</code> instead of <code>widget:xxx</code>

===synced & unsynced===
Gadgets are split into a synced and into an unsynced part.

In simple terms that means the synced part is usually for controlling the game logic.
The unsynced part is for drawig graphics.

For example look at this lava tide gadget:

http://springrts.com/mediawiki/images/3/33/Beachbuggysuicidecult_lava_sync_unsync.gif

The '''synced''' part is responsible for ''damaging/destroying the units'' in the lava. It actually alters the gamestate.

The '''unsynced''' part is only for ''drawing'' the graphic of the lava. The graphic itself does not influence the gamestate in any way.

In code it looks like this:

<code><pre>
if (gadgetHandler:IsSyncedCode()) then
--synced code
..
damage all units that are underneath the lava tide level
..
else
--unsynced code
..
drawing the lava with GL-api functions
..
end
</pre></code>

Of course that also means that some functions or callins can only be used in synced or unsynced part. For example the synced part can not draw anything and the unsynced part can not spawn units.

Sometimes it is nessecary to transfer some data/information "across the sync-unsynced border" - but the scope of variables is only in the part they were declared in.
In lava-exampe that might be the current height of lava.
How this still works is explained here: [[LuaTutorials::InterCommunications]]

==Look at more examples==
Common hint for learning spring Lua is: ''"Look at some examples in other games."''

But a spring game usually has dozen of wupdgets and only a few are useful examples for beginners. Many scripts deal with some very specifique problem or are just way too long.
Or one has to be familiar with the game to even understand what the script even does.
Or if one wants to use the wupdget in ones own game, suddendly nothing works anymore because it depends on so many configs or other files.

Two simple examples are:

"Linked units" (hub dies, child-units explode too)
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435

"Moveable metal extractor"
http://springrts.com/phpbb/viewtopic.php?f=14&t=26877

User:Knorke/Sandbox1

2014-04-23T13:16:50Z

Knorke: /* go go gadgets time! */

==What this is==
This page explains how to get started making scripts for spring.

==What this is not==
This page does not explains how to make scripts for spring.

This page is not a Lua tutorial.

==Requirements==
* having played spring game for some days
* text editor with synthax coloring
* copy of [[SpringTutorialGame]]
* some small map because those load faster
* Spring set to [[Springsettings.cfg#Fullscreen|windowed mode]] for easier switching between editor/game
* a very bit familiar with programing (variables, functions, loops, arrays = enough)
* read through [[TestingYourGame|this tips page]] once

==Wupget and friends==
In Spring games there are 3 kinds of Lua scripts.
Crude and simple explaination:
# gadgets: these are the "gameplay logic code."
# widgets: these are for interface.
# unit scripts: animate units & controll their weapons.

Making those 3 is not very different but widgets are the easiest to start with.

There is also 4) functionality provided by the engine.

'''Also look at this:'''

http://springrts.com/mediawiki/images/1/13/Gadgets_widgets_and_friends.png

All 4 are in a constant fight against each other.

==My first wupdget==
The [[SpringTutorialGame]] is simple and good for testing:
You can use any other game but some block player widgets or are very confusing.

Create a txt file like this and there:
Spring\LuaUI\Widgets\myfirstwidget.lua

and copypaste this text into it:
-----
<code><pre>
function widget:GetInfo()
return {
name = "my first widget",
desc = "this is so awesome",
author = "horse 3000",
date = "2009",
license = "GNU GPL, v2 or later",
layer = -10,
enabled = true
}
end
</pre></code>
-----
For now it does not matter what excactly this does but here you can put informations about your widget.

What matters is that without such GetInfo() function Spring will not load the widget correctly.
(Since it takes up screen-space it will be left out when code is posted. Of course it must still be there.)

Start spring.exe and press F11. The "widget menu" opens:

http://springrts.com/mediawiki/images/8/80/Widget_F11menu.png

It is likely already filled with some other widgets contained in the game.
Find your new widget in the list. Click on it to turn it on and off: The name in list should go green or red accordingly.

If that works - congratulation: You made a new widget that does excactly nothing.

="Hello unit" wupdget=
Add the following at the end of myfirstwidget.lua:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
Spring.Echo ("a new unit was finished! It belongs to team " .. teamID)
end
</pre></code>

UnitFinished(...) is a [[Lua:Callins|callin function]] : Those are functions that the engine calls when certain events happen.
Captain Obvious has already figured out: This function gets called when a new unit is finished.

Spring.Echo is used to output text to the chat/console.
So this widget should tell when a new unit is made.

4)
Open the widget menu and disable then re-enable your widget: This will reload the widget.
Now build some units to test it.

===Finding errors and infolog.txt===
For test add an error like this:
Spring.Echo (100 + nil)
and reload the widget.
The widgets name is green but turns yellow as soon a unit is build: "nil" can not be used in math like that.

The error is also displayed in chat and [[infolog.txt]]
In that logfile you can look up all errors even if they have disappeared from chat.
Fix the error, reload the widget and it is green again. Oha.

FIXME: expand this

===widget sees you and only you and your allies===
Even if there is a bot/other player building stuff, the widget will not notify on all their new units if they are outside line of sight.
That is because widgets are limited in what they can "see."
The widget only sees what what the player who is running the widget can see, too. This is to prevent cheating.

=="Hello unit" 2 - with markers and advancement==
change the widget to this and guess what it does:

<code><pre>
function widget:UnitFinished(unitID, unitDefID, teamID)
local x,y,z = Spring.GetUnitPosition (unitID)
Spring.MarkerAddPoint (x,y,z, "a new unit! id=" .. unitID)
end
</pre></code>

It adds a marker point on every new unit!
Note how the unitID parameter from UnitFinished() is passed to GetUnitPosition()

===unitIDs===
Previous paragraph featured ''unitID'' variable.
Every unit, feature or weapon projectile in spring has an ID number:

http://springrts.com/mediawiki/images/3/3c/Units_features_projectiles.png

There are never two units with the same unitID at the same time.

<pre>#YOLO?</pre>
No YOLO: when a unit is destroyed its unitID might be reused later for a different unit.

=a boring counter widget=
A counter that is increased when units are made:

<code><pre>
local counter = 0
function widget:UnitFinished (unitID, unitDefID, teamID)
counter = counter +1
Spring.Echo ("now there are " .. counter .. " units")
if counter > 10 then
Spring.Echo ("wow, more than 10 units!")
end
end
</pre></code>

[[TestingYourGame#Lua|Reload the widget]] and note how the counter gets reseted.
That is how widgets roll: Their variables get cleared on reload.

===boring counter widget with tables===
Imagine you want a counter that stores for each factory how many units it has already produced. One variable will not be enought here but an array can store multiple things.

Arrays in Lua are tables. Read about tables: http://lua-users.org/wiki/TablesTutorial

<code><pre>
local buildCount = {}
function widget:UnitFromFactory(unitID, unitDefID, unitTeam, factoryID, factoryDefID, userOrders)
--read from table how many units this factory already built
local n = buildCount[factoryID]

--was the entry empty?
if n == nil then
n = 0 --if yes, start counting from 0
end
n = n +1 --increase n by 1 (best comment ever)
Spring.Echo ("This was unit number " .. n .. " from factory " .. factoryID)
--store new buildCount for this factory
buildCount[factoryID] = n
end
</pre></code>
UnitFromFactory is basically the same as UnitFinished, but has the usefull ''factoryID'' parameter.
'''Why the if n == nil?'''
In Lua everything not initialized is nil (=nothing) and nil can not be used in any math.

(n = n +1 is a math)

Btw a shorter version could be:
<code><pre>buildCount[factoryID] = (buildCount[factoryID] or 0) + 1</pre></code>

==I made enough "hello world" widgets. What now?==
On [[Lua_Scripting]] the most important are the pages under '''GameState''' and '''Client'''

See these [[TestingYourGame|pro-tips]] to make testing less frustrating.

While widgets are initially easiest to make, soon there is a problem:
widgets are for interface stuff.

That means widgets usually need to either...
* ...draw something on the screen. (for example the health of Commander)
and/or
* ...give orders to units. (for example make Commander automatically run away from danger)

Both graphics and the whole order-system can be bit tricky for starters.
Without graphics and orders, the awesomeness potential of a widget is small.

'''Pro tip:''' gadgets can be awesome without either!

==go go gadgets time!==
We learned widgets can only "look at" the gamestate or do things that players can do, for example ordering units to attack another unit.

On the other hand gadgets are scripts that are able to alter the state of the game.
With gadgets it is possible to implent new game logic like jumpjets, drop pods, tech tree systems, etc.

Unlike widgets, gadgets must be [[Gamedev:Structure#LuaRules.5C|included in a game or in a map.]]

To do so it is best to unpack the game file into an [[Gamedev:Archives|.sdd archive]]

Writing gadgets is similiar to widgets, except the getInfo() header and callin functions are prefixed with <code>gadget:xxx</code> instead of <code>widget:xxx</code>

===synced & unsynced===
Gadgets are split into a synced and into an unsynced part.

In simple terms that means the synced part is usually for controlling the game logic.
The unsynced part is for drawig graphics.

For example look at this lava tide gadget:

http://springrts.com/mediawiki/images/3/33/Beachbuggysuicidecult_lava_sync_unsync.gif

The '''synced''' part is responsible for ''damaging/destroying the units'' in the lava. It actually alters the gamestate.

The '''unsynced''' part is only for ''drawing'' the graphic of the lava. The graphic itself does not influence the gamestate in any way.

In code it looks like this:

<code><pre>
if (gadgetHandler:IsSyncedCode()) then
--synced code
..
damage all units that are underneath the lava tide level
..
else
--unsynced code
..
drawing the lava with GL-api functions
..
end
</pre></code>

Of course that also means that some functions or callins can only be used in synced or unsynced part. For example the synced part can not draw anything and the unsynced part can not spawn units.

Sometimes it is nessecary to transfer some data/information "across the sync-unsynced border" - but the scope of variables is only in the part they were declared in.
In lava-exampe that might be the current height of lava.
How this still works is explained here: [[LuaTutorials::InterCommunications]]

==Look at more examples==
Common hint for learning spring Lua is: ''"Look at some examples in other games."''

But a spring game usually has dozen of wupdgets and only a few are useful examples for beginners. Many scripts deal with some very specifique problem or are just way too long.
Or one has to be familiar with the game to even understand what the script even does.
Or if one wants to use the wupdget in ones own game, suddendly nothing works anymore because it depends on so many configs or other files.

Two simple examples are:

"Linked units" (hub dies, child-units explode too)
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435

"Moveable metal extractor"
http://springrts.com/phpbb/viewtopic.php?f=14&t=26877