Spring - User contributions [en]

Animation-LuaCallins

2022-11-17T08:30:21Z

Forboding angel: /* Example of parts needed to create a Mobile Builder */

== Introduction ==

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular ''event'' happens.

For Lua unit scripts, a new call-in mechanism has been implemented, which is faster than the regular call-in mechanism used for widgets and gadgets.

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)
* heading/pitch: number (radians)

== Generic ==

'''script.Create''' ( ) -> nil

This is called just after the unit script has been created.

'''script.StartMoving''' ( ) -> nil<br>
'''script.StopMoving''' ( ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation. Since 95.0 they are only run when a unit transitions from zero to non-zero speed or vice versa, and no longer during in-place rotations.

'''script.ChangeHeading''' ( number deltaHeading ) -> nil

{{new|104.0}} Called when the unit changes heading.

'''script.StartSkidding''' ( ) -> nil<br>
'''script.StopSkidding''' ( ) -> nil

{{new|104.0}} Called when a (ground) unit reacts to an impulse. The start-skidding threshold ('sqSkidSpeedMult') is configurable via [[Lua_MoveCtrl#MoveType-Controlling|MoveCtrl.SetGroundMoveTypeData]]

'''script.Killed''' ( number recentDamage, number maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth ''(*100 so that it's in percent, no? at least that is how severity was expressed in Cob/bos, I think. Of course there's no reason to emulate that, just pointing it out for people "converting")''. Typically, this function would play a death animation for the unit, and finally return a corpse type.

'''script.WindChanged''' ( number heading, number strength ) -> nil

This is called for wind generators whenever the wind direction or strength changes.

'''script.ExtractionRateChanged''' ( number rate ) -> nil

Called for metal extractors each time their extraction rate (metal per second) changes.

'''script.setSFXoccupy''' ( number curTerrainType ) -> nil

Called when terrain type changes. Terrain type is calculated with the following rules (in this order):

* If unit is being transported -> curTerrainType = 0
* If ground height < -5 and unit is always upright -> curTerrainType = 2
* If ground height < -5 and unit is not always upright -> curTerrainType = 1
* If ground height < 0 and unit is always upright -> curTerrainType = 1
* Otherwise -> curTerrainType = 4

Where is curTerrainType = 3 ? :-)

Candidate to be changed to something saner later on.

'''script.MoveRate''' ( number curRate ) -> nil

Called only for certain types of aircraft (those which use ''CTAAirMoveType''.) The move rate is determined by the following rules (in this order):

* If the aircraft is landing or taking off -> curRate = 1
* Otherwise -> curRate = floor(curSpeed / maxSpeed * 3), clamped to be in the range [0, 2]

'''script.QueryLandingPads''' ( ) -> { number piece1, number piece2, ... }

Called one time for units with landing pads. Should return a table with pieces which should be used as landing pads. The number of pieces returned also determines the number of pads, so for Lua unit scripts there is no QueryLandingPadCount.

'''script.Activate''' ( ) -> nil<br>
'''script.Deactivate''' ( ) -> nil

Exact situation these are called depends a lot on the unit type. Factories are activated when they open their yard and deactivated when they close it. Aircraft are activated when they take off and deactivated when the land. Any unit that can be turned on or off is activated when it's turned on and deactivated when it's turned off. On ''script.SetUnitValue(COB.ACTIVATION, ...)'' one of these call-ins may be called too.

== Weapons ==

Weapon functions come in two variants.

* Separate function with numeric weapon number suffix. (e.g. ''script.AimWeapon<u>1</u>(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(<u>weaponNum</u>, heading, pitch)'')

Only the first variant is listed here, so whenever you see a function whose name ends with a numeric one ("1"), you should either replace it with the actual weapon number, or you can write a single combined function that takes a ''weaponNum'' argument. For each script, all functions should use the same variant. Either all using name suffix, or all using combined functions.

'''script.QueryWeapon1''' ( ) -> number piece<br>
'''script.AimFromWeapon1''' ( ) -> number piece<br>
'''script.AimWeapon1''' ( heading, pitch ) -> boolean<br>
'''script.AimShield1''' ( ) -> boolean

Weapon support. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired. AimWeapon is called repeatedly, at a rate determined by the {{xtaglink|Gamedev:WeaponDefs|fireTolerance}} tag.

'''script.FireWeapon1''' ( ) -> nil<br>
'''script.Shot1''' ( ) -> nil<br>
'''script.EndBurst1''' ( ) -> nil

If after aiming the unit actually fires it's weapon, FireWeapon is called once at the beginning of the salvo. Shot is called just before each projectile is fired. RockUnit (see below) is called just after all projectiles for that frame have been fired. At the end of the salvo, EndBurst is called.

Of these call-ins, FireWeapon is the more generic one and Shot and EndBurst are more specialized. FireWeapon is usually used to play a recoil animation or emit some smoke near the weapon's barrel using EmitSfx.

'''script.BlockShot1''' ( targetUnitID, boolean userTarget ) -> boolean

Allows you to block a weapon from shooting. TargetUnitID may be nil: in this case the unit has a ground-attack order.

'''script.TargetWeight1''' ( targetUnitID ) -> number

Allows you to tweak the priority of the target for this particular weapon. The target priority is multiplied by the return value of this function. Lower priority targets are targeted first, so return a value smaller than 1 to prioritize a target, or return a value larger than 1 to avoid a target.

The exact behavior of specific values shouldn't be relied upon.

'''script.RockUnit''' ( x, z ) -> nil

A bit like the weapon-specific FireWeapon function, although this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to â€œrockâ€ the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truly realistic rock direction it needs to be rotated according to the unit's current heading.

'''script.HitByWeapon''' ( x, z, weaponDefID, damage ) -> nil | number newDamage

This is called if a unit has been hit by a weapon. (x, z) is the direction from which the projectile came in unit space (the reverse direction of the impulse, to be exact.) It also gets the weaponDefID of the weapon which is dealing the damage, and the amount of damage. If HitByWeapon returns a number, this number will replace the damage value calculated by the engine.

Note: Pre Spring 95, this call-in runs just before the LuaRules UnitPreDamaged callin (see also [[LuaCallinReturn]]). If HitByWeapon overrides the damage, UnitPreDamaged will see the new damage value, and may override again the damage value. Starting Spring 95, it is run after UnitPreDamaged.

== Builders and factories ==

'''script.StartBuilding''' ( heading, pitch ) -> nil<br>
'''script.StartBuilding''' ( ) -> nil<br>
'''script.StopBuilding''' ( ) -> nil

These notify the script when a builder or factory starts or stops building.

The first variant (with heading and pitch arguments) is called for builders. For factories, the second variant is used. In this case the heading and pitch are not necessary, because the factory script specifies the build location itself using QueryBuildInfo.

BTW, don't forget to set INBUILDSTANCE to 1 to start building! For lua script, that is

<nowiki>
function script.StartBuilding(heading, pitch)
SetUnitValue(COB.INBUILDSTANCE, 1)
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
end
</nowiki>

'''script.QueryBuildInfo''' ( ) -> number piece

For factories only. Should return the piece to which the unit which is going to be build will be attached while it's being build.

'''script.QueryNanopiece''' ( ) -> number piece

Called each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

<span class="note">N.B. As of 92.0 the results are cached and the function is called 31 times only. Deprecated in favour of Spring.SetUnitNanoPieces, which disables this callin when used.</span>

=== Example of what is needed to create a Mobile Builder ===
<nowiki>
local nanoPieces = {[0] = nanopoint1}
local SIG_AIM = 2

-- Add this to create()
Spring.SetUnitNanoPieces(unitID, nanoPieces)
--

function RestoreAfterDelay()
SetSignalMask(SIG_AIM)
if building == false then
Sleep(2000)
end
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
building = false
StartThread(RestoreAfterDelay)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
end

function script.StartBuilding(heading, pitch)
Signal(SIG_AIM)
SetUnitValue(COB.INBUILDSTANCE, 1)
building = true
end

function script.QueryNanoPiece()
local nano = nanoPieces[nanoNum]
return nano
end
</nowiki>

== Transports ==

There are some different code paths inside Spring related to transports, each (unfortunately) also associated with a different set of unit script call-ins.

This table shows for the three different {{xtaglink|Gamedev:UnitDefs|transportUnloadMethod}} for both air transports and ground transports which callins are used and roughly when and how often they are called. Refer to the documentation below for a description of the call-ins.

The entire behavior around transports should be considered subject to change; it is obvious it is far from a perfect design currently.

{|border="1" style="border-spacing:0px;"
|+
!
!Load
!UnloadLand (0)
!UnloadDrop (1)
!UnloadLandFlood (2)
|-
|
|
|default unload
|fly over and drop unit
|land, then release all units at once
|-
|air
|BeginTransport (each)<br>QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first)<br>TransportDrop (each)<br>EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each)<br>EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil<br>
'''script.QueryTransport''' ( passengerID ) -> number piece

For an air transport, if any one unit is picked up, these two are called in succession and the passenger is attached to the piece returned by the second one.

'''script.StartUnload''' ( ) -> nil

Only called in UnloadLandFlood behavior. Signals the start of an unload cycle.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Only called in UnloadLandFlood behavior. Called when a passenger will be unloaded. Contrary to ground transports, Spring will detach the passenger after the call.

'''script.EndTransport''' ( ) -> nil

In UnloadLand and UnloadLandFlood behaviors, these are called one time after all units are unloaded. (The transport is empty.) For the UnloadDrop behavior, this is called for every unit that is unloaded.

==== Example of what is needed for an air Transport ====
<nowiki>
-- This assumes that the name of the piece where you want to attach the unit is "link"
function script.BeginTransport(passengerID)
local unitHeight = Spring.GetUnitHeight(passengerID) -- This moves the unit down so that it appears as though the top of it is attached to where the link piece was set (usually underneath the transport)
Move(link, y_axis, -unitHeight, 500)
end

function script.QueryTransport()
return link
end

function script.EndTransport(passengerID)
Move(link, y_axis, 0, 500) -- Once transport is complete, move the link piece back to where it was originally
end
</nowiki>

=== Ground transports ===

'''script.TransportPickup''' ( passengerID ) -> nil

Called when a passenger should be loaded into the transport. This should eventually call AttachUnit to actually attach the unit. Assuming the transport is in range of the next passenger, this will be called again for the next passenger 16 frames later, ''unless'' the script enters the BUSY state: then Spring will not move on to the next passenger until the script leaves the BUSY state.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Called when a passenger should be unloaded. This should eventually call DetachUnit to actually detach the unit, ''unless'' the used unload method is UnloadLandFlood, in which case Spring will actually detach the unit after the call.

'''script.EndTransport''' ( ) -> nil

Only called in UnloadLandFlood behavior, after the last unit has been unloaded.

=== Passenger ===

'''script.Falling''' ( ) -> nil

For a unit dropped from an UnloadDrop transport, this is called every frame to inform the script the unit is still falling. It may be used to show a parachute for example.

'''script.Landed''' ( ) -> nil

This is called one time after the unit reached the ground. May be used to hide a parachute for example.

== Internal ==

These call-ins are NOT available to Lua unit scripts. They are called by the engine however, but always 'intercepted' by the framework gadget. For completeness (or if you are poking at the gadget), they are listed here anyway.

'''script.MoveFinished''' ( piece, axis ) -> nil<br>
'''script.TurnFinished''' ( piece, axis ) -> nil

Called when a move or turn finished. The framework gadget uses this to resume the coroutines which are waiting for the particular move or turn to be finished.

'''script.Destroy''' ( ) -> nil

Called right before the unit's script is destroyed. This may happen if the unit is being destroyed, but also if the unit's script is being replaced by another script. The framework gadget uses this to stop all threads and remove the unit from some internal data structures.

[[Category:Animation]]
[[Category:Lua]]

Animation-LuaCallins

2022-11-17T08:29:54Z

Forboding angel: /* Example of what is needed for a Transport */

== Introduction ==

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular ''event'' happens.

For Lua unit scripts, a new call-in mechanism has been implemented, which is faster than the regular call-in mechanism used for widgets and gadgets.

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)
* heading/pitch: number (radians)

== Generic ==

'''script.Create''' ( ) -> nil

This is called just after the unit script has been created.

'''script.StartMoving''' ( ) -> nil<br>
'''script.StopMoving''' ( ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation. Since 95.0 they are only run when a unit transitions from zero to non-zero speed or vice versa, and no longer during in-place rotations.

'''script.ChangeHeading''' ( number deltaHeading ) -> nil

{{new|104.0}} Called when the unit changes heading.

'''script.StartSkidding''' ( ) -> nil<br>
'''script.StopSkidding''' ( ) -> nil

{{new|104.0}} Called when a (ground) unit reacts to an impulse. The start-skidding threshold ('sqSkidSpeedMult') is configurable via [[Lua_MoveCtrl#MoveType-Controlling|MoveCtrl.SetGroundMoveTypeData]]

'''script.Killed''' ( number recentDamage, number maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth ''(*100 so that it's in percent, no? at least that is how severity was expressed in Cob/bos, I think. Of course there's no reason to emulate that, just pointing it out for people "converting")''. Typically, this function would play a death animation for the unit, and finally return a corpse type.

'''script.WindChanged''' ( number heading, number strength ) -> nil

This is called for wind generators whenever the wind direction or strength changes.

'''script.ExtractionRateChanged''' ( number rate ) -> nil

Called for metal extractors each time their extraction rate (metal per second) changes.

'''script.setSFXoccupy''' ( number curTerrainType ) -> nil

Called when terrain type changes. Terrain type is calculated with the following rules (in this order):

* If unit is being transported -> curTerrainType = 0
* If ground height < -5 and unit is always upright -> curTerrainType = 2
* If ground height < -5 and unit is not always upright -> curTerrainType = 1
* If ground height < 0 and unit is always upright -> curTerrainType = 1
* Otherwise -> curTerrainType = 4

Where is curTerrainType = 3 ? :-)

Candidate to be changed to something saner later on.

'''script.MoveRate''' ( number curRate ) -> nil

Called only for certain types of aircraft (those which use ''CTAAirMoveType''.) The move rate is determined by the following rules (in this order):

* If the aircraft is landing or taking off -> curRate = 1
* Otherwise -> curRate = floor(curSpeed / maxSpeed * 3), clamped to be in the range [0, 2]

'''script.QueryLandingPads''' ( ) -> { number piece1, number piece2, ... }

Called one time for units with landing pads. Should return a table with pieces which should be used as landing pads. The number of pieces returned also determines the number of pads, so for Lua unit scripts there is no QueryLandingPadCount.

'''script.Activate''' ( ) -> nil<br>
'''script.Deactivate''' ( ) -> nil

Exact situation these are called depends a lot on the unit type. Factories are activated when they open their yard and deactivated when they close it. Aircraft are activated when they take off and deactivated when the land. Any unit that can be turned on or off is activated when it's turned on and deactivated when it's turned off. On ''script.SetUnitValue(COB.ACTIVATION, ...)'' one of these call-ins may be called too.

== Weapons ==

Weapon functions come in two variants.

* Separate function with numeric weapon number suffix. (e.g. ''script.AimWeapon<u>1</u>(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(<u>weaponNum</u>, heading, pitch)'')

Only the first variant is listed here, so whenever you see a function whose name ends with a numeric one ("1"), you should either replace it with the actual weapon number, or you can write a single combined function that takes a ''weaponNum'' argument. For each script, all functions should use the same variant. Either all using name suffix, or all using combined functions.

'''script.QueryWeapon1''' ( ) -> number piece<br>
'''script.AimFromWeapon1''' ( ) -> number piece<br>
'''script.AimWeapon1''' ( heading, pitch ) -> boolean<br>
'''script.AimShield1''' ( ) -> boolean

Weapon support. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired. AimWeapon is called repeatedly, at a rate determined by the {{xtaglink|Gamedev:WeaponDefs|fireTolerance}} tag.

'''script.FireWeapon1''' ( ) -> nil<br>
'''script.Shot1''' ( ) -> nil<br>
'''script.EndBurst1''' ( ) -> nil

If after aiming the unit actually fires it's weapon, FireWeapon is called once at the beginning of the salvo. Shot is called just before each projectile is fired. RockUnit (see below) is called just after all projectiles for that frame have been fired. At the end of the salvo, EndBurst is called.

Of these call-ins, FireWeapon is the more generic one and Shot and EndBurst are more specialized. FireWeapon is usually used to play a recoil animation or emit some smoke near the weapon's barrel using EmitSfx.

'''script.BlockShot1''' ( targetUnitID, boolean userTarget ) -> boolean

Allows you to block a weapon from shooting. TargetUnitID may be nil: in this case the unit has a ground-attack order.

'''script.TargetWeight1''' ( targetUnitID ) -> number

Allows you to tweak the priority of the target for this particular weapon. The target priority is multiplied by the return value of this function. Lower priority targets are targeted first, so return a value smaller than 1 to prioritize a target, or return a value larger than 1 to avoid a target.

The exact behavior of specific values shouldn't be relied upon.

'''script.RockUnit''' ( x, z ) -> nil

A bit like the weapon-specific FireWeapon function, although this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to â€œrockâ€ the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truly realistic rock direction it needs to be rotated according to the unit's current heading.

'''script.HitByWeapon''' ( x, z, weaponDefID, damage ) -> nil | number newDamage

This is called if a unit has been hit by a weapon. (x, z) is the direction from which the projectile came in unit space (the reverse direction of the impulse, to be exact.) It also gets the weaponDefID of the weapon which is dealing the damage, and the amount of damage. If HitByWeapon returns a number, this number will replace the damage value calculated by the engine.

Note: Pre Spring 95, this call-in runs just before the LuaRules UnitPreDamaged callin (see also [[LuaCallinReturn]]). If HitByWeapon overrides the damage, UnitPreDamaged will see the new damage value, and may override again the damage value. Starting Spring 95, it is run after UnitPreDamaged.

== Builders and factories ==

'''script.StartBuilding''' ( heading, pitch ) -> nil<br>
'''script.StartBuilding''' ( ) -> nil<br>
'''script.StopBuilding''' ( ) -> nil

These notify the script when a builder or factory starts or stops building.

The first variant (with heading and pitch arguments) is called for builders. For factories, the second variant is used. In this case the heading and pitch are not necessary, because the factory script specifies the build location itself using QueryBuildInfo.

BTW, don't forget to set INBUILDSTANCE to 1 to start building! For lua script, that is

<nowiki>
function script.StartBuilding(heading, pitch)
SetUnitValue(COB.INBUILDSTANCE, 1)
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
end
</nowiki>

'''script.QueryBuildInfo''' ( ) -> number piece

For factories only. Should return the piece to which the unit which is going to be build will be attached while it's being build.

'''script.QueryNanopiece''' ( ) -> number piece

Called each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

<span class="note">N.B. As of 92.0 the results are cached and the function is called 31 times only. Deprecated in favour of Spring.SetUnitNanoPieces, which disables this callin when used.</span>

=== Example of parts needed to create a Mobile Builder ===
<nowiki>
local nanoPieces = {[0] = nanopoint1}
local SIG_AIM = 2

-- Add this to create()
Spring.SetUnitNanoPieces(unitID, nanoPieces)
--

function RestoreAfterDelay()
SetSignalMask(SIG_AIM)
if building == false then
Sleep(2000)
end
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
building = false
StartThread(RestoreAfterDelay)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
end

function script.StartBuilding(heading, pitch)
Signal(SIG_AIM)
SetUnitValue(COB.INBUILDSTANCE, 1)
building = true
end

function script.QueryNanoPiece()
local nano = nanoPieces[nanoNum]
return nano
end
</nowiki>

== Transports ==

There are some different code paths inside Spring related to transports, each (unfortunately) also associated with a different set of unit script call-ins.

This table shows for the three different {{xtaglink|Gamedev:UnitDefs|transportUnloadMethod}} for both air transports and ground transports which callins are used and roughly when and how often they are called. Refer to the documentation below for a description of the call-ins.

The entire behavior around transports should be considered subject to change; it is obvious it is far from a perfect design currently.

{|border="1" style="border-spacing:0px;"
|+
!
!Load
!UnloadLand (0)
!UnloadDrop (1)
!UnloadLandFlood (2)
|-
|
|
|default unload
|fly over and drop unit
|land, then release all units at once
|-
|air
|BeginTransport (each)<br>QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first)<br>TransportDrop (each)<br>EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each)<br>EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil<br>
'''script.QueryTransport''' ( passengerID ) -> number piece

For an air transport, if any one unit is picked up, these two are called in succession and the passenger is attached to the piece returned by the second one.

'''script.StartUnload''' ( ) -> nil

Only called in UnloadLandFlood behavior. Signals the start of an unload cycle.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Only called in UnloadLandFlood behavior. Called when a passenger will be unloaded. Contrary to ground transports, Spring will detach the passenger after the call.

'''script.EndTransport''' ( ) -> nil

In UnloadLand and UnloadLandFlood behaviors, these are called one time after all units are unloaded. (The transport is empty.) For the UnloadDrop behavior, this is called for every unit that is unloaded.

==== Example of what is needed for an air Transport ====
<nowiki>
-- This assumes that the name of the piece where you want to attach the unit is "link"
function script.BeginTransport(passengerID)
local unitHeight = Spring.GetUnitHeight(passengerID) -- This moves the unit down so that it appears as though the top of it is attached to where the link piece was set (usually underneath the transport)
Move(link, y_axis, -unitHeight, 500)
end

function script.QueryTransport()
return link
end

function script.EndTransport(passengerID)
Move(link, y_axis, 0, 500) -- Once transport is complete, move the link piece back to where it was originally
end
</nowiki>

=== Ground transports ===

'''script.TransportPickup''' ( passengerID ) -> nil

Called when a passenger should be loaded into the transport. This should eventually call AttachUnit to actually attach the unit. Assuming the transport is in range of the next passenger, this will be called again for the next passenger 16 frames later, ''unless'' the script enters the BUSY state: then Spring will not move on to the next passenger until the script leaves the BUSY state.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Called when a passenger should be unloaded. This should eventually call DetachUnit to actually detach the unit, ''unless'' the used unload method is UnloadLandFlood, in which case Spring will actually detach the unit after the call.

'''script.EndTransport''' ( ) -> nil

Only called in UnloadLandFlood behavior, after the last unit has been unloaded.

=== Passenger ===

'''script.Falling''' ( ) -> nil

For a unit dropped from an UnloadDrop transport, this is called every frame to inform the script the unit is still falling. It may be used to show a parachute for example.

'''script.Landed''' ( ) -> nil

This is called one time after the unit reached the ground. May be used to hide a parachute for example.

== Internal ==

These call-ins are NOT available to Lua unit scripts. They are called by the engine however, but always 'intercepted' by the framework gadget. For completeness (or if you are poking at the gadget), they are listed here anyway.

'''script.MoveFinished''' ( piece, axis ) -> nil<br>
'''script.TurnFinished''' ( piece, axis ) -> nil

Called when a move or turn finished. The framework gadget uses this to resume the coroutines which are waiting for the particular move or turn to be finished.

'''script.Destroy''' ( ) -> nil

Called right before the unit's script is destroyed. This may happen if the unit is being destroyed, but also if the unit's script is being replaced by another script. The framework gadget uses this to stop all threads and remove the unit from some internal data structures.

[[Category:Animation]]
[[Category:Lua]]

Animation-LuaCallins

2022-11-17T08:29:08Z

Forboding angel: /* Example of what is needed for a Transport */

== Introduction ==

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular ''event'' happens.

For Lua unit scripts, a new call-in mechanism has been implemented, which is faster than the regular call-in mechanism used for widgets and gadgets.

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)
* heading/pitch: number (radians)

== Generic ==

'''script.Create''' ( ) -> nil

This is called just after the unit script has been created.

'''script.StartMoving''' ( ) -> nil<br>
'''script.StopMoving''' ( ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation. Since 95.0 they are only run when a unit transitions from zero to non-zero speed or vice versa, and no longer during in-place rotations.

'''script.ChangeHeading''' ( number deltaHeading ) -> nil

{{new|104.0}} Called when the unit changes heading.

'''script.StartSkidding''' ( ) -> nil<br>
'''script.StopSkidding''' ( ) -> nil

{{new|104.0}} Called when a (ground) unit reacts to an impulse. The start-skidding threshold ('sqSkidSpeedMult') is configurable via [[Lua_MoveCtrl#MoveType-Controlling|MoveCtrl.SetGroundMoveTypeData]]

'''script.Killed''' ( number recentDamage, number maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth ''(*100 so that it's in percent, no? at least that is how severity was expressed in Cob/bos, I think. Of course there's no reason to emulate that, just pointing it out for people "converting")''. Typically, this function would play a death animation for the unit, and finally return a corpse type.

'''script.WindChanged''' ( number heading, number strength ) -> nil

This is called for wind generators whenever the wind direction or strength changes.

'''script.ExtractionRateChanged''' ( number rate ) -> nil

Called for metal extractors each time their extraction rate (metal per second) changes.

'''script.setSFXoccupy''' ( number curTerrainType ) -> nil

Called when terrain type changes. Terrain type is calculated with the following rules (in this order):

* If unit is being transported -> curTerrainType = 0
* If ground height < -5 and unit is always upright -> curTerrainType = 2
* If ground height < -5 and unit is not always upright -> curTerrainType = 1
* If ground height < 0 and unit is always upright -> curTerrainType = 1
* Otherwise -> curTerrainType = 4

Where is curTerrainType = 3 ? :-)

Candidate to be changed to something saner later on.

'''script.MoveRate''' ( number curRate ) -> nil

Called only for certain types of aircraft (those which use ''CTAAirMoveType''.) The move rate is determined by the following rules (in this order):

* If the aircraft is landing or taking off -> curRate = 1
* Otherwise -> curRate = floor(curSpeed / maxSpeed * 3), clamped to be in the range [0, 2]

'''script.QueryLandingPads''' ( ) -> { number piece1, number piece2, ... }

Called one time for units with landing pads. Should return a table with pieces which should be used as landing pads. The number of pieces returned also determines the number of pads, so for Lua unit scripts there is no QueryLandingPadCount.

'''script.Activate''' ( ) -> nil<br>
'''script.Deactivate''' ( ) -> nil

Exact situation these are called depends a lot on the unit type. Factories are activated when they open their yard and deactivated when they close it. Aircraft are activated when they take off and deactivated when the land. Any unit that can be turned on or off is activated when it's turned on and deactivated when it's turned off. On ''script.SetUnitValue(COB.ACTIVATION, ...)'' one of these call-ins may be called too.

== Weapons ==

Weapon functions come in two variants.

* Separate function with numeric weapon number suffix. (e.g. ''script.AimWeapon<u>1</u>(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(<u>weaponNum</u>, heading, pitch)'')

Only the first variant is listed here, so whenever you see a function whose name ends with a numeric one ("1"), you should either replace it with the actual weapon number, or you can write a single combined function that takes a ''weaponNum'' argument. For each script, all functions should use the same variant. Either all using name suffix, or all using combined functions.

'''script.QueryWeapon1''' ( ) -> number piece<br>
'''script.AimFromWeapon1''' ( ) -> number piece<br>
'''script.AimWeapon1''' ( heading, pitch ) -> boolean<br>
'''script.AimShield1''' ( ) -> boolean

Weapon support. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired. AimWeapon is called repeatedly, at a rate determined by the {{xtaglink|Gamedev:WeaponDefs|fireTolerance}} tag.

'''script.FireWeapon1''' ( ) -> nil<br>
'''script.Shot1''' ( ) -> nil<br>
'''script.EndBurst1''' ( ) -> nil

If after aiming the unit actually fires it's weapon, FireWeapon is called once at the beginning of the salvo. Shot is called just before each projectile is fired. RockUnit (see below) is called just after all projectiles for that frame have been fired. At the end of the salvo, EndBurst is called.

Of these call-ins, FireWeapon is the more generic one and Shot and EndBurst are more specialized. FireWeapon is usually used to play a recoil animation or emit some smoke near the weapon's barrel using EmitSfx.

'''script.BlockShot1''' ( targetUnitID, boolean userTarget ) -> boolean

Allows you to block a weapon from shooting. TargetUnitID may be nil: in this case the unit has a ground-attack order.

'''script.TargetWeight1''' ( targetUnitID ) -> number

Allows you to tweak the priority of the target for this particular weapon. The target priority is multiplied by the return value of this function. Lower priority targets are targeted first, so return a value smaller than 1 to prioritize a target, or return a value larger than 1 to avoid a target.

The exact behavior of specific values shouldn't be relied upon.

'''script.RockUnit''' ( x, z ) -> nil

A bit like the weapon-specific FireWeapon function, although this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to â€œrockâ€ the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truly realistic rock direction it needs to be rotated according to the unit's current heading.

'''script.HitByWeapon''' ( x, z, weaponDefID, damage ) -> nil | number newDamage

This is called if a unit has been hit by a weapon. (x, z) is the direction from which the projectile came in unit space (the reverse direction of the impulse, to be exact.) It also gets the weaponDefID of the weapon which is dealing the damage, and the amount of damage. If HitByWeapon returns a number, this number will replace the damage value calculated by the engine.

Note: Pre Spring 95, this call-in runs just before the LuaRules UnitPreDamaged callin (see also [[LuaCallinReturn]]). If HitByWeapon overrides the damage, UnitPreDamaged will see the new damage value, and may override again the damage value. Starting Spring 95, it is run after UnitPreDamaged.

== Builders and factories ==

'''script.StartBuilding''' ( heading, pitch ) -> nil<br>
'''script.StartBuilding''' ( ) -> nil<br>
'''script.StopBuilding''' ( ) -> nil

These notify the script when a builder or factory starts or stops building.

The first variant (with heading and pitch arguments) is called for builders. For factories, the second variant is used. In this case the heading and pitch are not necessary, because the factory script specifies the build location itself using QueryBuildInfo.

BTW, don't forget to set INBUILDSTANCE to 1 to start building! For lua script, that is

<nowiki>
function script.StartBuilding(heading, pitch)
SetUnitValue(COB.INBUILDSTANCE, 1)
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
end
</nowiki>

'''script.QueryBuildInfo''' ( ) -> number piece

For factories only. Should return the piece to which the unit which is going to be build will be attached while it's being build.

'''script.QueryNanopiece''' ( ) -> number piece

Called each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

<span class="note">N.B. As of 92.0 the results are cached and the function is called 31 times only. Deprecated in favour of Spring.SetUnitNanoPieces, which disables this callin when used.</span>

=== Example of parts needed to create a Mobile Builder ===
<nowiki>
local nanoPieces = {[0] = nanopoint1}
local SIG_AIM = 2

-- Add this to create()
Spring.SetUnitNanoPieces(unitID, nanoPieces)
--

function RestoreAfterDelay()
SetSignalMask(SIG_AIM)
if building == false then
Sleep(2000)
end
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
building = false
StartThread(RestoreAfterDelay)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
end

function script.StartBuilding(heading, pitch)
Signal(SIG_AIM)
SetUnitValue(COB.INBUILDSTANCE, 1)
building = true
end

function script.QueryNanoPiece()
local nano = nanoPieces[nanoNum]
return nano
end
</nowiki>

== Transports ==

There are some different code paths inside Spring related to transports, each (unfortunately) also associated with a different set of unit script call-ins.

This table shows for the three different {{xtaglink|Gamedev:UnitDefs|transportUnloadMethod}} for both air transports and ground transports which callins are used and roughly when and how often they are called. Refer to the documentation below for a description of the call-ins.

The entire behavior around transports should be considered subject to change; it is obvious it is far from a perfect design currently.

{|border="1" style="border-spacing:0px;"
|+
!
!Load
!UnloadLand (0)
!UnloadDrop (1)
!UnloadLandFlood (2)
|-
|
|
|default unload
|fly over and drop unit
|land, then release all units at once
|-
|air
|BeginTransport (each)<br>QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first)<br>TransportDrop (each)<br>EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each)<br>EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil<br>
'''script.QueryTransport''' ( passengerID ) -> number piece

For an air transport, if any one unit is picked up, these two are called in succession and the passenger is attached to the piece returned by the second one.

'''script.StartUnload''' ( ) -> nil

Only called in UnloadLandFlood behavior. Signals the start of an unload cycle.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Only called in UnloadLandFlood behavior. Called when a passenger will be unloaded. Contrary to ground transports, Spring will detach the passenger after the call.

'''script.EndTransport''' ( ) -> nil

In UnloadLand and UnloadLandFlood behaviors, these are called one time after all units are unloaded. (The transport is empty.) For the UnloadDrop behavior, this is called for every unit that is unloaded.

==== Example of what is needed for a Transport ====
<nowiki>
-- This assumes that the name of the piece where you want to attach the unit is "link"
function script.BeginTransport(passengerID)
local unitHeight = Spring.GetUnitHeight(passengerID) -- This moves the unit down so that it appears as though the top of it is attached to where the link piece was set (usually underneath the transport)
Move(link, y_axis, -unitHeight, 500)
end

function script.QueryTransport()
return link
end

function script.EndTransport(passengerID)
Move(link, y_axis, 0, 500) -- Once transport is complete, move the link piece back to where it was originally
end
</nowiki>

=== Ground transports ===

'''script.TransportPickup''' ( passengerID ) -> nil

Called when a passenger should be loaded into the transport. This should eventually call AttachUnit to actually attach the unit. Assuming the transport is in range of the next passenger, this will be called again for the next passenger 16 frames later, ''unless'' the script enters the BUSY state: then Spring will not move on to the next passenger until the script leaves the BUSY state.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Called when a passenger should be unloaded. This should eventually call DetachUnit to actually detach the unit, ''unless'' the used unload method is UnloadLandFlood, in which case Spring will actually detach the unit after the call.

'''script.EndTransport''' ( ) -> nil

Only called in UnloadLandFlood behavior, after the last unit has been unloaded.

=== Passenger ===

'''script.Falling''' ( ) -> nil

For a unit dropped from an UnloadDrop transport, this is called every frame to inform the script the unit is still falling. It may be used to show a parachute for example.

'''script.Landed''' ( ) -> nil

This is called one time after the unit reached the ground. May be used to hide a parachute for example.

== Internal ==

These call-ins are NOT available to Lua unit scripts. They are called by the engine however, but always 'intercepted' by the framework gadget. For completeness (or if you are poking at the gadget), they are listed here anyway.

'''script.MoveFinished''' ( piece, axis ) -> nil<br>
'''script.TurnFinished''' ( piece, axis ) -> nil

Called when a move or turn finished. The framework gadget uses this to resume the coroutines which are waiting for the particular move or turn to be finished.

'''script.Destroy''' ( ) -> nil

Called right before the unit's script is destroyed. This may happen if the unit is being destroyed, but also if the unit's script is being replaced by another script. The framework gadget uses this to stop all threads and remove the unit from some internal data structures.

[[Category:Animation]]
[[Category:Lua]]

Animation-LuaCallins

2022-11-17T08:28:03Z

Forboding angel: /* Example of what is needed for a Transport */

== Introduction ==

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular ''event'' happens.

For Lua unit scripts, a new call-in mechanism has been implemented, which is faster than the regular call-in mechanism used for widgets and gadgets.

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)
* heading/pitch: number (radians)

== Generic ==

'''script.Create''' ( ) -> nil

This is called just after the unit script has been created.

'''script.StartMoving''' ( ) -> nil<br>
'''script.StopMoving''' ( ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation. Since 95.0 they are only run when a unit transitions from zero to non-zero speed or vice versa, and no longer during in-place rotations.

'''script.ChangeHeading''' ( number deltaHeading ) -> nil

{{new|104.0}} Called when the unit changes heading.

'''script.StartSkidding''' ( ) -> nil<br>
'''script.StopSkidding''' ( ) -> nil

{{new|104.0}} Called when a (ground) unit reacts to an impulse. The start-skidding threshold ('sqSkidSpeedMult') is configurable via [[Lua_MoveCtrl#MoveType-Controlling|MoveCtrl.SetGroundMoveTypeData]]

'''script.Killed''' ( number recentDamage, number maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth ''(*100 so that it's in percent, no? at least that is how severity was expressed in Cob/bos, I think. Of course there's no reason to emulate that, just pointing it out for people "converting")''. Typically, this function would play a death animation for the unit, and finally return a corpse type.

'''script.WindChanged''' ( number heading, number strength ) -> nil

This is called for wind generators whenever the wind direction or strength changes.

'''script.ExtractionRateChanged''' ( number rate ) -> nil

Called for metal extractors each time their extraction rate (metal per second) changes.

'''script.setSFXoccupy''' ( number curTerrainType ) -> nil

Called when terrain type changes. Terrain type is calculated with the following rules (in this order):

* If unit is being transported -> curTerrainType = 0
* If ground height < -5 and unit is always upright -> curTerrainType = 2
* If ground height < -5 and unit is not always upright -> curTerrainType = 1
* If ground height < 0 and unit is always upright -> curTerrainType = 1
* Otherwise -> curTerrainType = 4

Where is curTerrainType = 3 ? :-)

Candidate to be changed to something saner later on.

'''script.MoveRate''' ( number curRate ) -> nil

Called only for certain types of aircraft (those which use ''CTAAirMoveType''.) The move rate is determined by the following rules (in this order):

* If the aircraft is landing or taking off -> curRate = 1
* Otherwise -> curRate = floor(curSpeed / maxSpeed * 3), clamped to be in the range [0, 2]

'''script.QueryLandingPads''' ( ) -> { number piece1, number piece2, ... }

Called one time for units with landing pads. Should return a table with pieces which should be used as landing pads. The number of pieces returned also determines the number of pads, so for Lua unit scripts there is no QueryLandingPadCount.

'''script.Activate''' ( ) -> nil<br>
'''script.Deactivate''' ( ) -> nil

Exact situation these are called depends a lot on the unit type. Factories are activated when they open their yard and deactivated when they close it. Aircraft are activated when they take off and deactivated when the land. Any unit that can be turned on or off is activated when it's turned on and deactivated when it's turned off. On ''script.SetUnitValue(COB.ACTIVATION, ...)'' one of these call-ins may be called too.

== Weapons ==

Weapon functions come in two variants.

* Separate function with numeric weapon number suffix. (e.g. ''script.AimWeapon<u>1</u>(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(<u>weaponNum</u>, heading, pitch)'')

Only the first variant is listed here, so whenever you see a function whose name ends with a numeric one ("1"), you should either replace it with the actual weapon number, or you can write a single combined function that takes a ''weaponNum'' argument. For each script, all functions should use the same variant. Either all using name suffix, or all using combined functions.

'''script.QueryWeapon1''' ( ) -> number piece<br>
'''script.AimFromWeapon1''' ( ) -> number piece<br>
'''script.AimWeapon1''' ( heading, pitch ) -> boolean<br>
'''script.AimShield1''' ( ) -> boolean

Weapon support. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired. AimWeapon is called repeatedly, at a rate determined by the {{xtaglink|Gamedev:WeaponDefs|fireTolerance}} tag.

'''script.FireWeapon1''' ( ) -> nil<br>
'''script.Shot1''' ( ) -> nil<br>
'''script.EndBurst1''' ( ) -> nil

If after aiming the unit actually fires it's weapon, FireWeapon is called once at the beginning of the salvo. Shot is called just before each projectile is fired. RockUnit (see below) is called just after all projectiles for that frame have been fired. At the end of the salvo, EndBurst is called.

Of these call-ins, FireWeapon is the more generic one and Shot and EndBurst are more specialized. FireWeapon is usually used to play a recoil animation or emit some smoke near the weapon's barrel using EmitSfx.

'''script.BlockShot1''' ( targetUnitID, boolean userTarget ) -> boolean

Allows you to block a weapon from shooting. TargetUnitID may be nil: in this case the unit has a ground-attack order.

'''script.TargetWeight1''' ( targetUnitID ) -> number

Allows you to tweak the priority of the target for this particular weapon. The target priority is multiplied by the return value of this function. Lower priority targets are targeted first, so return a value smaller than 1 to prioritize a target, or return a value larger than 1 to avoid a target.

The exact behavior of specific values shouldn't be relied upon.

'''script.RockUnit''' ( x, z ) -> nil

A bit like the weapon-specific FireWeapon function, although this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to â€œrockâ€ the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truly realistic rock direction it needs to be rotated according to the unit's current heading.

'''script.HitByWeapon''' ( x, z, weaponDefID, damage ) -> nil | number newDamage

This is called if a unit has been hit by a weapon. (x, z) is the direction from which the projectile came in unit space (the reverse direction of the impulse, to be exact.) It also gets the weaponDefID of the weapon which is dealing the damage, and the amount of damage. If HitByWeapon returns a number, this number will replace the damage value calculated by the engine.

Note: Pre Spring 95, this call-in runs just before the LuaRules UnitPreDamaged callin (see also [[LuaCallinReturn]]). If HitByWeapon overrides the damage, UnitPreDamaged will see the new damage value, and may override again the damage value. Starting Spring 95, it is run after UnitPreDamaged.

== Builders and factories ==

'''script.StartBuilding''' ( heading, pitch ) -> nil<br>
'''script.StartBuilding''' ( ) -> nil<br>
'''script.StopBuilding''' ( ) -> nil

These notify the script when a builder or factory starts or stops building.

The first variant (with heading and pitch arguments) is called for builders. For factories, the second variant is used. In this case the heading and pitch are not necessary, because the factory script specifies the build location itself using QueryBuildInfo.

BTW, don't forget to set INBUILDSTANCE to 1 to start building! For lua script, that is

<nowiki>
function script.StartBuilding(heading, pitch)
SetUnitValue(COB.INBUILDSTANCE, 1)
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
end
</nowiki>

'''script.QueryBuildInfo''' ( ) -> number piece

For factories only. Should return the piece to which the unit which is going to be build will be attached while it's being build.

'''script.QueryNanopiece''' ( ) -> number piece

Called each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

<span class="note">N.B. As of 92.0 the results are cached and the function is called 31 times only. Deprecated in favour of Spring.SetUnitNanoPieces, which disables this callin when used.</span>

=== Example of parts needed to create a Mobile Builder ===
<nowiki>
local nanoPieces = {[0] = nanopoint1}
local SIG_AIM = 2

-- Add this to create()
Spring.SetUnitNanoPieces(unitID, nanoPieces)
--

function RestoreAfterDelay()
SetSignalMask(SIG_AIM)
if building == false then
Sleep(2000)
end
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
building = false
StartThread(RestoreAfterDelay)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
end

function script.StartBuilding(heading, pitch)
Signal(SIG_AIM)
SetUnitValue(COB.INBUILDSTANCE, 1)
building = true
end

function script.QueryNanoPiece()
local nano = nanoPieces[nanoNum]
return nano
end
</nowiki>

== Transports ==

There are some different code paths inside Spring related to transports, each (unfortunately) also associated with a different set of unit script call-ins.

This table shows for the three different {{xtaglink|Gamedev:UnitDefs|transportUnloadMethod}} for both air transports and ground transports which callins are used and roughly when and how often they are called. Refer to the documentation below for a description of the call-ins.

The entire behavior around transports should be considered subject to change; it is obvious it is far from a perfect design currently.

{|border="1" style="border-spacing:0px;"
|+
!
!Load
!UnloadLand (0)
!UnloadDrop (1)
!UnloadLandFlood (2)
|-
|
|
|default unload
|fly over and drop unit
|land, then release all units at once
|-
|air
|BeginTransport (each)<br>QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first)<br>TransportDrop (each)<br>EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each)<br>EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil<br>
'''script.QueryTransport''' ( passengerID ) -> number piece

For an air transport, if any one unit is picked up, these two are called in succession and the passenger is attached to the piece returned by the second one.

'''script.StartUnload''' ( ) -> nil

Only called in UnloadLandFlood behavior. Signals the start of an unload cycle.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Only called in UnloadLandFlood behavior. Called when a passenger will be unloaded. Contrary to ground transports, Spring will detach the passenger after the call.

'''script.EndTransport''' ( ) -> nil

In UnloadLand and UnloadLandFlood behaviors, these are called one time after all units are unloaded. (The transport is empty.) For the UnloadDrop behavior, this is called for every unit that is unloaded.

==== Example of what is needed for a Transport ====
<nowiki>
function script.BeginTransport(passengerID)
local unitHeight = Spring.GetUnitHeight(passengerID) -- This moves the unit down so that it appears as though the top of it is attached to where the link piece was set (usually underneath the transport)
Move(link, y_axis, -unitHeight, 500)
end

function script.QueryTransport()
return link
end

function script.EndTransport(passengerID)
Move(link, y_axis, 0, 500) -- Once transport is complete, move the link piece back to where it was originally
end
</nowiki>

=== Ground transports ===

'''script.TransportPickup''' ( passengerID ) -> nil

Called when a passenger should be loaded into the transport. This should eventually call AttachUnit to actually attach the unit. Assuming the transport is in range of the next passenger, this will be called again for the next passenger 16 frames later, ''unless'' the script enters the BUSY state: then Spring will not move on to the next passenger until the script leaves the BUSY state.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Called when a passenger should be unloaded. This should eventually call DetachUnit to actually detach the unit, ''unless'' the used unload method is UnloadLandFlood, in which case Spring will actually detach the unit after the call.

'''script.EndTransport''' ( ) -> nil

Only called in UnloadLandFlood behavior, after the last unit has been unloaded.

=== Passenger ===

'''script.Falling''' ( ) -> nil

For a unit dropped from an UnloadDrop transport, this is called every frame to inform the script the unit is still falling. It may be used to show a parachute for example.

'''script.Landed''' ( ) -> nil

This is called one time after the unit reached the ground. May be used to hide a parachute for example.

== Internal ==

These call-ins are NOT available to Lua unit scripts. They are called by the engine however, but always 'intercepted' by the framework gadget. For completeness (or if you are poking at the gadget), they are listed here anyway.

'''script.MoveFinished''' ( piece, axis ) -> nil<br>
'''script.TurnFinished''' ( piece, axis ) -> nil

Called when a move or turn finished. The framework gadget uses this to resume the coroutines which are waiting for the particular move or turn to be finished.

'''script.Destroy''' ( ) -> nil

Called right before the unit's script is destroyed. This may happen if the unit is being destroyed, but also if the unit's script is being replaced by another script. The framework gadget uses this to stop all threads and remove the unit from some internal data structures.

[[Category:Animation]]
[[Category:Lua]]

Animation-LuaCallins

2022-11-17T08:27:45Z

Forboding angel: /* Air transports */

== Introduction ==

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular ''event'' happens.

For Lua unit scripts, a new call-in mechanism has been implemented, which is faster than the regular call-in mechanism used for widgets and gadgets.

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)
* heading/pitch: number (radians)

== Generic ==

'''script.Create''' ( ) -> nil

This is called just after the unit script has been created.

'''script.StartMoving''' ( ) -> nil<br>
'''script.StopMoving''' ( ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation. Since 95.0 they are only run when a unit transitions from zero to non-zero speed or vice versa, and no longer during in-place rotations.

'''script.ChangeHeading''' ( number deltaHeading ) -> nil

{{new|104.0}} Called when the unit changes heading.

'''script.StartSkidding''' ( ) -> nil<br>
'''script.StopSkidding''' ( ) -> nil

{{new|104.0}} Called when a (ground) unit reacts to an impulse. The start-skidding threshold ('sqSkidSpeedMult') is configurable via [[Lua_MoveCtrl#MoveType-Controlling|MoveCtrl.SetGroundMoveTypeData]]

'''script.Killed''' ( number recentDamage, number maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth ''(*100 so that it's in percent, no? at least that is how severity was expressed in Cob/bos, I think. Of course there's no reason to emulate that, just pointing it out for people "converting")''. Typically, this function would play a death animation for the unit, and finally return a corpse type.

'''script.WindChanged''' ( number heading, number strength ) -> nil

This is called for wind generators whenever the wind direction or strength changes.

'''script.ExtractionRateChanged''' ( number rate ) -> nil

Called for metal extractors each time their extraction rate (metal per second) changes.

'''script.setSFXoccupy''' ( number curTerrainType ) -> nil

Called when terrain type changes. Terrain type is calculated with the following rules (in this order):

* If unit is being transported -> curTerrainType = 0
* If ground height < -5 and unit is always upright -> curTerrainType = 2
* If ground height < -5 and unit is not always upright -> curTerrainType = 1
* If ground height < 0 and unit is always upright -> curTerrainType = 1
* Otherwise -> curTerrainType = 4

Where is curTerrainType = 3 ? :-)

Candidate to be changed to something saner later on.

'''script.MoveRate''' ( number curRate ) -> nil

Called only for certain types of aircraft (those which use ''CTAAirMoveType''.) The move rate is determined by the following rules (in this order):

* If the aircraft is landing or taking off -> curRate = 1
* Otherwise -> curRate = floor(curSpeed / maxSpeed * 3), clamped to be in the range [0, 2]

'''script.QueryLandingPads''' ( ) -> { number piece1, number piece2, ... }

Called one time for units with landing pads. Should return a table with pieces which should be used as landing pads. The number of pieces returned also determines the number of pads, so for Lua unit scripts there is no QueryLandingPadCount.

'''script.Activate''' ( ) -> nil<br>
'''script.Deactivate''' ( ) -> nil

Exact situation these are called depends a lot on the unit type. Factories are activated when they open their yard and deactivated when they close it. Aircraft are activated when they take off and deactivated when the land. Any unit that can be turned on or off is activated when it's turned on and deactivated when it's turned off. On ''script.SetUnitValue(COB.ACTIVATION, ...)'' one of these call-ins may be called too.

== Weapons ==

Weapon functions come in two variants.

* Separate function with numeric weapon number suffix. (e.g. ''script.AimWeapon<u>1</u>(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(<u>weaponNum</u>, heading, pitch)'')

Only the first variant is listed here, so whenever you see a function whose name ends with a numeric one ("1"), you should either replace it with the actual weapon number, or you can write a single combined function that takes a ''weaponNum'' argument. For each script, all functions should use the same variant. Either all using name suffix, or all using combined functions.

'''script.QueryWeapon1''' ( ) -> number piece<br>
'''script.AimFromWeapon1''' ( ) -> number piece<br>
'''script.AimWeapon1''' ( heading, pitch ) -> boolean<br>
'''script.AimShield1''' ( ) -> boolean

Weapon support. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired. AimWeapon is called repeatedly, at a rate determined by the {{xtaglink|Gamedev:WeaponDefs|fireTolerance}} tag.

'''script.FireWeapon1''' ( ) -> nil<br>
'''script.Shot1''' ( ) -> nil<br>
'''script.EndBurst1''' ( ) -> nil

If after aiming the unit actually fires it's weapon, FireWeapon is called once at the beginning of the salvo. Shot is called just before each projectile is fired. RockUnit (see below) is called just after all projectiles for that frame have been fired. At the end of the salvo, EndBurst is called.

Of these call-ins, FireWeapon is the more generic one and Shot and EndBurst are more specialized. FireWeapon is usually used to play a recoil animation or emit some smoke near the weapon's barrel using EmitSfx.

'''script.BlockShot1''' ( targetUnitID, boolean userTarget ) -> boolean

Allows you to block a weapon from shooting. TargetUnitID may be nil: in this case the unit has a ground-attack order.

'''script.TargetWeight1''' ( targetUnitID ) -> number

Allows you to tweak the priority of the target for this particular weapon. The target priority is multiplied by the return value of this function. Lower priority targets are targeted first, so return a value smaller than 1 to prioritize a target, or return a value larger than 1 to avoid a target.

The exact behavior of specific values shouldn't be relied upon.

'''script.RockUnit''' ( x, z ) -> nil

A bit like the weapon-specific FireWeapon function, although this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to â€œrockâ€ the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truly realistic rock direction it needs to be rotated according to the unit's current heading.

'''script.HitByWeapon''' ( x, z, weaponDefID, damage ) -> nil | number newDamage

This is called if a unit has been hit by a weapon. (x, z) is the direction from which the projectile came in unit space (the reverse direction of the impulse, to be exact.) It also gets the weaponDefID of the weapon which is dealing the damage, and the amount of damage. If HitByWeapon returns a number, this number will replace the damage value calculated by the engine.

Note: Pre Spring 95, this call-in runs just before the LuaRules UnitPreDamaged callin (see also [[LuaCallinReturn]]). If HitByWeapon overrides the damage, UnitPreDamaged will see the new damage value, and may override again the damage value. Starting Spring 95, it is run after UnitPreDamaged.

== Builders and factories ==

'''script.StartBuilding''' ( heading, pitch ) -> nil<br>
'''script.StartBuilding''' ( ) -> nil<br>
'''script.StopBuilding''' ( ) -> nil

These notify the script when a builder or factory starts or stops building.

The first variant (with heading and pitch arguments) is called for builders. For factories, the second variant is used. In this case the heading and pitch are not necessary, because the factory script specifies the build location itself using QueryBuildInfo.

BTW, don't forget to set INBUILDSTANCE to 1 to start building! For lua script, that is

<nowiki>
function script.StartBuilding(heading, pitch)
SetUnitValue(COB.INBUILDSTANCE, 1)
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
end
</nowiki>

'''script.QueryBuildInfo''' ( ) -> number piece

For factories only. Should return the piece to which the unit which is going to be build will be attached while it's being build.

'''script.QueryNanopiece''' ( ) -> number piece

Called each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

<span class="note">N.B. As of 92.0 the results are cached and the function is called 31 times only. Deprecated in favour of Spring.SetUnitNanoPieces, which disables this callin when used.</span>

=== Example of parts needed to create a Mobile Builder ===
<nowiki>
local nanoPieces = {[0] = nanopoint1}
local SIG_AIM = 2

-- Add this to create()
Spring.SetUnitNanoPieces(unitID, nanoPieces)
--

function RestoreAfterDelay()
SetSignalMask(SIG_AIM)
if building == false then
Sleep(2000)
end
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
building = false
StartThread(RestoreAfterDelay)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
end

function script.StartBuilding(heading, pitch)
Signal(SIG_AIM)
SetUnitValue(COB.INBUILDSTANCE, 1)
building = true
end

function script.QueryNanoPiece()
local nano = nanoPieces[nanoNum]
return nano
end
</nowiki>

== Transports ==

There are some different code paths inside Spring related to transports, each (unfortunately) also associated with a different set of unit script call-ins.

This table shows for the three different {{xtaglink|Gamedev:UnitDefs|transportUnloadMethod}} for both air transports and ground transports which callins are used and roughly when and how often they are called. Refer to the documentation below for a description of the call-ins.

The entire behavior around transports should be considered subject to change; it is obvious it is far from a perfect design currently.

{|border="1" style="border-spacing:0px;"
|+
!
!Load
!UnloadLand (0)
!UnloadDrop (1)
!UnloadLandFlood (2)
|-
|
|
|default unload
|fly over and drop unit
|land, then release all units at once
|-
|air
|BeginTransport (each)<br>QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first)<br>TransportDrop (each)<br>EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each)<br>EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil<br>
'''script.QueryTransport''' ( passengerID ) -> number piece

For an air transport, if any one unit is picked up, these two are called in succession and the passenger is attached to the piece returned by the second one.

'''script.StartUnload''' ( ) -> nil

Only called in UnloadLandFlood behavior. Signals the start of an unload cycle.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Only called in UnloadLandFlood behavior. Called when a passenger will be unloaded. Contrary to ground transports, Spring will detach the passenger after the call.

'''script.EndTransport''' ( ) -> nil

In UnloadLand and UnloadLandFlood behaviors, these are called one time after all units are unloaded. (The transport is empty.) For the UnloadDrop behavior, this is called for every unit that is unloaded.

==== Example of what is needed for a Transport ====
<nowiki>
function script.BeginTransport(passengerID)
local unitHeight = Spring.GetUnitHeight(passengerID) -- This moves the unit down so that it appears as though the top of it is attached to where the link piece was set (usually underneath the transport)
Move(link, y_axis, -unitHeight, 500)
end

function script.QueryTransport()
return link
end

function script.EndTransport(passengerID)
Move(link, y_axis, 0, 500) -- Once transport is complete, move the link piece back to where it was originally
end
</nowiki>

=== Ground transports ===

'''script.TransportPickup''' ( passengerID ) -> nil

Called when a passenger should be loaded into the transport. This should eventually call AttachUnit to actually attach the unit. Assuming the transport is in range of the next passenger, this will be called again for the next passenger 16 frames later, ''unless'' the script enters the BUSY state: then Spring will not move on to the next passenger until the script leaves the BUSY state.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Called when a passenger should be unloaded. This should eventually call DetachUnit to actually detach the unit, ''unless'' the used unload method is UnloadLandFlood, in which case Spring will actually detach the unit after the call.

'''script.EndTransport''' ( ) -> nil

Only called in UnloadLandFlood behavior, after the last unit has been unloaded.

=== Passenger ===

'''script.Falling''' ( ) -> nil

For a unit dropped from an UnloadDrop transport, this is called every frame to inform the script the unit is still falling. It may be used to show a parachute for example.

'''script.Landed''' ( ) -> nil

This is called one time after the unit reached the ground. May be used to hide a parachute for example.

== Internal ==

These call-ins are NOT available to Lua unit scripts. They are called by the engine however, but always 'intercepted' by the framework gadget. For completeness (or if you are poking at the gadget), they are listed here anyway.

'''script.MoveFinished''' ( piece, axis ) -> nil<br>
'''script.TurnFinished''' ( piece, axis ) -> nil

Called when a move or turn finished. The framework gadget uses this to resume the coroutines which are waiting for the particular move or turn to be finished.

'''script.Destroy''' ( ) -> nil

Called right before the unit's script is destroyed. This may happen if the unit is being destroyed, but also if the unit's script is being replaced by another script. The framework gadget uses this to stop all threads and remove the unit from some internal data structures.

[[Category:Animation]]
[[Category:Lua]]

Animation-LuaCallins

2022-11-17T08:24:19Z

Forboding angel: /* Builders and factories */

== Introduction ==

Call-ins are calls from the engine, into the unit script. In other words, these functions are called, if they are defined, when a particular ''event'' happens.

For Lua unit scripts, a new call-in mechanism has been implemented, which is faster than the regular call-in mechanism used for widgets and gadgets.

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)
* heading/pitch: number (radians)

== Generic ==

'''script.Create''' ( ) -> nil

This is called just after the unit script has been created.

'''script.StartMoving''' ( ) -> nil<br>
'''script.StopMoving''' ( ) -> nil

These are called whenever the unit starts or stops moving. Typical use for them is to trigger wheels to start spinning, animate treads, or start/stop a walking animation. Since 95.0 they are only run when a unit transitions from zero to non-zero speed or vice versa, and no longer during in-place rotations.

'''script.ChangeHeading''' ( number deltaHeading ) -> nil

{{new|104.0}} Called when the unit changes heading.

'''script.StartSkidding''' ( ) -> nil<br>
'''script.StopSkidding''' ( ) -> nil

{{new|104.0}} Called when a (ground) unit reacts to an impulse. The start-skidding threshold ('sqSkidSpeedMult') is configurable via [[Lua_MoveCtrl#MoveType-Controlling|MoveCtrl.SetGroundMoveTypeData]]

'''script.Killed''' ( number recentDamage, number maxHealth ) -> number corpseType

This is called when the unit is killed. The severity of the kill may be calculated as severity=recentDamage/maxHealth ''(*100 so that it's in percent, no? at least that is how severity was expressed in Cob/bos, I think. Of course there's no reason to emulate that, just pointing it out for people "converting")''. Typically, this function would play a death animation for the unit, and finally return a corpse type.

'''script.WindChanged''' ( number heading, number strength ) -> nil

This is called for wind generators whenever the wind direction or strength changes.

'''script.ExtractionRateChanged''' ( number rate ) -> nil

Called for metal extractors each time their extraction rate (metal per second) changes.

'''script.setSFXoccupy''' ( number curTerrainType ) -> nil

Called when terrain type changes. Terrain type is calculated with the following rules (in this order):

* If unit is being transported -> curTerrainType = 0
* If ground height < -5 and unit is always upright -> curTerrainType = 2
* If ground height < -5 and unit is not always upright -> curTerrainType = 1
* If ground height < 0 and unit is always upright -> curTerrainType = 1
* Otherwise -> curTerrainType = 4

Where is curTerrainType = 3 ? :-)

Candidate to be changed to something saner later on.

'''script.MoveRate''' ( number curRate ) -> nil

Called only for certain types of aircraft (those which use ''CTAAirMoveType''.) The move rate is determined by the following rules (in this order):

* If the aircraft is landing or taking off -> curRate = 1
* Otherwise -> curRate = floor(curSpeed / maxSpeed * 3), clamped to be in the range [0, 2]

'''script.QueryLandingPads''' ( ) -> { number piece1, number piece2, ... }

Called one time for units with landing pads. Should return a table with pieces which should be used as landing pads. The number of pieces returned also determines the number of pads, so for Lua unit scripts there is no QueryLandingPadCount.

'''script.Activate''' ( ) -> nil<br>
'''script.Deactivate''' ( ) -> nil

Exact situation these are called depends a lot on the unit type. Factories are activated when they open their yard and deactivated when they close it. Aircraft are activated when they take off and deactivated when the land. Any unit that can be turned on or off is activated when it's turned on and deactivated when it's turned off. On ''script.SetUnitValue(COB.ACTIVATION, ...)'' one of these call-ins may be called too.

== Weapons ==

Weapon functions come in two variants.

* Separate function with numeric weapon number suffix. (e.g. ''script.AimWeapon<u>1</u>(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(<u>weaponNum</u>, heading, pitch)'')

Only the first variant is listed here, so whenever you see a function whose name ends with a numeric one ("1"), you should either replace it with the actual weapon number, or you can write a single combined function that takes a ''weaponNum'' argument. For each script, all functions should use the same variant. Either all using name suffix, or all using combined functions.

'''script.QueryWeapon1''' ( ) -> number piece<br>
'''script.AimFromWeapon1''' ( ) -> number piece<br>
'''script.AimWeapon1''' ( heading, pitch ) -> boolean<br>
'''script.AimShield1''' ( ) -> boolean

Weapon support. The return value of QueryWeapon and AimFromWeapon determines the pieces which will be used for aiming: typically e.g. the barrel for QueryWeapon and the turret for AimFromWeapon. AimWeapon is then called to allow the script to turn the weapons in the target direction, which is passed as the heading and pitch argument (in radians). Only if AimWeapon returns true, the weapon is actually fired. AimWeapon is called repeatedly, at a rate determined by the {{xtaglink|Gamedev:WeaponDefs|fireTolerance}} tag.

'''script.FireWeapon1''' ( ) -> nil<br>
'''script.Shot1''' ( ) -> nil<br>
'''script.EndBurst1''' ( ) -> nil

If after aiming the unit actually fires it's weapon, FireWeapon is called once at the beginning of the salvo. Shot is called just before each projectile is fired. RockUnit (see below) is called just after all projectiles for that frame have been fired. At the end of the salvo, EndBurst is called.

Of these call-ins, FireWeapon is the more generic one and Shot and EndBurst are more specialized. FireWeapon is usually used to play a recoil animation or emit some smoke near the weapon's barrel using EmitSfx.

'''script.BlockShot1''' ( targetUnitID, boolean userTarget ) -> boolean

Allows you to block a weapon from shooting. TargetUnitID may be nil: in this case the unit has a ground-attack order.

'''script.TargetWeight1''' ( targetUnitID ) -> number

Allows you to tweak the priority of the target for this particular weapon. The target priority is multiplied by the return value of this function. Lower priority targets are targeted first, so return a value smaller than 1 to prioritize a target, or return a value larger than 1 to avoid a target.

The exact behavior of specific values shouldn't be relied upon.

'''script.RockUnit''' ( x, z ) -> nil

A bit like the weapon-specific FireWeapon function, although this is called after any weapon fires. As argument it gets a two dimensional vector in the direction the unit just fired. This may be used to â€œrockâ€ the unit as a whole a bit as part of the firing animation. Note though that this vector is in world space, so for a truly realistic rock direction it needs to be rotated according to the unit's current heading.

'''script.HitByWeapon''' ( x, z, weaponDefID, damage ) -> nil | number newDamage

This is called if a unit has been hit by a weapon. (x, z) is the direction from which the projectile came in unit space (the reverse direction of the impulse, to be exact.) It also gets the weaponDefID of the weapon which is dealing the damage, and the amount of damage. If HitByWeapon returns a number, this number will replace the damage value calculated by the engine.

Note: Pre Spring 95, this call-in runs just before the LuaRules UnitPreDamaged callin (see also [[LuaCallinReturn]]). If HitByWeapon overrides the damage, UnitPreDamaged will see the new damage value, and may override again the damage value. Starting Spring 95, it is run after UnitPreDamaged.

== Builders and factories ==

'''script.StartBuilding''' ( heading, pitch ) -> nil<br>
'''script.StartBuilding''' ( ) -> nil<br>
'''script.StopBuilding''' ( ) -> nil

These notify the script when a builder or factory starts or stops building.

The first variant (with heading and pitch arguments) is called for builders. For factories, the second variant is used. In this case the heading and pitch are not necessary, because the factory script specifies the build location itself using QueryBuildInfo.

BTW, don't forget to set INBUILDSTANCE to 1 to start building! For lua script, that is

<nowiki>
function script.StartBuilding(heading, pitch)
SetUnitValue(COB.INBUILDSTANCE, 1)
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
end
</nowiki>

'''script.QueryBuildInfo''' ( ) -> number piece

For factories only. Should return the piece to which the unit which is going to be build will be attached while it's being build.

'''script.QueryNanopiece''' ( ) -> number piece

Called each time a nano particle is to be created. Should return the piece at which the particle will be spawned. This may be used to iterate through a few pieces, to simulate the factory/builder having multiple nanolathes.

<span class="note">N.B. As of 92.0 the results are cached and the function is called 31 times only. Deprecated in favour of Spring.SetUnitNanoPieces, which disables this callin when used.</span>

=== Example of parts needed to create a Mobile Builder ===
<nowiki>
local nanoPieces = {[0] = nanopoint1}
local SIG_AIM = 2

-- Add this to create()
Spring.SetUnitNanoPieces(unitID, nanoPieces)
--

function RestoreAfterDelay()
SetSignalMask(SIG_AIM)
if building == false then
Sleep(2000)
end
end

function script.StopBuilding()
SetUnitValue(COB.INBUILDSTANCE, 0)
building = false
StartThread(RestoreAfterDelay)
Signal(SIG_AIM)
SetSignalMask(SIG_AIM)
end

function script.StartBuilding(heading, pitch)
Signal(SIG_AIM)
SetUnitValue(COB.INBUILDSTANCE, 1)
building = true
end

function script.QueryNanoPiece()
local nano = nanoPieces[nanoNum]
return nano
end
</nowiki>

== Transports ==

There are some different code paths inside Spring related to transports, each (unfortunately) also associated with a different set of unit script call-ins.

This table shows for the three different {{xtaglink|Gamedev:UnitDefs|transportUnloadMethod}} for both air transports and ground transports which callins are used and roughly when and how often they are called. Refer to the documentation below for a description of the call-ins.

The entire behavior around transports should be considered subject to change; it is obvious it is far from a perfect design currently.

{|border="1" style="border-spacing:0px;"
|+
!
!Load
!UnloadLand (0)
!UnloadDrop (1)
!UnloadLandFlood (2)
|-
|
|
|default unload
|fly over and drop unit
|land, then release all units at once
|-
|air
|BeginTransport (each)<br>QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first)<br>TransportDrop (each)<br>EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each)<br>EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil<br>
'''script.QueryTransport''' ( passengerID ) -> number piece

For an air transport, if any one unit is picked up, these two are called in succession and the passenger is attached to the piece returned by the second one.

'''script.StartUnload''' ( ) -> nil

Only called in UnloadLandFlood behavior. Signals the start of an unload cycle.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Only called in UnloadLandFlood behavior. Called when a passenger will be unloaded. Contrary to ground transports, Spring will detach the passenger after the call.

'''script.EndTransport''' ( ) -> nil

In UnloadLand and UnloadLandFlood behaviors, these are called one time after all units are unloaded. (The transport is empty.) For the UnloadDrop behavior, this is called for every unit that is unloaded.

=== Ground transports ===

'''script.TransportPickup''' ( passengerID ) -> nil

Called when a passenger should be loaded into the transport. This should eventually call AttachUnit to actually attach the unit. Assuming the transport is in range of the next passenger, this will be called again for the next passenger 16 frames later, ''unless'' the script enters the BUSY state: then Spring will not move on to the next passenger until the script leaves the BUSY state.

'''script.TransportDrop''' ( passengerID, x, y, z ) -> nil

Called when a passenger should be unloaded. This should eventually call DetachUnit to actually detach the unit, ''unless'' the used unload method is UnloadLandFlood, in which case Spring will actually detach the unit after the call.

'''script.EndTransport''' ( ) -> nil

Only called in UnloadLandFlood behavior, after the last unit has been unloaded.

=== Passenger ===

'''script.Falling''' ( ) -> nil

For a unit dropped from an UnloadDrop transport, this is called every frame to inform the script the unit is still falling. It may be used to show a parachute for example.

'''script.Landed''' ( ) -> nil

This is called one time after the unit reached the ground. May be used to hide a parachute for example.

== Internal ==

These call-ins are NOT available to Lua unit scripts. They are called by the engine however, but always 'intercepted' by the framework gadget. For completeness (or if you are poking at the gadget), they are listed here anyway.

'''script.MoveFinished''' ( piece, axis ) -> nil<br>
'''script.TurnFinished''' ( piece, axis ) -> nil

Called when a move or turn finished. The framework gadget uses this to resume the coroutines which are waiting for the particular move or turn to be finished.

'''script.Destroy''' ( ) -> nil

Called right before the unit's script is destroyed. This may happen if the unit is being destroyed, but also if the unit's script is being replaced by another script. The framework gadget uses this to stop all threads and remove the unit from some internal data structures.

[[Category:Animation]]
[[Category:Lua]]

Modrules.lua

2022-07-05T05:23:32Z

Forboding angel: /* system */

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

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

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

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

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

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

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

===flankingBonus===
{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Gamedev:UnitDefs|flankingBonusMode}} for units. Can be <code>0</code> - No flanking bonus. Mode <code>1</code> builds up the ability to move over time, and swings to face attacks, but does not respect the way the unit is facing. Mode <code>2</code> also can swing, but moves with the unit as it turns. Mode <code>3</code> stays with the unit as it turns and otherwise doesn't move, the ideal mode to simulate something such as tank armour.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = pathFinderRawDistMult
|type = float
|default = 1.25
|special={{new|105.+ BAR}}
|description = Engine does raw move with a limited distance, this multiplier adjusts that}}

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

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

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

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

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

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

==Examples==

===Empty===

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

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

===External Examples===
[https://github.com/EvolutionRTS/Evolution-RTS/blob/master/Gamedata/modrules.lua 'Evolution RTS' Modrules.lua]

[[Category:gamedata]]

Modrules.lua

2021-05-30T03:34:22Z

Forboding angel: /* External Examples */

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

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

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

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

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

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

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

===flankingBonus===
{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Gamedev:UnitDefs|flankingBonusMode}} for units. Can be <code>0</code> - No flanking bonus. Mode <code>1</code> builds up the ability to move over time, and swings to face attacks, but does not respect the way the unit is facing. Mode <code>2</code> also can swing, but moves with the unit as it turns. Mode <code>3</code> stays with the unit as it turns and otherwise doesn't move, the ideal mode to simulate something such as tank armour.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Examples==

===Empty===

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

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

===External Examples===
[https://github.com/EvolutionRTS/Evolution-RTS/blob/master/Gamedata/modrules.lua 'Evolution RTS' Modrules.lua]

[[Category:gamedata]]

Lua UnitDefs

2020-02-14T02:57:44Z

Forboding angel: Add helpful "are you lost?" to page so that perhaps people who end up on the wrong page will figure it out sooner rather than later.

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

'''Were you looking for the unitDefs page for Game Developers?''' ([[Gamedev:UnitDefs]])

==What is this==
The '''UnitDefs[]''' table holds information about the unit'''types''' used in the game. It is indexed by a number, and normally refered to as unitDefID. It is read-only. To access its tags you write, for example,
<pre>
UnitDefs[unitDefID].name
</pre>

'''Note:'''<br>
The name of the keys often vary from the ones in the [[Gamedev:UnitDefs]] files.
For example ''maxDamage'' is named ''health''.

==UnitDefs reverse lookup: UnitDefNames==
The '''UnitDefNames[]''' table holds the unitdefs and can be used to get the unitdef table for a known unitname:
<pre>
local unitDef = UnitDefNames["supertank"]
</pre>

==Print all unitDefs==
This example code prints all unitdefs, with all keys and their values (but not their subtables).
<pre>
for id,unitDef in pairs(UnitDefs) do
for name,param in unitDef:pairs() do
Spring.Echo(name,param)
end
end
</pre>
Note that unitDef is a metatable, and requires the special iterator unitDef:pairs()

==Useful keys/snippets==
<code> UnitDefs[unitDefID].id </code> - gives back the unitDefID

<code> UnitDefs[unitDefID].name </code> - the internal unit name

<code> UnitDefs[unitDefID].humanName </code> - the displayed unit name

<code>UnitDefs[unitDefID].weapons</code> - See [[Lua_WeaponDefs]], <code>UnitDefs[unitDefID].weapons[1].weaponDef</code> returns the weaponDefID of the units first weapon, which apppears in the WeaponsDef table as <code>WeaponDefs[weaponDefID]</code>.

To read [[Gamedev:UnitDefs#customParams|custom parameters]] use:
<pre>
local myCustomParameters = UnitDefs[unitDefID].customParams
if (myCustomParameters) then
blub = myCustomParameters.blubfactor
end
</pre>
Key-names of the customParams table written must be lowercase and their values can only be strings.

===Types of Units===
Sometimes one wants to check type of unit. Like is it a factory, is it a transport and so on.
Complete list: <ref>''Spring 95, commit message'',{{Sourcelinkhash|4e58b8b0f7af04065878d34e5e17523246739b0c}}</ref>

*isTransport
*isImmobile
*isBuilding
*isBuilder
*isMobileBuilder
*isStaticBuilder
*isFactory
*isExtractor
*isGroundUnit
*isAirUnit
*isStrafingAirUnit
*isHoveringAirUnit
*isFighterAirUnit
*isBomberAirUnit

==Example UnitDef table==
In the form of key = value, where UnitDefs[unitDefID].key = value, with subtables at the bottom.

<pre>
activateWhenBuilt = true,
airLosRadius = 5.2734375,
airStrafe = true,
armorType = 3,
armoredMultiple = 1,
autoHeal = 2.5,
bankingAllowed = true,
buildDistance = 112,
buildRange3D = false,
buildSpeed = 300,
buildTime = 75000,
builder = false,
buildingDecalDecaySpeed = 0.10000000149012,
buildingDecalSizeX = 4,
buildingDecalSizeY = 4,
buildingDecalType = -1,
buildpicname = "CORCOM.DDS",
canAssist = true,
canAttack = true,
canAttackWater = true,
canBeAssisted = true,
canCapture = true,
canCloak = true,
canCrash = false,
canDGun = false,
canDropFlare = false,
canFight = true,
canFireControl = true,
canFly = false,
canGuard = true,
canKamikaze = false,
canLoopbackAttack = false,
canManualFire = true,
canMove = true,
canParalyze = false,
canPatrol = true,
canReclaim = true,
canRepair = true,
canRepeat = true,
canRestore = true,
canResurrect = false,
canSelfD = true,
canSelfRepair = false,
canStockpile = false,
canSubmerge = false,
cantBeTransported = false,
capturable = true,
captureSpeed = 900,
cloakCost = 100,
cloakCostMoving = 1000,
cloakTimeout = 128,
cobID = -1,
collide = true,
cost = 3111.4499511719,
crashDrag = 0.0049999998882413,
deathExplosion = "commander_blast",
decloakDistance = 50,
decloakOnFire = true,
decloakSpherical = true,
dlHoverFactor = -1,
energyCost = 26667,
energyMake = 25,
energyStorage = 0,
energyUpkeep = 0,
extractRange = 0,
extractsMetal = 0,
factoryHeadingTakeoff = true,
fallSpeed = 0.20000000298023,
fireState = -1,
flankingBonusDirX = 0,
flankingBonusDirY = 0,
flankingBonusDirZ = 1,
flankingBonusMax = 1.8999999761581,
flankingBonusMin = 0.89999997615814,
flankingBonusMobilityAdd = 0.0099999997764826,
flankingBonusMode = 1,
flareDelay = 0.30000001192093,
flareDropVectorX = 0,
flareDropVectorY = 0,
flareDropVectorZ = 0,
flareEfficiency = 0.5,
flareReloadTime = 5,
flareSalvoDelay = 0,
flareSalvoSize = 4,
flareTime = 90,
floatOnWater = false,
floater = false,
frontToSpeed = 0.10000000149012,
fullHealthFactory = false,
hasShield = false,
health = 3000,
height = 50,
hideDamage = true,
highTrajectoryType = 0,
holdSteady = false,
hoverAttack = false,
humanName = "Commander",
iconType = "corcom.user",
id = 261,
idleAutoHeal = 2.5,
idleTime = 1800,
isAirBase = false,
isAirUnit = false,
isBomberAirUnit = false,
isBuilder = true,
isBuilding = false,
isCommander = false,
isExtractor = false,
isFactory = false,
isFeature = false,
isFighterAirUnit = false,
isFirePlatform = false,
isGroundUnit = true,
isHoveringAirUnit = false,
isImmobile = false,
isMobileBuilder = true,
isStaticBuilder = false,
isStrafingAirUnit = false,
isTransport = false,
jammerRadius = 0,
kamikazeDist = 0,
kamikazeUseLOS = false,
leaveTracks = false,
levelGround = true,
loadingRadius = 220,
losHeight = 40,
losRadius = 14.0625,
makesMetal = 0,
mass = 5000,
maxAcc = 0.18000000715256,
maxAileron = 0.014999999664724,
maxBank = 0.80000001192093,
maxCoverage = 0,
maxDec = 1.125,
maxElevator = 0.0099999997764826,
maxFuel = 0,
maxHeightDif = 14.558809280396,
maxPitch = 0.44999998807907,
maxRepairSpeed = 300,
maxRudder = 0.0040000001899898,
maxSlope = -1,
maxThisUnit = 32000,
maxWaterDepth = 35,
maxWeaponRange = 300,
maxx = 17.423709869385,
maxy = 48.386325836182,
maxz = 14.10532283783,
metalCost = 2667,
metalMake = 1.5,
metalStorage = 0,
metalUpkeep = 0,
midx = 0.66120779514313,
midy = 19,
midz = 1.7122877836227,
minAirBasePower = 0,
minCollisionSpeed = 1,
minWaterDepth = -10000000,
minx = -16.537784576416,
miny = 0.058725833892822,
minz = -9.709508895874,
moveState = -1,
myGravity = 0.40000000596046,
name = "corcom",
nanoColorB = 0.20000000298023,
nanoColorG = 0.69999998807907,
nanoColorR = 0.20000000298023,
needGeo = false,
onOffable = false,
power = 3111.4499511719,
primaryWeapon = 2,
rSpeed = 0,
radarRadius = 700,
radius = 22,
reclaimSpeed = 300,
reclaimable = false,
refuelTime = 5,
releaseHeld = false,
reloadTime = 1,
repairSpeed = 300,
repairable = true,
resurrectSpeed = 300,
scriptName = "corcom.cob",
scriptPath = "corcom.cob",
seismicRadius = 0,
seismicSignature = 0,
selfDCountdown = 5,
selfDExplosion = "commander_blast",
shieldPower = -1,
showNanoFrame = true,
showNanoSpray = true,
showPlayerName = true,
slideTolerance = 0,
sonarJamRadius = 0,
sonarRadius = 300,
sonarStealth = false,
speed = 37.5,
speedToFront = 0.070000000298023,
startCloaked = false,
stealth = false,
strafeToAttack = false,
targfac = false,
techLevel = 0,
terraformSpeed = 1500,
tidalGenerator = 0,
tooltip = "Commander",
totalEnergyOut = 25,
trackOffset = 0,
trackStrength = 0,
trackStretch = 1,
trackType = -1,
trackWidth = 32,
transportByEnemy = false,
transportCapacity = 0,
transportMass = 100000,
transportSize = 0,
transportUnloadMethod = 0,
turnInPlace = true,
turnInPlaceSpeedLimit = 0.82499998807907,
turnRadius = 500,
turnRate = 1133,
type = "",
unitFallSpeed = 0,
upright = true,
useBuildingGroundDecal = false,
useSmoothMesh = true,
verticalSpeed = 3,
wantedHeight = 0,
waterline = 0,
windGenerator = 0,
wingAngle = 0.079999998211861,
wingDrag = 0.070000000298023,
wreckName = "corcom_dead",
xsize = 4,
zsize = 4,

buildOptions = {
[1] = unitDefID1,
[2] = unitDefID2,
...
},
collisionVolume = {
boundingRadius = 1.0893974967364e-026,
defaultToFootPrint = false,
defaultToPieceTree = false,
defaultToSphere = false,
offsetX = 0,
offsetY = 1,
offsetZ = 1.089395031546e-026,
scaleX = 6.4911419586111e-027,
scaleY = 1.9340968033141e-038,
scaleZ = 1.0894122878784e-026,
type = "ellipsoid",
},
customParams = {
...
},
modCategories = {
all = true,
commander = true,
notair = true,
...
},
model = {
name = "CORCOM.s3o",
path = "objects3d/CORCOM.s3o",
type = "s3o",
textures = {
tex1 = "Core_color.dds",
tex2 = "Core_other.dds",
},
},
moveDef = {
crushStrength = 50,
depth = 5000,
depthMod = 0,
family = "kbot",
heatMapping = false,
heatMod = 0.0041666668839753,
heatProduced = 60,
id = 6,
maxSlope = 0.41221469640732,
name = "akbot2",
slopeMod = 9.6801977157593,
type = "ground",
xsize = 3,
zsize = 3,
},
noChaseCategories = {
all = true,
...
},
sounds = {
activate = {},
arrived = {},
build = {
[1] = {
id = 208,
name = "nanlath2",
volume = 1,
},
...
},
...
},
weapons = {
[1] = {
fuelUsage = 0,
mainDirX = 0,
mainDirY = 0,
mainDirZ = 0.99999564886093,
maxAngleDif = -1,
slavedTo = 0,
weaponDef = 221,
badTargets = {
vtol = true,
},
onlyTargets = {
all = true,
antiemg = true,
...
},
},
...
},
</pre>

==Unit/Weapon damages and armor classes==

For details on how to extract which units/weapons target/damage which units, see https://springrts.com/phpbb/viewtopic.php?f=44&t=34382&p=575738#p575738 (TODO: migrate info to wiki).

==How to save unitDef tables to file==
To save all unitDefs to a file, including all tables, you can use
<pre>
local unitDef = UnitDefs[unitDefID]
local t = {}
for k,v in unitDef:pairs() do
t[k] = v
end
table.save(t, "lua_unitDef_" .. unitDef.name .. ".lua", "-- generated by table.save")
</pre>
The special iterator is needed because metatables. See https://springrts.com/phpbb/viewtopic.php?f=67&t=33778 for a widget to regenerate the example defs.

[[category: Lua]]

----
<references/>

Gamedev:UnitDefs

2020-02-14T02:31:18Z

Forboding angel: Nevermind, mediawiki's search is even shittier than I thought.

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

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

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

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The following tags have now been removed from the engine:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Sub Tables==

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

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

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

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

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

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

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

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

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

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

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

The following additional tags are associated with this subtable:

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

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

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

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

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

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

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

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

There are no additional tags specific to this subtable.

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

====explosionGenerators====

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

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

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

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

===sounds===

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

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

Sounds can be defined in one of three ways:

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

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

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

====sounds Example====

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

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

====sounds Events====

The events called by the engine are as follows:

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

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

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

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

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

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

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

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

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

There are no additional tags specific to this subtable

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

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

[[Category: Game Dev]]

Gamedev:UnitDefs

2020-02-14T02:29:14Z

Forboding angel: Add some minor keywords, specifically "unitdef" as it will return zero results whereas unitdefs will return the expected results.

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

<div class="keywords">'''Keywords:'''
unitdef, unitdefs, unit files </div>

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

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

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The following tags have now been removed from the engine:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Sub Tables==

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

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

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

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

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

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

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

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

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

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

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

The following additional tags are associated with this subtable:

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

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

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

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

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

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

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

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

There are no additional tags specific to this subtable.

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

====explosionGenerators====

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

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

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

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

===sounds===

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

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

Sounds can be defined in one of three ways:

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

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

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

====sounds Example====

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

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

====sounds Events====

The events called by the engine are as follows:

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

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

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

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

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

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

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

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

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

There are no additional tags specific to this subtable

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

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

[[Category: Game Dev]]

Mapdev:sunDir

2020-02-14T02:20:29Z

Forboding angel: Add a possibly more colloquial term

<div class="keywords"> sun, position, direction, sunDir, sun position, sun direction, sun grid </div>

This grid is meant to show on a 2d plane, where the sun position will be on your map and the values needed for x and z axis positioning.

WARNING - It is entirely possible that the engine causes these values to be mirrored when the map loads, so pay attention. You can make it super easy to see where the sun position is by lowering it significantly (e.g. y = 0.2) and using terrain and trees to see the shadow positions. A little janky, but it works.

Without further adieu, the grid:

[[File:Map_Grid.png]]

If someone wants to make it better, here is a link to the PSD:

https://drive.google.com/file/d/15t9gVU0fsqzPequvxePgVTEe5IhCDw29/view?usp=sharing

Mapdev:sunDir

2020-02-14T02:11:31Z

Forboding angel: Apparently I have to be more pedantic with the keywords

<div class="keywords"> sun, position, direction, sunDir, sun position, sun direction </div>

This grid is meant to show on a 2d plane, where the sun position will be on your map and the values needed for x and z axis positioning.

WARNING - It is entirely possible that the engine causes these values to be mirrored when the map loads, so pay attention. You can make it super easy to see where the sun position is by lowering it significantly (e.g. y = 0.2) and using terrain and trees to see the shadow positions. A little janky, but it works.

Without further adieu, the grid:

[[File:Map_Grid.png]]

If someone wants to make it better, here is a link to the PSD:

https://drive.google.com/file/d/15t9gVU0fsqzPequvxePgVTEe5IhCDw29/view?usp=sharing

Sun Position Direction sunDir

2020-02-14T02:10:35Z

Forboding angel:

The droids you are looking for are in another castle: https://springrts.com/wiki/Mapdev:sunDir

Mapdev:sunDir

2020-02-14T02:08:55Z

Forboding angel: Created page with "<div class="keywords"> sun, position, direction, sunDir </div> This grid is meant to show on a 2d plane, where the sun position will be on your map and the values needed for..."

<div class="keywords"> sun, position, direction, sunDir </div>

This grid is meant to show on a 2d plane, where the sun position will be on your map and the values needed for x and z axis positioning.

WARNING - It is entirely possible that the engine causes these values to be mirrored when the map loads, so pay attention. You can make it super easy to see where the sun position is by lowering it significantly (e.g. y = 0.2) and using terrain and trees to see the shadow positions. A little janky, but it works.

Without further adieu, the grid:

[[File:Map_Grid.png]]

If someone wants to make it better, here is a link to the PSD:

https://drive.google.com/file/d/15t9gVU0fsqzPequvxePgVTEe5IhCDw29/view?usp=sharing

Sun Position Direction sunDir

2020-02-14T02:05:03Z

Forboding angel: This page is going to end up being deleted, but in the process I learned a little about how to do some basic wiki stuffs. For those wiki changelog purists out there.

<div class="keywords"> sun, position, direction, sunDir </div>

The title of this page has been keyword stuffed in order to hopefully catch any terms mappers might use when trying to find this grid. This grid existed 10+ years ago in the wiki but has long since been lost.

This grid is meant to show on a 2d plane, where the sun position will be on your map and the values needed for x and z axis positioning.

WARNING - It is entirely possible that the engine causes these values to be mirrored when the map loads, so pay attention. You can make it super easy to see where the sun position is by lowering it significantly (e.g. y = 0.2) and using terrain and trees to see the shadow positions. A little janky, but it works.

Without further adieu, the grid:

[[File:Map_Grid.png]]

If someone wants to make it better, here is a link to the PSD:

https://drive.google.com/file/d/15t9gVU0fsqzPequvxePgVTEe5IhCDw29/view?usp=sharing

Sun Position Direction sunDir

2020-02-14T02:00:30Z

Forboding angel: Apparently you can keyword stuff without doing it in the title

<div class="keywords"> Foo, Bar, Blaz </div>

The title of this page has been keyword stuffed in order to hopefully catch any terms mappers might use when trying to find this grid. This grid existed 10+ years ago in the wiki but has long since been lost.

This grid is meant to show on a 2d plane, where the sun position will be on your map and the values needed for x and z axis positioning.

WARNING - It is entirely possible that the engine causes these values to be mirrored when the map loads, so pay attention. You can make it super easy to see where the sun position is by lowering it significantly (e.g. y = 0.2) and using terrain and trees to see the shadow positions. A little janky, but it works.

Without further adieu, the grid:

[[File:Map_Grid.png]]

If someone wants to make it better, here is a link to the PSD:

https://drive.google.com/file/d/15t9gVU0fsqzPequvxePgVTEe5IhCDw29/view?usp=sharing

Sun Position Direction sunDir

2020-02-14T01:58:15Z

Forboding angel:

The title of this page has been keyword stuffed in order to hopefully catch any terms mappers might use when trying to find this grid. This grid existed 10+ years ago in the wiki but has long since been lost.

This grid is meant to show on a 2d plane, where the sun position will be on your map and the values needed for x and z axis positioning.

WARNING - It is entirely possible that the engine causes these values to be mirrored when the map loads, so pay attention. You can make it super easy to see where the sun position is by lowering it significantly (e.g. y = 0.2) and using terrain and trees to see the shadow positions. A little janky, but it works.

Without further adieu, the grid:

[[File:Map_Grid.png]]

If someone wants to make it better, here is a link to the PSD:

https://drive.google.com/file/d/15t9gVU0fsqzPequvxePgVTEe5IhCDw29/view?usp=sharing

Sun Position Direction sunDir

2020-02-14T01:56:40Z

Forboding angel:

Sun Position Direction sunDir

2020-02-14T01:55:23Z

Forboding angel:

File:Map Grid.png

2020-02-14T01:55:09Z

Forboding angel: A grid which shows sun position using sunDir in 2d, representing the X and Z axes.

== Summary ==
A grid which shows sun position using sunDir in 2d, representing the X and Z axes.

Sun Position Direction sunDir

2020-02-14T01:53:25Z

Forboding angel: Created page with "The title of this page has been keyword stuffed in order to hopefully catch any terms mappers might use when trying to find this grid. This grid existed 10+ years ago in the w..."

UI commands

2019-10-14T03:20:21Z

Forboding angel: /* Lists of commands, some are even explained */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}
=How to use the console=
The ingame chat is the console. Open with hitting the `<code>return</code>` or `<code>enter</code>` key.
If you want to enter a command into ingame chat, you must add a <code>/</code> in front<br>
for example: <code>/commandhelp</code><br>
Some commands will also autocomplete if you press <code>TAB</code>. So if you enter "/com" and then to press TAB, it will complete it to `/command` and tells you there is `/commandhelp` & `/commandlist`, if you now enter either `l` or `h` and press TAB again it will complete to one of them.

Also commands are not case-sensitive.

=Lists of commands, some are even explained=

For a complete (excluding Lua commands & some engine `actions`) use:
<code>/commandlist</code>

Example output (104.0):
<pre style="overflow:auto; width:auto;">
Chat commands plus description
==============================
/Atm (synced) Gives 1000 metal and 1000 energy to the issuing players team
/Cheat (synced) Enables/Disables cheating, which is required for a lot of other commands to be usable
/Destroy (synced) Destroys one or multiple units by unit-ID, instantly
/DevLua (synced) Enables/Disables Lua dev-mode (can cause desyncs if enabled)
/EditDefs (synced) Allows/Disallows editing of unit-, feature- and weapon-defs through Lua
/Give [amount] <objectName|'all'>(synced) Places one or multiple units of a single or multiple types on the map, instantly; by default to your own team. Example : /give 10 corkrog 3 - gives team 3 10 corkrogs.
/GlobalLOS (synced) Enables/Disables global line-of-sight, which makes the whole map permanently visible to everyone or to a specific allyteam
/GodMode (synced) Enables/Disables god-mode, which allows all players (even spectators) to control all units (even during replays, which will DESYNC them)
/LuaGaia (synced) Allows reloading or disabling LuaGaia, and to send a chat message to LuaGaia scripts
/LuaRules (synced) Allows reloading or disabling LuaRules, and to send a chat message to LuaRules scripts
/NoCost (synced) Enables/Disables everything-for-free, which allows everyone to build everything for zero resource costs
/NoHelp (synced) Enables/Disables widgets (LuaUI control)
/NoSpecDraw (synced) Allows/Disallows spectators to draw on the map
/NoSpectatorChat (synced) Enables/Disables spectators to use the chat
/ReloadCEGs (synced) Reloads CEG scripts
/ReloadCOB (synced) Reloads COB scripts
/Skip (synced) Fast-forwards to a given frame, or stops fast-forwarding
/Take (synced) Transfers all units of allied teams without any active players to the team of the issuing player
/AdvMapShading (unsynced) Set or toggle advanced map shading mode
/AdvModelShading (unsynced) Set or toggle advanced model shading mode
/AIControl (unsynced) Creates a new instance of a Skirmish AI, to let it controll a specific team
/AIKill (unsynced) Kills the Skirmish AI controlling a specified team
/AIList (unsynced) Prints a list of all currently active Skirmish AIs
/AIReload (unsynced) Reloads the Skirmish AI controlling a specified team
/AirMesh (unsynced) Show/Hide the smooth air-mesh map overlay
/AllMapMarks (unsynced) Show/Hide all map marks drawn so far
/Ally (unsynced) Starts/Ends alliance of the local players ally-team with another ally-team
/ATM (unsynced) Redirects command /ATM to its synced processor
/BufferText (unsynced) Write the argument string(s) directly to the console history, but not anywhere else. This is useful for fast manual issuing of the command, later on
/Chat (unsynced) Starts waiting for intput to be sent to
/ChatAll (unsynced) Starts waiting for intput to be sent to All
/ChatAlly (unsynced) Starts waiting for intput to be sent to Ally
/ChatSpec (unsynced) Starts waiting for intput to be sent to Spec
/ClearMapMarks (unsynced) Remove all map marks drawn so far
/Clock (unsynced) Shows a small digital clock indicating the local time
/CmdColors (unsynced) Reloads cmdcolors.txt
/CommandHelp (unsynced) Prints info about a specific chat command (so far only synced/unsynced and the description)
/CommandList (unsynced) Prints all the available chat commands with description (if available) to the console
/Console (unsynced) Enables/Disables the in-game console
/ControlUnit (unsynced) Start to first-person-control a unit
/Crash (unsynced) Invoke an artificial crash through a NULL-pointer dereference (SIGSEGV)
/CreateVideo (unsynced) Start/Stop capturing a video of the game in progress
/Cross (unsynced) Allows one to exchange and modify the appearance of the cross/mouse-pointer in first-person-control view
/CtrlPanel (unsynced) Reloads GUI config
/Debug (unsynced) Enable/Disable debug rendering mode
/DebugColVol (unsynced) Enable/Disable drawing of collision volumes
/DebugDrawAI (unsynced) Enables/Disables debug drawing for AIs
/DebugGL (unsynced) Enable/Disable OpenGL debug-context output
/DebugGLErrors (unsynced) Enable/Disable OpenGL debug-errors
/DebugInfo (unsynced) Print debug info to the chat/log-file about either: sound, profiling
/DebugPath (unsynced) Enable/Disable drawing of pathfinder debug-data
/DebugTraceRay (unsynced) Enable/Disable drawing of traceray debug-data
/DecGUIOpacity (unsynced) Decreases the opacity(see-through-ness) of GUI elements
/DecreaseViewRadius (unsynced) Decrease the view radius (higher performance, uglier view)
/Deselect (unsynced) Deselects all currently selected units
/Destroy (unsynced) Destroys one or multiple units by unit-ID, instantly
/DistDraw (unsynced) Set the distance between units and camera, at which they turn into far-textures (flat/texture-only representation) (Graphic setting)
/DistIcon (unsynced) Set the distance between units and camera, at which they turn into icons (Graphic setting)
/DivByZero (unsynced) Invoke an artificial crash by performing a division-by-Zero
/DrawInMap (unsynced) Enables drawing on the map
/DrawLabel (unsynced) Draws a label on the map at the current mouse-pointer position
/DrawTrees (unsynced) Enable/Disable engine-tree rendering
/DumpState (unsynced) dump game-state to file
/DynamicSky (unsynced) Enable/Disable dynamic-sky rendering
/Echo (unsynced) Write a string to the log file
/EndGraph (unsynced) Enables/Disables the statistics graphs shown at the end of the game
/Exception (unsynced) Invoke an artificial crash by throwing an std::runtime_error
/Font (unsynced) Reloads the fonts
/FPS (unsynced) Shows/Hides the frames-per-second indicator
/FPSHud (unsynced) Enables/Disables HUD (GUI interface) shown in first-person-control mode
/Fullscreen (unsynced) Switches fullscreen mode
/GameInfo (unsynced) Enables/Disables game-info panel rendering
/GatherMode (unsynced) Enter/Leave gather-wait command mode
/Give (unsynced) Places one or multiple units of a single or multiple types on the map, instantly; by default to your own team
/GrabInput (unsynced) Prevents/Enables the mouse from leaving the game window (windowed mode only)
/GroundDecals (unsynced) Disable/Enable ground-decals rendering. Ground-decals are things like scars appearing on the map after an explosion.
/GroundDetail (unsynced) Set the level of ground detail
/Group (unsynced) Allows modifying the members of a group
/Group0 (unsynced) Allows modifying the members of group 0
/Group1 (unsynced) Allows modifying the members of group 1
/Group2 (unsynced) Allows modifying the members of group 2
/Group3 (unsynced) Allows modifying the members of group 3
/Group4 (unsynced) Allows modifying the members of group 4
/Group5 (unsynced) Allows modifying the members of group 5
/Group6 (unsynced) Allows modifying the members of group 6
/Group7 (unsynced) Allows modifying the members of group 7
/Group8 (unsynced) Allows modifying the members of group 8
/Group9 (unsynced) Allows modifying the members of group 9
/HardwareCursor (unsynced) Enables/Disables hardware mouse-cursor support
/HideInterface (unsynced) Hide/Show the GUI controlls
/IncGUIOpacity (unsynced) Increases the opacity(see-through-ness) of GUI elements
/IncreaseViewRadius (unsynced) Increase the view radius (lower performance, nicer view)
/Info (unsynced) Shows/Hides the player roster
/InputTextGeo (unsynced) Move and/or resize the input-text field (the "Say: " thing)
/LastMsgPos (unsynced) Moves the camera to show the position of the last message
/LessClouds (unsynced) Decreases the density of clouds (higher performance)
/LessTrees (unsynced) Decreases distance from the camera at which trees are still drawn
/LODScale (unsynced) Set the scale for either of: LOD (level-of-detail), shadow-LOD, reflection-LOD, refraction-LOD
/LuaGaia (unsynced) Redirects command /LuaGaia to its synced processor
/LuaRules (unsynced) Redirects command /LuaRules to its synced processor
/LuaSave (unsynced) Save the game state to a specific file, add -y to overwrite when file is already present
/LuaUI (unsynced) Allows one to reload or disable LuaUI, or alternatively to send a chat message to LuaUI
/MapBorder (unsynced) Set or toggle map-border rendering
/MapMarks (unsynced) Enables/Disables map marks rendering
/mapmeshdrawer (unsynced) Switch map-mesh rendering modes: 0=GCM, 1=HLOD, 2=ROAM
/MapShadowPolyOffset (unsynced)
/MaxNanoParticles (unsynced) Set the maximum number of nano-particles (Graphic setting)
/MaxParticles (unsynced) Set the maximum number of particles (Graphics setting)
/MiniMap (unsynced) FIXME document subcommands
/MoreClouds (unsynced) Increases the density of clouds (lower performance)
/MoreTrees (unsynced) Increases distance from the camera at which trees are still drawn
/Mouse1 (unsynced) Simulates a mouse button press of button 1
/Mouse2 (unsynced) Simulates a mouse button press of button 2
/Mouse3 (unsynced) Simulates a mouse button press of button 3
/Mouse4 (unsynced) Simulates a mouse button press of button 4
/Mouse5 (unsynced) Simulates a mouse button press of button 5
/MoveBack (unsynced) Moves the camera Back a bit
/MoveDown (unsynced) Moves the camera Down a bit
/MoveFast (unsynced) Moves the camera Fast a bit
/MoveForward (unsynced) Moves the camera Forward a bit
/MoveLeft (unsynced) Moves the camera Left a bit
/MoveRight (unsynced) Moves the camera Right a bit
/MoveSlow (unsynced) Moves the camera Slow a bit
/MoveUp (unsynced) Moves the camera Up a bit
/MuteSound (unsynced) Mute/Unmute the current sound system
/NoLuaDraw (unsynced) Allow/Disallow Lua to draw on the map
/PasteText (unsynced) Paste either the argument string(s) or if none given, the content of the clip-board to chat input
/Pause (unsynced) Pause/Unpause the game
/QuitForce (unsynced) Exits game to system
/QuitMenu (unsynced) Opens the quit-menu, if it is not already open
/QuitMessage (unsynced) Deprecated, see /Quit instead (was used to quite the game immediately)
/ReloadForce (unsynced) Exits game to menu
/ReloadGame (unsynced) Restarts the game with the initially provided start-script
/ReloadShaders (unsynced) Reloads all engine shaders
/ResBar (unsynced) Shows/Hides team resource storage indicator bar
/Resync (unsynced) Redirects command /Resync to its synced processor
/SafeGL (unsynced) Enables/Disables OpenGL safe-mode
/Save (unsynced) Save the game state to a specific file, add -y to overwrite when file is already present
/SaveGame (unsynced) Save the game state to QuickSave.ssf (BROKEN)
/Say (unsynced) Say something in (public) chat
/ScreenShot (unsynced) Take a low quality JPG screen-shot of the current view
/ScreenShot png (unsynced) Take a high quality PNG screen-shot of the current view
/Select (unsynced) <chat command description: Select>
/SelectCycle (unsynced) <chat command description: SelectUnits>
/SelectUnits (unsynced) <chat command description: SelectUnits>
/Send (unsynced) Send a string as raw network message to the game host (for debugging only)
/Set (unsynced) Set a config key=value pair
/Shadows (unsynced) Disables/Enables shadows rendering: -1=disabled, 0=off, 1=full shadows, 2=skip terrain shadows
/ShareDialog (unsynced) Opens the share dialog, which allows you to send units and resources to other players
/ShowElevation (unsynced) Enable rendering of the auxiliary height-map overlay
/ShowMetalMap (unsynced) Enable rendering of the auxiliary metal-map overlay
/ShowPathCost (unsynced) Enable rendering of the path cost-map overlay
/ShowPathFlow (unsynced) Enable/Disable rendering of the path flow-map overlay
/ShowPathHeat (unsynced) Enable/Disable rendering of the path heat-map overlay
/ShowPathTraversability (unsynced) Enable rendering of the path traversability-map overlay
/ShowPathType (unsynced) Shows path traversability for a given MoveDefName, MoveDefID or UnitDefName
/ShowStandard (unsynced) Disable rendering of all auxiliary map overlays
/SlowDown (unsynced) Decreases the simulation speed. The engine will try to simulate less frames per second
/SoundChannelEnable (unsynced) Enable/Disable specific sound channels: UnitReply, General, Battle, UserInterface, Music
/SoundDevice (unsynced) Switch the sound output system (currently only OpenAL / NullAudio)
/SpecFullView (unsynced) Sets or toggles between full LOS or ally-team LOS, if the local user is a spectator
/Spectator (unsynced) Lets the local user give up control over a team, and start spectating
/SpecTeam (unsynced) Lets the local user specify the team to follow, if he is a spectator
/Speed (unsynced) Shows/Hides the simulation speed indicator
/SpeedControl (unsynced) Sets how server adjusts speed according to player's load (CPU), 1: use average, 2: use highest,
/SpeedUp (unsynced) Increases the simulation speed. The engine will try to simulate more frames per second
/Take (unsynced) Redirects command /Take to its synced processor
/Team (unsynced) Lets the local user change to another team
/TeamHighlight (unsynced) Enables/Disables uncontrolled team blinking
/ToggleInfo (unsynced) Toggles current info texture view
/ToggleLOS (unsynced) Enable rendering of the auxiliary LOS-map overlay
/ToolTip (unsynced) Enables/Disables the general tool-tips, displayed when hovering over units. features or the map
/Track (unsynced) Start following the selected unit(s) with the camera
/TrackMode (unsynced) Shift through different ways of following selected unit(s)
/TrackOff (unsynced) Stop following the selected unit(s) with the camera
/TSet (unsynced) Set a config key=value pair in the overlay, meaning it will not be persisted for future games
/ViewSelection (unsynced) Moves the camera to the center of the currently selected units
/VSync (unsynced) Enables/Disables vertical-sync (Graphics setting)
/W (unsynced) Say something in private to a specific player, by player-name
/Water (unsynced) Set water rendering mode: 0=basic, 1=reflective, 2=dynamic, 3=reflective&refractive, 4=bump-mapped
/WByNum (unsynced) Say something in private to a specific player, by player-ID
/WireMap (unsynced) Toggle wireframe-mode drawing of map geometry
/WireModel (unsynced) Toggle wireframe-mode drawing of model geometry
/WireSky (unsynced) Toggle wireframe-mode drawing of skydome geometry
/WireTree (unsynced) Toggle wireframe-mode drawing of tree geometry
/WireWater (unsynced) Toggle wireframe-mode drawing of water geometry
</pre>
More commands:
<pre style="overflow:auto; width:auto;">
/bind <keyset> <action> Binds a key or key combination. Example with a key: /bind a reclaim. Example with a "key combination": /bind ctrl+a reclaim
/luagaia reload Reloads gaia gadgets
/luarules reload Reloads gadgets
/luaui reload
/luaui tweakgui Tweak mode on
/Setmaxspeed # Changes the maximum speed (default is 3.0)
/Setminspeed # Changes the minimum speed (default is 0.3)
/unbind <keyset> <action> Unbinds a key or key combination. Example: /unbind a reclaim.
/unbindaction <action> Unbinds all keybinds that uses <action>.
/unbindkeyset <keyset> Unbinds all bindings that uses <keyset>.
/unbindall Unbinds all keys except the chat keybinding.
</pre>

=Scripting=
In Lua scripts, these commands can be used like this:<br>
Spring.SendCommands("resbar 0")<br>
notice the missing / when used like this.<br>

[[Category:Help]]

Movedefs.lua

2019-03-23T01:01:08Z

Forboding angel: /* depthModParams */

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

{{tag
|name = footprintX
|type = int
|default = 1
|description = How wide the '''MoveClass''' is in footprint units, left to right. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Gamedev:UnitDefs|footprintX}} of its [[Gamedev:UnitDefs|UnitDef]].
}}

{{tag
|name = footprintZ
|type = int
|default = footprintX
|description = How wide the '''MoveClass''' is in footprint units, top to bottom. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Gamedev:UnitDefs|footprintZ}} of its [[Gamedev:UnitDefs|UnitDef]].
}}

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

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

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

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

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

{{tag
|name = allowRawMovement
|type = bool
|default = false
|special = {{new|104.0}}
|description = Enables native "raw move" (straight-line path) support (See also [[Lua_SyncedCtrl|Spring.SetUnitMoveGoal]] and {{mantis|4412}}).
}}

=== Heat Tags ===
These tags are used in unit avoidance.

{{tag
|name = heatMapping
|type = bool
|default = false
|description = This enables/disables generation and usage of path heats.
}}

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = maxScale
|type = float
|default = MAX_FLOAT
|description = This is the cap on how severe the depth effect can be. For example, lets say that you use a maxScale value of 2. If a unit is at the depth where its scale reaches the max (usually near its maximum depth; with a maxScale value of 2), the slowest it will go is half of its maximum speed. In other words, (maxVelocity / maxScale). Therefore, as another example, a value of 4 would cause the unit's maximum speed (near the units maximum depth) to be 25% of it's maxVelocity.
}}

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

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

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

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

These previously hard-coded variables allow control over how the pathfinder (default only, not [[QTPFS]], see [[Modrules.lua]]) calculates the cost for a '''MoveClass''' for squares containing mobile units, if and only if {{taglink|avoidMobilesOnPath|true}}.

{{tag
|name = mobileBusyMult
|type = float
|default = 0.1
|description = The cost multiplier for mobile units which are 'Busy'; Not currently being built and with a non-empty command queue, but not moving on a path. Clamped to values above <code>0.01</code>.}}

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

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

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

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

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

--kloot, Thu Jul 31, 2008

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

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

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

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

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

[[Category:Gamedata]]

Movedefs.lua

2019-03-23T00:53:45Z

Forboding angel: /* depthModParams */

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

{{tag
|name = footprintX
|type = int
|default = 1
|description = How wide the '''MoveClass''' is in footprint units, left to right. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Gamedev:UnitDefs|footprintX}} of its [[Gamedev:UnitDefs|UnitDef]].
}}

{{tag
|name = footprintZ
|type = int
|default = footprintX
|description = How wide the '''MoveClass''' is in footprint units, top to bottom. 1 footprint unit = 16 [[elmo]]s. Cannot be below <code>1</code>. For mobile units this should be the same as the {{xtaglink|Gamedev:UnitDefs|footprintZ}} of its [[Gamedev:UnitDefs|UnitDef]].
}}

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

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

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

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

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

{{tag
|name = allowRawMovement
|type = bool
|default = false
|special = {{new|104.0}}
|description = Enables native "raw move" (straight-line path) support (See also [[Lua_SyncedCtrl|Spring.SetUnitMoveGoal]] and {{mantis|4412}}).
}}

=== Heat Tags ===
These tags are used in unit avoidance.

{{tag
|name = heatMapping
|type = bool
|default = false
|description = This enables/disables generation and usage of path heats.
}}

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = maxScale
|type = float
|default = MAX_FLOAT
|description = This is the cap on how severe the depth effect can be. For example, lets say that you use a maxScale value of 2. If a unit is near its maximum depth (with a maxScale value of 2), the slowest it will go is half of its maximum speed. In other words, (maxVelocity / maxScale). Therefore, as another example, a value of 4 would cause the unit's maximum speed (near maximum depth) to be 25% of it's maxVelocity.
}}

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

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

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

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

These previously hard-coded variables allow control over how the pathfinder (default only, not [[QTPFS]], see [[Modrules.lua]]) calculates the cost for a '''MoveClass''' for squares containing mobile units, if and only if {{taglink|avoidMobilesOnPath|true}}.

{{tag
|name = mobileBusyMult
|type = float
|default = 0.1
|description = The cost multiplier for mobile units which are 'Busy'; Not currently being built and with a non-empty command queue, but not moving on a path. Clamped to values above <code>0.01</code>.}}

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

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

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

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

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

--kloot, Thu Jul 31, 2008

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

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

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

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

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

[[Category:Gamedata]]

Games

2016-11-26T03:51:25Z

Forboding angel:

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Games can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
|-
| [[Image:Zero-k_image.jpg|300px|link=http://zero-k.info/]]
| 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]
|-
| <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([https://github.com/spring1944/spring1944/blob/master/docs/License.txt CC-BY-NC])
|-
| [[Image:S44_tigers.jpg|300px|link=http://spring1944.org/]]
| valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-SA])
|-
| [[Image:Evoimg.jpg|300px|link=http://www.evolutionrts.info]]
| 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.
|-
| <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| [[Image:Kernel_Panic_3.4.jpg|300px|link=Kernel Panic]]
| valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| [[Image:CT_Hojos.png|300px|link=http://www.moddb.com/games/conflict-terra]]
| 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.
|-
| <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|-
| [[Image:start3.jpg|300px|link=http://springfiles.com/spring/games/edge-1]]
| 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]
|-
| <h2>[http://www.metalfactions.pt Metal Factions]</h2>
([http://www.metalfactions.pt/about.html#license CC-BY-ND, with GPL/PD code])
|-
| [[Image:Mf_spring_wiki.jpg|300px|link=http://www.metalfactions.pt]]
| valign="top" | An evolving game that started as a TA mod and currently features four factions: AVEN, GEAR, CLAW and SPHERE. Commanders can morph to fit into different play styles and be easily revived. Economy scaling is more strictly tied to map control.
|-
| <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
|-
| [[Image:cursed_logo.jpg|300px|link=http://www.indiedb.com/games/the-cursed]]
| 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.
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
|-
| [[Image:Imperial Winter assault.jpg|300px|link=https://springrts.com/phpbb/viewforum.php?f=46]]
| valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|-
| <h2> [https://springrts.com/phpbb/viewforum.php?f=69 Journeywar] </h2>
|-
| [[Image:JwLogo.jpg|300px|link=https://springrts.com/phpbb/viewtopic.php?f=69&t=23275&start=1180]]
| valign="top" | Journeywar is the final battle between Combine and Exobiotics. Join the fight and rediscover the HL- Universe from a new, strategic perspective. Download in Springlogbby as jw:test archive.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
|<h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
|-
| [[Image:BAScreenShot.jpg|300px|link=http://springrts.com/phpbb/viewforum.php?f=44]]
| 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.
|-
| <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| [[Image:Tech_Annihilation.png|300px|link=http://springfiles.com/spring/games/tech-annihilation-8]]
| valign="top" |This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|-
|<h2>[http://nota.machys.net/downloads NOTA]</h2>
|-
| [[Image:notAgame02.jpg|300px|link=http://nota.machys.net/downloads]]
| 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.
|-
| <h2> [[XTA]] </h2>
|-
| [[Image:Screen508_s.jpg|300px|link=XTA]]
| 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]]

Tutorial:MapDevWithBlueprint(Forb)

2016-11-18T01:34:40Z

Forboding angel: /* Specular Map */

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

= Getting Started (Tools) =

'''Blueprint: '''[https://github.com/jk3064/Map-Blueprint https://github.com/jk3064/Map-Blueprint] 

The only other tool really needed is "Mapconv". The other tools available are there simply to make your life easier. A list of common mapping tools are as follows:

[[MapConv|Mapconv]]

[[MapConvNG|MapConvNG - For use with Linux]]

SMFED '''(Deprecated, no longer useful)'''

Grout '''(Deprecated, no longer useful unless texture was generated with L3dt utilizing tiles)'''

SMD Creator '''(Deprecated, no longer useful)'''

[http://springfiles.com/spring/tools/mapping-tools Start Position Editor]

[http://springfiles.com/spring/tools/mapping-tools Das Bruce's Mapconv frontend]

These tools have been compiled into a zip available here: [http://springfiles.com/spring/tools/mapping-tools http://springfiles.com/spring/tools/mapping-tools]

Keep in mind that mapconv is still being developed, so it may be necessary to update the included Mapconv to a later version, located here: [http://springrts.com/phpbb/viewtopic.php?f=56&t=21458 http://springrts.com/phpbb/viewtopic.php?f=56&t=21458]

= The Components of a Map =

== Texture Map ==

<code>'''Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps mus be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).'''</code>

This guide assumes that you understand how to make a texture map and it also assumes that you know how to use terrain generation software.

Commonly used terrain generation programs are:

Spring Map Edit (Does not work on 64bit machines)

L3DT

WorldMachine

Bryce3D

Carrara

Example Texture Map (generated by Carrara):

[[File:exampletexturemap.jpg]]

== Heightmap ==

<code>'''Height Maps are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

You will need a good image editing program to make heightmaps. Many of the aforementioned terrain generation programs will also generate heightmaps as well, but you can draw them by hand. They can be either 8bit or 16bit greyscale PNG. If you have photoshop or the gimp, you can use these programs to help you create your heightmap.

Here is an example of a 16bit heightmap:

[[File:Heightmapexample.png]]

Heightmaps work upon the idea of height according to color values. Black is the lowest, white is the heighest. In spring mapping, the waterline is defined by a negative height value. In other words, you define the heights of the map,  anything below 0 is under water. So on this heightmap, you might use -50 for the lowest value and 300 for the highest height value. The aforementioned tool "Mapconv Gui (a.k.a Das Bruce's MapConv Gui) has a waterline calculator that will help you calculate the correct waterline for your map.

== Metal Map ==

<code>'''Metal Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

In Spring, metal maps are used for the built in resourcing scheme (Metal/Energy). You do not have to use this scheme. In fact, there are several games for Spring who use their own resourcing systems added on using Lua. If you are creating this map for one of those games, a metal map is not strictly necessary (in other words you can just us a black image), however, it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.

Metalmaps show metal areas on a map based upon the amount of red on the image (make sure red is the only color used!). On this map you can see that the "Patch Technique" is used, which is pretty common among spring maps, but you are not limited to using this scheme.

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

Example Metal Map:

[[File:Examplemetal.jpg]]

== Feature Map ==

This part is easy...

'''DO NOT USE THIS FOR ANY REASON WHATSOEVER!!!''' Just use a flat black image for the featuremap.

<code>'''Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024'''</code>

Feature maps used to be quite complicated, but all that changed with the advent of Smoth's FeaturePlacer (short featuremap history below).

Now featuremaps are use simply for the purpose of placing grass. Grass coverage is defined by blue pixels on the feature map. The more blue the pixel is (the closer to blue 255 it is), the thicker grass will be at that location. Grass is entirely optional, but can be customized via map parameters and adds a nice touch to your map.

Example Feature Map:

[[File:examplefeature.jpg]]

=== A brief history of featuremaps ===

Feature maps were (and still are) a single RGB image where features such as grass, geothermal vents and trees, as well as structures, etc were "placed" using pixels on the image. This method was extremely imprecise and involved recompiling the map many times in order to simply move a tree from one location to another.

= Compiling a Map (MapConv) =

== Texture Specifications ==

Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps must be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).

Height Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025

Metal Map dimensions are Texture Map size / 16 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 16 = 512x512

Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024

== Using MapConv ==

[[MapConv]] is a command line program that is generally started via a batch file .

Below is an example set of parameters given to mapconv:

<code>'''MapConv -i -l -c 0 -x 101 -n 100 -o EvoRTS-Craggy_Creek-v01.smf -t terrain.png -a height6.png -m metal.png -f feature.png -z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file"'''</code>

Once compiled, you will get 2 new files: <mapname.smt> and <mapname.smf>

= Utilizing Blueprint =

Unzip the blueprint archive into your Spring Maps folder.

[[File:mapcontainer.jpg]]

You will notice a new folder called "mapcontainer.sdd". The .sdd ending on the folder name is very important for testing as <foldername>.sdd tells spring to load map files from that folder. This way you can work on your maps without having to zip them up over and over again.

== mapcontainer.sdd ==

Inside the map container folder you have the following file/folder structure.

<div>'''<code>LuaGaia</code>'''</div><div>'''<code>mapconfig</code>'''</div><div>'''<code>maphelper</code>'''</div><div>'''<code>maps</code>'''</div><div>'''<code>mapinfo.lua</code>'''</div><div>'''<code>mapoptions.lua</code>'''</div><div><br/></div>
Now, copy your compiled map files (the <code>.smt</code> and <code>.smf</code> files) into the "maps" folder.

= Texture Splatting using SSMF =

SSMF mapping is adding detail textures all over the map based upon specified distribution areas. This will make your map infinitely more detailed and beautiful.

Adding SSMF to a map consists of the following steps:

== Distribution Map ==

The Distribution map is essentially an atlas telling spring where to spread your detail textures. Lets have a look at an example distribution map:

http://www.evolutionrts.info/random/examplesplatdistribution.jpg

Each channel corresponds to a different texture referenced in the detail texture map. These areas are set using the channels of the image and are generally saved using the Targa format ( .tga ), sized at 1024x1024.

http://www.evolutionrts.info/random/examplechannels.jpg

Save your distribution map as splatdistribution.tga, and place it in the maps folder alongside the smf and smt files.

Once you have your distribution map, you need to set up your detail textures

== Detail Textures ==

Detail textures are made by adding a texture to each channel of an image.

http://www.evolutionrts.info/random/examplesplattex.jpg

There are a total of 4 texture slots available. One for R, G, B, and one for the Alpha Channel. When you have your detail textures ready, save the file as splattex.tga (Targa - 1024x1024) and place it in the maps folder alongside splatdistribution.tga

== Specular Map ==

A specular map controls brightness and "shinyness" of your map. The more light you add to a particular portion of your specular map, the brighter and more reflective that portion of the map will be. Specular maps should be 1024x1024 and saved as specularmap.bmp. Of course placed in the maps folder with the other ssmf maps.

A specular map can cause your map to look like molten plastic. Most of us don't really use specular maps except for certain circumstances.

http://www.evolutionrts.info/random/examplespecularmap.jpg

== Grass Shading Map ==
By default spring's grass pulls the minimap to use for coloration of the grass patches. You can override this with ''grassShadingTex''. Below is an example

<table><tr><td colspan="2">Grass map</td><td>Grass map in game</td></tr>
<tr><td>[[File:Grassmap_Map_example.jpegâ€Ž|120px|alt=grassmap example |grassmap]]</td><td>This is a section of grassmap image. This image applied to the entire map which determines the color of grass.</td><td>[[File:Grassmap_Map_ingame.jpgâ€Ž|300px|alt=grassmapp applied in game|in game]]</td></tr><tr><td colspan="2">Click image for larger picture</td><td>Click image for larger picture</td></tr></table>

== Normal Map ==

Normal maps (in this case) are used to add "fake" 3d detail to a flat 2d image. It is a technique of manipulating lighting to give the appearance of looking at a 3d object, when actually it is just 2D.

This is what a normal map looks like:
[[File:examplenormalmap.jpg]]

= Placing Features =

As previously mentioned, features can now be placed via LUA based upon a coordinate system that looks similar to this:

<div><code>local features = { </code></div>
<div><code> unitlist = {</code></div>
<div><code> },</code></div>
<div><code> buildinglist = {</code></div>
<div><code> },</code></div>
<div><code> objectlist = {</code></div>
<div><code> { name = 'btreeclo_4', x = 7760, z = 112, rot = "0" },</code></div>
<div><code> { name = 'btreea_3', x = 2520, z = 6904, rot = "0" },</code></div>
<div><code> { name = 'btreeblo_5', x = 7736, z = 536, rot = "0" },</code></div>
<div><code> { name = 'btreeclo_1', x = 2504, z = 7112, rot = "0" },</code></div>
<div><code> { name = 'geovent', x = 177, z = 192, rot = "0" },</code></div>
<div><code> },</code></div>
<div><code>},</code></div>
<div><code>return features</code></div>

<div>Of course, features can be placed by editing the set.lua file in a text editor, but that would take an extremely long time. Enter FeaturePlacer.</div><div><br/></div>
== Feature Placer ==

* [[Map Making: Feature Placer|Feature Placer]]

= Configuring Map Parameters (Mapinfo.lua) =

Admittedly, the default values used in blueprint mapinfo are awful. It may be wise for you to download another map that has used blueprint and copy and paste it's mapinfo contents into yours. However, you are also free to use the default or use the provided example.

In time, the mapinfo tags will be documented and this will like to that page. As it is the tags and values are pretty easy to figure out for the most part.

== MapInfo.lua ==
* [[Map_Making:mapinfo.lua|MapInfo.lua]]

= Skyboxes =

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

= Mutators =

Mutators are files that add new content to exiting game files. "[http://springfiles.com/spring/tools/spring-features Spring Features]" is an example of a mutator.

This section needs a proper description.

[http://springrts.com/phpbb/viewtopic.php?f=13&t=21808 http://springrts.com/phpbb/viewtopic.php?f=13&t=21808]

= Archiving a Map =

<div>Spring reads two different archive formats, 7zip and zip. Both archives are named sd7 and sdz, respectively. 7zip files are made by The 7zip archive program, available at [http://www.7-zip.org/ http://www.7-zip.org/]</div><div><br/></div><div>Navigate to your mapcontainer.sdd folder and zip it's contents into either a .7z file or .zip (7zip format is '''HIGHLY RECOMMENDED'''!), usually naming schemes follow the actual mapname (<mapname.sd7>, such as EvoRTS-Craggy_Creek-v08.sd7</div><div><br/></div><div>

<span style="color:red">'''Make sure that the archive is non-solid!''' </span>

[[File:examplearchivewith7zip.jpg]]<br/></div><div><br/></div><div>Once completed, copy the sd7/sdz file to your maps folder. At this point, be sure to remove the .sdd ending from your mapcontainer.sdd folder (or change the map name/version contained withing), otherwise you might get sync errors because spring is reading from the wrong archive source.</div>
<br/>

= Tools =

*[[Maps:SpringMapEdit|Frostregen's SpringMapEdit]]. 3D editing, Compiles and import SM2 directly. Beginner friendly but still powerful.
*[[MapConv]] Map converter program, compiles maps.
*[[MapConvNG]] Rewrite of MapConv that works on linux / 64 bit.
*[[Maps:Map Designer]] '''(Outdated, Deprecated)''' Hugh's 3D map designer. Splatting, heightmap editing, splat painting, SM3
*[http://www.springfiles.com/show_file.php?id=1679 Starting position creator]: Or you can always find out the hard way which x/y coordinates are good by starting spring and having a look at the mouse cursor coordinates.
*[http://code.google.com/p/conflictterra/source/browse/games/CT/luaui/widgets/tp_coordinate_help.lua Coordinate Helper widget] A small widget that helps you with finding coordinates ie for start positions. Every time you put down a marker it will log its position in [[Infolog.txt]] and also in MAPNAME_coordinates.txt Helpfull if you need to get lots of map coordinates and do not want to write them down by hand. (it writes SpawnResource in front of the coordinates but you can ignore or edit the widget)

= Minimal barebones template with no extras =
If you want a completely barebones template with no extra configuration needed (useful for testing), Extract the blueprint files, then delete everything except mapinfo.lua and everything in maps folder (except your .smf and .smt files). Next copy paste following to mapinfo.lua (not the most minimal but minimal enough):
<pre>
local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "",
modtype = 3, --// 3=map

teams = {
[0] = {startPos = {x = 8, z = 8}},
[1] = {startPos = {x = 16, z = 16}},
},
}
return mapinfo
</pre>
In summary: maps folder with .smf.and .smt files and single mapinfo.lua file. You should be now able to test your map immediately (if files are placed to mapcontainer.sdd).

[[Category:Tutorial]]
[[Category:Map making]]

Tutorial:MapDevWithBlueprint(Forb)

2016-11-18T01:33:02Z

Forboding angel: /* Feature Map */

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

= Getting Started (Tools) =

'''Blueprint: '''[https://github.com/jk3064/Map-Blueprint https://github.com/jk3064/Map-Blueprint] 

The only other tool really needed is "Mapconv". The other tools available are there simply to make your life easier. A list of common mapping tools are as follows:

[[MapConv|Mapconv]]

[[MapConvNG|MapConvNG - For use with Linux]]

SMFED '''(Deprecated, no longer useful)'''

Grout '''(Deprecated, no longer useful unless texture was generated with L3dt utilizing tiles)'''

SMD Creator '''(Deprecated, no longer useful)'''

[http://springfiles.com/spring/tools/mapping-tools Start Position Editor]

[http://springfiles.com/spring/tools/mapping-tools Das Bruce's Mapconv frontend]

These tools have been compiled into a zip available here: [http://springfiles.com/spring/tools/mapping-tools http://springfiles.com/spring/tools/mapping-tools]

Keep in mind that mapconv is still being developed, so it may be necessary to update the included Mapconv to a later version, located here: [http://springrts.com/phpbb/viewtopic.php?f=56&t=21458 http://springrts.com/phpbb/viewtopic.php?f=56&t=21458]

= The Components of a Map =

== Texture Map ==

<code>'''Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps mus be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).'''</code>

This guide assumes that you understand how to make a texture map and it also assumes that you know how to use terrain generation software.

Commonly used terrain generation programs are:

Spring Map Edit (Does not work on 64bit machines)

L3DT

WorldMachine

Bryce3D

Carrara

Example Texture Map (generated by Carrara):

[[File:exampletexturemap.jpg]]

== Heightmap ==

<code>'''Height Maps are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

You will need a good image editing program to make heightmaps. Many of the aforementioned terrain generation programs will also generate heightmaps as well, but you can draw them by hand. They can be either 8bit or 16bit greyscale PNG. If you have photoshop or the gimp, you can use these programs to help you create your heightmap.

Here is an example of a 16bit heightmap:

[[File:Heightmapexample.png]]

Heightmaps work upon the idea of height according to color values. Black is the lowest, white is the heighest. In spring mapping, the waterline is defined by a negative height value. In other words, you define the heights of the map,  anything below 0 is under water. So on this heightmap, you might use -50 for the lowest value and 300 for the highest height value. The aforementioned tool "Mapconv Gui (a.k.a Das Bruce's MapConv Gui) has a waterline calculator that will help you calculate the correct waterline for your map.

== Metal Map ==

<code>'''Metal Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

In Spring, metal maps are used for the built in resourcing scheme (Metal/Energy). You do not have to use this scheme. In fact, there are several games for Spring who use their own resourcing systems added on using Lua. If you are creating this map for one of those games, a metal map is not strictly necessary (in other words you can just us a black image), however, it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.

Metalmaps show metal areas on a map based upon the amount of red on the image (make sure red is the only color used!). On this map you can see that the "Patch Technique" is used, which is pretty common among spring maps, but you are not limited to using this scheme.

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

Example Metal Map:

[[File:Examplemetal.jpg]]

== Feature Map ==

This part is easy...

'''DO NOT USE THIS FOR ANY REASON WHATSOEVER!!!''' Just use a flat black image for the featuremap.

<code>'''Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024'''</code>

Feature maps used to be quite complicated, but all that changed with the advent of Smoth's FeaturePlacer (short featuremap history below).

Now featuremaps are use simply for the purpose of placing grass. Grass coverage is defined by blue pixels on the feature map. The more blue the pixel is (the closer to blue 255 it is), the thicker grass will be at that location. Grass is entirely optional, but can be customized via map parameters and adds a nice touch to your map.

Example Feature Map:

[[File:examplefeature.jpg]]

=== A brief history of featuremaps ===

Feature maps were (and still are) a single RGB image where features such as grass, geothermal vents and trees, as well as structures, etc were "placed" using pixels on the image. This method was extremely imprecise and involved recompiling the map many times in order to simply move a tree from one location to another.

= Compiling a Map (MapConv) =

== Texture Specifications ==

Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps must be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).

Height Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025

Metal Map dimensions are Texture Map size / 16 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 16 = 512x512

Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024

== Using MapConv ==

[[MapConv]] is a command line program that is generally started via a batch file .

Below is an example set of parameters given to mapconv:

<code>'''MapConv -i -l -c 0 -x 101 -n 100 -o EvoRTS-Craggy_Creek-v01.smf -t terrain.png -a height6.png -m metal.png -f feature.png -z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file"'''</code>

Once compiled, you will get 2 new files: <mapname.smt> and <mapname.smf>

= Utilizing Blueprint =

Unzip the blueprint archive into your Spring Maps folder.

[[File:mapcontainer.jpg]]

You will notice a new folder called "mapcontainer.sdd". The .sdd ending on the folder name is very important for testing as <foldername>.sdd tells spring to load map files from that folder. This way you can work on your maps without having to zip them up over and over again.

== mapcontainer.sdd ==

Inside the map container folder you have the following file/folder structure.

<div>'''<code>LuaGaia</code>'''</div><div>'''<code>mapconfig</code>'''</div><div>'''<code>maphelper</code>'''</div><div>'''<code>maps</code>'''</div><div>'''<code>mapinfo.lua</code>'''</div><div>'''<code>mapoptions.lua</code>'''</div><div><br/></div>
Now, copy your compiled map files (the <code>.smt</code> and <code>.smf</code> files) into the "maps" folder.

= Texture Splatting using SSMF =

SSMF mapping is adding detail textures all over the map based upon specified distribution areas. This will make your map infinitely more detailed and beautiful.

Adding SSMF to a map consists of the following steps:

== Distribution Map ==

The Distribution map is essentially an atlas telling spring where to spread your detail textures. Lets have a look at an example distribution map:

http://www.evolutionrts.info/random/examplesplatdistribution.jpg

Each channel corresponds to a different texture referenced in the detail texture map. These areas are set using the channels of the image and are generally saved using the Targa format ( .tga ), sized at 1024x1024.

http://www.evolutionrts.info/random/examplechannels.jpg

Save your distribution map as splatdistribution.tga, and place it in the maps folder alongside the smf and smt files.

Once you have your distribution map, you need to set up your detail textures

== Detail Textures ==

Detail textures are made by adding a texture to each channel of an image.

http://www.evolutionrts.info/random/examplesplattex.jpg

There are a total of 4 texture slots available. One for R, G, B, and one for the Alpha Channel. When you have your detail textures ready, save the file as splattex.tga (Targa - 1024x1024) and place it in the maps folder alongside splatdistribution.tga

== Specular Map ==

A specular map controls brightness and "shinyness" of your map. The more light you add to a particular portion of your specular map, the brighter and more reflective that portion of the map will be. Specular maps should be 1024x1024 and saved as specularmap.bmp. Of course placed in the maps folder with the other ssmf maps.

http://www.evolutionrts.info/random/examplespecularmap.jpg

== Grass Shading Map ==
By default spring's grass pulls the minimap to use for coloration of the grass patches. You can override this with ''grassShadingTex''. Below is an example

<table><tr><td colspan="2">Grass map</td><td>Grass map in game</td></tr>
<tr><td>[[File:Grassmap_Map_example.jpegâ€Ž|120px|alt=grassmap example |grassmap]]</td><td>This is a section of grassmap image. This image applied to the entire map which determines the color of grass.</td><td>[[File:Grassmap_Map_ingame.jpgâ€Ž|300px|alt=grassmapp applied in game|in game]]</td></tr><tr><td colspan="2">Click image for larger picture</td><td>Click image for larger picture</td></tr></table>

== Normal Map ==

Normal maps (in this case) are used to add "fake" 3d detail to a flat 2d image. It is a technique of manipulating lighting to give the appearance of looking at a 3d object, when actually it is just 2D.

This is what a normal map looks like:
[[File:examplenormalmap.jpg]]

= Placing Features =

As previously mentioned, features can now be placed via LUA based upon a coordinate system that looks similar to this:

<div><code>local features = { </code></div>
<div><code> unitlist = {</code></div>
<div><code> },</code></div>
<div><code> buildinglist = {</code></div>
<div><code> },</code></div>
<div><code> objectlist = {</code></div>
<div><code> { name = 'btreeclo_4', x = 7760, z = 112, rot = "0" },</code></div>
<div><code> { name = 'btreea_3', x = 2520, z = 6904, rot = "0" },</code></div>
<div><code> { name = 'btreeblo_5', x = 7736, z = 536, rot = "0" },</code></div>
<div><code> { name = 'btreeclo_1', x = 2504, z = 7112, rot = "0" },</code></div>
<div><code> { name = 'geovent', x = 177, z = 192, rot = "0" },</code></div>
<div><code> },</code></div>
<div><code>},</code></div>
<div><code>return features</code></div>

<div>Of course, features can be placed by editing the set.lua file in a text editor, but that would take an extremely long time. Enter FeaturePlacer.</div><div><br/></div>
== Feature Placer ==

* [[Map Making: Feature Placer|Feature Placer]]

= Configuring Map Parameters (Mapinfo.lua) =

Admittedly, the default values used in blueprint mapinfo are awful. It may be wise for you to download another map that has used blueprint and copy and paste it's mapinfo contents into yours. However, you are also free to use the default or use the provided example.

In time, the mapinfo tags will be documented and this will like to that page. As it is the tags and values are pretty easy to figure out for the most part.

== MapInfo.lua ==
* [[Map_Making:mapinfo.lua|MapInfo.lua]]

= Skyboxes =

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

= Mutators =

Mutators are files that add new content to exiting game files. "[http://springfiles.com/spring/tools/spring-features Spring Features]" is an example of a mutator.

This section needs a proper description.

[http://springrts.com/phpbb/viewtopic.php?f=13&t=21808 http://springrts.com/phpbb/viewtopic.php?f=13&t=21808]

= Archiving a Map =

<div>Spring reads two different archive formats, 7zip and zip. Both archives are named sd7 and sdz, respectively. 7zip files are made by The 7zip archive program, available at [http://www.7-zip.org/ http://www.7-zip.org/]</div><div><br/></div><div>Navigate to your mapcontainer.sdd folder and zip it's contents into either a .7z file or .zip (7zip format is '''HIGHLY RECOMMENDED'''!), usually naming schemes follow the actual mapname (<mapname.sd7>, such as EvoRTS-Craggy_Creek-v08.sd7</div><div><br/></div><div>

<span style="color:red">'''Make sure that the archive is non-solid!''' </span>

[[File:examplearchivewith7zip.jpg]]<br/></div><div><br/></div><div>Once completed, copy the sd7/sdz file to your maps folder. At this point, be sure to remove the .sdd ending from your mapcontainer.sdd folder (or change the map name/version contained withing), otherwise you might get sync errors because spring is reading from the wrong archive source.</div>
<br/>

= Tools =

*[[Maps:SpringMapEdit|Frostregen's SpringMapEdit]]. 3D editing, Compiles and import SM2 directly. Beginner friendly but still powerful.
*[[MapConv]] Map converter program, compiles maps.
*[[MapConvNG]] Rewrite of MapConv that works on linux / 64 bit.
*[[Maps:Map Designer]] '''(Outdated, Deprecated)''' Hugh's 3D map designer. Splatting, heightmap editing, splat painting, SM3
*[http://www.springfiles.com/show_file.php?id=1679 Starting position creator]: Or you can always find out the hard way which x/y coordinates are good by starting spring and having a look at the mouse cursor coordinates.
*[http://code.google.com/p/conflictterra/source/browse/games/CT/luaui/widgets/tp_coordinate_help.lua Coordinate Helper widget] A small widget that helps you with finding coordinates ie for start positions. Every time you put down a marker it will log its position in [[Infolog.txt]] and also in MAPNAME_coordinates.txt Helpfull if you need to get lots of map coordinates and do not want to write them down by hand. (it writes SpawnResource in front of the coordinates but you can ignore or edit the widget)

= Minimal barebones template with no extras =
If you want a completely barebones template with no extra configuration needed (useful for testing), Extract the blueprint files, then delete everything except mapinfo.lua and everything in maps folder (except your .smf and .smt files). Next copy paste following to mapinfo.lua (not the most minimal but minimal enough):
<pre>
local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "",
modtype = 3, --// 3=map

teams = {
[0] = {startPos = {x = 8, z = 8}},
[1] = {startPos = {x = 16, z = 16}},
},
}
return mapinfo
</pre>
In summary: maps folder with .smf.and .smt files and single mapinfo.lua file. You should be now able to test your map immediately (if files are placed to mapcontainer.sdd).

[[Category:Tutorial]]
[[Category:Map making]]

Tutorial:MapDevWithBlueprint(Forb)

2016-11-18T01:32:18Z

Forboding angel: /* Feature Map */

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

= Getting Started (Tools) =

'''Blueprint: '''[https://github.com/jk3064/Map-Blueprint https://github.com/jk3064/Map-Blueprint] 

The only other tool really needed is "Mapconv". The other tools available are there simply to make your life easier. A list of common mapping tools are as follows:

[[MapConv|Mapconv]]

[[MapConvNG|MapConvNG - For use with Linux]]

SMFED '''(Deprecated, no longer useful)'''

Grout '''(Deprecated, no longer useful unless texture was generated with L3dt utilizing tiles)'''

SMD Creator '''(Deprecated, no longer useful)'''

[http://springfiles.com/spring/tools/mapping-tools Start Position Editor]

[http://springfiles.com/spring/tools/mapping-tools Das Bruce's Mapconv frontend]

These tools have been compiled into a zip available here: [http://springfiles.com/spring/tools/mapping-tools http://springfiles.com/spring/tools/mapping-tools]

Keep in mind that mapconv is still being developed, so it may be necessary to update the included Mapconv to a later version, located here: [http://springrts.com/phpbb/viewtopic.php?f=56&t=21458 http://springrts.com/phpbb/viewtopic.php?f=56&t=21458]

= The Components of a Map =

== Texture Map ==

<code>'''Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps mus be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).'''</code>

This guide assumes that you understand how to make a texture map and it also assumes that you know how to use terrain generation software.

Commonly used terrain generation programs are:

Spring Map Edit (Does not work on 64bit machines)

L3DT

WorldMachine

Bryce3D

Carrara

Example Texture Map (generated by Carrara):

[[File:exampletexturemap.jpg]]

== Heightmap ==

<code>'''Height Maps are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

You will need a good image editing program to make heightmaps. Many of the aforementioned terrain generation programs will also generate heightmaps as well, but you can draw them by hand. They can be either 8bit or 16bit greyscale PNG. If you have photoshop or the gimp, you can use these programs to help you create your heightmap.

Here is an example of a 16bit heightmap:

[[File:Heightmapexample.png]]

Heightmaps work upon the idea of height according to color values. Black is the lowest, white is the heighest. In spring mapping, the waterline is defined by a negative height value. In other words, you define the heights of the map,  anything below 0 is under water. So on this heightmap, you might use -50 for the lowest value and 300 for the highest height value. The aforementioned tool "Mapconv Gui (a.k.a Das Bruce's MapConv Gui) has a waterline calculator that will help you calculate the correct waterline for your map.

== Metal Map ==

<code>'''Metal Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

In Spring, metal maps are used for the built in resourcing scheme (Metal/Energy). You do not have to use this scheme. In fact, there are several games for Spring who use their own resourcing systems added on using Lua. If you are creating this map for one of those games, a metal map is not strictly necessary (in other words you can just us a black image), however, it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.

Metalmaps show metal areas on a map based upon the amount of red on the image (make sure red is the only color used!). On this map you can see that the "Patch Technique" is used, which is pretty common among spring maps, but you are not limited to using this scheme.

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

Example Metal Map:

[[File:Examplemetal.jpg]]

== Feature Map ==

This part is easy...

'''DO NOT USE THIS FOR ANY REASON WHATSOEVER!!!'''

<code>'''Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024'''</code>

Feature maps used to be quite complicated, but all that changed with the advent of Smoth's FeaturePlacer (short featuremap history below).

Now featuremaps are use simply for the purpose of placing grass. Grass coverage is defined by blue pixels on the feature map. The more blue the pixel is (the closer to blue 255 it is), the thicker grass will be at that location. Grass is entirely optional, but can be customized via map parameters and adds a nice touch to your map.

Example Feature Map:

[[File:examplefeature.jpg]]

=== A brief history of featuremaps ===

Feature maps were (and still are) a single RGB image where features such as grass, geothermal vents and trees, as well as structures, etc were "placed" using pixels on the image. This method was extremely imprecise and involved recompiling the map many times in order to simply move a tree from one location to another.

= Compiling a Map (MapConv) =

== Texture Specifications ==

Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps must be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).

Height Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025

Metal Map dimensions are Texture Map size / 16 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 16 = 512x512

Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024

== Using MapConv ==

[[MapConv]] is a command line program that is generally started via a batch file .

Below is an example set of parameters given to mapconv:

<code>'''MapConv -i -l -c 0 -x 101 -n 100 -o EvoRTS-Craggy_Creek-v01.smf -t terrain.png -a height6.png -m metal.png -f feature.png -z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file"'''</code>

Once compiled, you will get 2 new files: <mapname.smt> and <mapname.smf>

= Utilizing Blueprint =

Unzip the blueprint archive into your Spring Maps folder.

[[File:mapcontainer.jpg]]

You will notice a new folder called "mapcontainer.sdd". The .sdd ending on the folder name is very important for testing as <foldername>.sdd tells spring to load map files from that folder. This way you can work on your maps without having to zip them up over and over again.

== mapcontainer.sdd ==

Inside the map container folder you have the following file/folder structure.

<div>'''<code>LuaGaia</code>'''</div><div>'''<code>mapconfig</code>'''</div><div>'''<code>maphelper</code>'''</div><div>'''<code>maps</code>'''</div><div>'''<code>mapinfo.lua</code>'''</div><div>'''<code>mapoptions.lua</code>'''</div><div><br/></div>
Now, copy your compiled map files (the <code>.smt</code> and <code>.smf</code> files) into the "maps" folder.

= Texture Splatting using SSMF =

SSMF mapping is adding detail textures all over the map based upon specified distribution areas. This will make your map infinitely more detailed and beautiful.

Adding SSMF to a map consists of the following steps:

== Distribution Map ==

The Distribution map is essentially an atlas telling spring where to spread your detail textures. Lets have a look at an example distribution map:

http://www.evolutionrts.info/random/examplesplatdistribution.jpg

Each channel corresponds to a different texture referenced in the detail texture map. These areas are set using the channels of the image and are generally saved using the Targa format ( .tga ), sized at 1024x1024.

http://www.evolutionrts.info/random/examplechannels.jpg

Save your distribution map as splatdistribution.tga, and place it in the maps folder alongside the smf and smt files.

Once you have your distribution map, you need to set up your detail textures

== Detail Textures ==

Detail textures are made by adding a texture to each channel of an image.

http://www.evolutionrts.info/random/examplesplattex.jpg

There are a total of 4 texture slots available. One for R, G, B, and one for the Alpha Channel. When you have your detail textures ready, save the file as splattex.tga (Targa - 1024x1024) and place it in the maps folder alongside splatdistribution.tga

== Specular Map ==

A specular map controls brightness and "shinyness" of your map. The more light you add to a particular portion of your specular map, the brighter and more reflective that portion of the map will be. Specular maps should be 1024x1024 and saved as specularmap.bmp. Of course placed in the maps folder with the other ssmf maps.

http://www.evolutionrts.info/random/examplespecularmap.jpg

== Grass Shading Map ==
By default spring's grass pulls the minimap to use for coloration of the grass patches. You can override this with ''grassShadingTex''. Below is an example

<table><tr><td colspan="2">Grass map</td><td>Grass map in game</td></tr>
<tr><td>[[File:Grassmap_Map_example.jpegâ€Ž|120px|alt=grassmap example |grassmap]]</td><td>This is a section of grassmap image. This image applied to the entire map which determines the color of grass.</td><td>[[File:Grassmap_Map_ingame.jpgâ€Ž|300px|alt=grassmapp applied in game|in game]]</td></tr><tr><td colspan="2">Click image for larger picture</td><td>Click image for larger picture</td></tr></table>

== Normal Map ==

Normal maps (in this case) are used to add "fake" 3d detail to a flat 2d image. It is a technique of manipulating lighting to give the appearance of looking at a 3d object, when actually it is just 2D.

This is what a normal map looks like:
[[File:examplenormalmap.jpg]]

= Placing Features =

As previously mentioned, features can now be placed via LUA based upon a coordinate system that looks similar to this:

<div><code>local features = { </code></div>
<div><code> unitlist = {</code></div>
<div><code> },</code></div>
<div><code> buildinglist = {</code></div>
<div><code> },</code></div>
<div><code> objectlist = {</code></div>
<div><code> { name = 'btreeclo_4', x = 7760, z = 112, rot = "0" },</code></div>
<div><code> { name = 'btreea_3', x = 2520, z = 6904, rot = "0" },</code></div>
<div><code> { name = 'btreeblo_5', x = 7736, z = 536, rot = "0" },</code></div>
<div><code> { name = 'btreeclo_1', x = 2504, z = 7112, rot = "0" },</code></div>
<div><code> { name = 'geovent', x = 177, z = 192, rot = "0" },</code></div>
<div><code> },</code></div>
<div><code>},</code></div>
<div><code>return features</code></div>

<div>Of course, features can be placed by editing the set.lua file in a text editor, but that would take an extremely long time. Enter FeaturePlacer.</div><div><br/></div>
== Feature Placer ==

* [[Map Making: Feature Placer|Feature Placer]]

= Configuring Map Parameters (Mapinfo.lua) =

Admittedly, the default values used in blueprint mapinfo are awful. It may be wise for you to download another map that has used blueprint and copy and paste it's mapinfo contents into yours. However, you are also free to use the default or use the provided example.

In time, the mapinfo tags will be documented and this will like to that page. As it is the tags and values are pretty easy to figure out for the most part.

== MapInfo.lua ==
* [[Map_Making:mapinfo.lua|MapInfo.lua]]

= Skyboxes =

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

= Mutators =

Mutators are files that add new content to exiting game files. "[http://springfiles.com/spring/tools/spring-features Spring Features]" is an example of a mutator.

This section needs a proper description.

[http://springrts.com/phpbb/viewtopic.php?f=13&t=21808 http://springrts.com/phpbb/viewtopic.php?f=13&t=21808]

= Archiving a Map =

<div>Spring reads two different archive formats, 7zip and zip. Both archives are named sd7 and sdz, respectively. 7zip files are made by The 7zip archive program, available at [http://www.7-zip.org/ http://www.7-zip.org/]</div><div><br/></div><div>Navigate to your mapcontainer.sdd folder and zip it's contents into either a .7z file or .zip (7zip format is '''HIGHLY RECOMMENDED'''!), usually naming schemes follow the actual mapname (<mapname.sd7>, such as EvoRTS-Craggy_Creek-v08.sd7</div><div><br/></div><div>

<span style="color:red">'''Make sure that the archive is non-solid!''' </span>

[[File:examplearchivewith7zip.jpg]]<br/></div><div><br/></div><div>Once completed, copy the sd7/sdz file to your maps folder. At this point, be sure to remove the .sdd ending from your mapcontainer.sdd folder (or change the map name/version contained withing), otherwise you might get sync errors because spring is reading from the wrong archive source.</div>
<br/>

= Tools =

*[[Maps:SpringMapEdit|Frostregen's SpringMapEdit]]. 3D editing, Compiles and import SM2 directly. Beginner friendly but still powerful.
*[[MapConv]] Map converter program, compiles maps.
*[[MapConvNG]] Rewrite of MapConv that works on linux / 64 bit.
*[[Maps:Map Designer]] '''(Outdated, Deprecated)''' Hugh's 3D map designer. Splatting, heightmap editing, splat painting, SM3
*[http://www.springfiles.com/show_file.php?id=1679 Starting position creator]: Or you can always find out the hard way which x/y coordinates are good by starting spring and having a look at the mouse cursor coordinates.
*[http://code.google.com/p/conflictterra/source/browse/games/CT/luaui/widgets/tp_coordinate_help.lua Coordinate Helper widget] A small widget that helps you with finding coordinates ie for start positions. Every time you put down a marker it will log its position in [[Infolog.txt]] and also in MAPNAME_coordinates.txt Helpfull if you need to get lots of map coordinates and do not want to write them down by hand. (it writes SpawnResource in front of the coordinates but you can ignore or edit the widget)

= Minimal barebones template with no extras =
If you want a completely barebones template with no extra configuration needed (useful for testing), Extract the blueprint files, then delete everything except mapinfo.lua and everything in maps folder (except your .smf and .smt files). Next copy paste following to mapinfo.lua (not the most minimal but minimal enough):
<pre>
local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "",
modtype = 3, --// 3=map

teams = {
[0] = {startPos = {x = 8, z = 8}},
[1] = {startPos = {x = 16, z = 16}},
},
}
return mapinfo
</pre>
In summary: maps folder with .smf.and .smt files and single mapinfo.lua file. You should be now able to test your map immediately (if files are placed to mapcontainer.sdd).

[[Category:Tutorial]]
[[Category:Map making]]

Lua SyncedRead

2016-05-25T02:33:54Z

Forboding angel:

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''Spring.ENEMY_UNITS'''

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

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

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

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

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

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

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

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

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

! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition:<br><br>
<font color="#55ee99">"if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end"</font><br>
not only:<br>
<span class="warning">"if (Spring.GetModOptions.exampleOption) then...end"</span>

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

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

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

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

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

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }
<font color="#55ee99">
plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0
</font>

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

<span class="note">Post 95.0 this no longer returns neutral units</span>

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

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

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

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

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

'''Spring.GetUnitBasePosition''' <span class="warning">Deprecated in 89.0, use GetUnitPosition</span>
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
<span class="note">returns the direction vector</span>

'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
<span class="note">returns heading directions used in COB scripts</span>

'''Spring.GetUnitRotation''' {{New|95.0}}
(number unitID) --> nil | number pitch, number yaw, number roll
<span class="note">Marked as (WIP) in changelog</span>

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

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

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

==== Unit Weapon Informations ====
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
<span class=note>`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"</span>

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

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

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

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

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

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

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

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

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

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

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
<font color="#55ee99">Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want move a piece to another piece.</font>

'''Spring.GetUnitPieceDirection''' <font color="red">Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir</font>
( number unitID, number piece ) -> number dirx, number diry, number dirz
'''Spring.GetUnitPieceMatrix'''
( number unitID, number piece ) -> { [1] = number, ... , [16] = number }
'''Spring.GetUnitPieceList'''
( number unitID ) -> { [1] = string "piecename", ... , [pieceNumN] = string "piecename" }
'''Spring.GetUnitPieceMap'''
( number unitID ) -> { "piecename1" = pieceNum1, ... , "piecenameN" = pieceNumN }
'''Spring.GetUnitPieceInfo'''
( number unitID, number piece ) -> {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}
"parent" field {{New|95.0}}

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

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

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
<font color="#55ee99">Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.</font>

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

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

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

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

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

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

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

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
<span class="note">since 89.0, returns the base (default), middle or aim position of the feature.</span>

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

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

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

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

== Ground ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>

'''Spring.GetGroundHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundOrigHeight'''
( number x, number z ) -> number y
'''Spring.GetGroundNormal'''
( number x, number z [, smoothedNormal] ) -> number x, number y, number z, number slope
{{new|100.0}}<span class="warning">: smoothedNormal and slope</span>

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

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

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

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

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

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

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

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

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

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

'''Spring.GetClosestValidPosition''' <span class="warning">//NOT FINISHED YET</span>
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

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

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

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

'''Spring.GetProjectileDefID'''
(number projectileID) -> nil | number weaponDefID
<span class=note>using this to get a weaponDefID is HIGHLY preferred <br/> to indexing WeaponDefNames via GetProjectileName<span>

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

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

<span class=note>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
</span>
'''Spring.GetProjectileIntercepted''' {{new|99.0}}
( number projectileID ) -> nil | boolean isBeingIntercepted

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

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

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

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

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

'''Spring.GetProjectileSpinAngle''' <span class="warning">Deprecated in 95.0</span>
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed''' <span class="warning">Deprecated in 95.0</span>
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec''' <span class="warning">Deprecated in 95.0</span>
( number projectileID ) -> nil | number x, number y, number z

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

[[category: Lua]]

EvoGreenLitFAQ

2016-04-07T20:55:29Z

Forboding angel: Blanked the page

Rapid Tags

2015-07-04T04:10:32Z

Forboding angel:

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

[[Category:Download Systems]]

Rapid Tags

2015-07-04T04:10:06Z

Forboding angel:

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

[[Category:Download Systems]]

Associated Development Groups

2015-04-18T05:18:14Z

Forboding angel:

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

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

= Websites =
== Games ==
=== Balanced Annhiliation ===
*[https://springrts.com/phpbb/viewforum.php?f=44 Balanced Annihilation] forum

=== Evolution RTS ===

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

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

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

=== Zero-K ===
*[http://www.zero-k.info Zero-K.info] - Official Website & Forums

== Misc ==
*[http://www.moddb.com/engines/spring/ Spring on moddb.com]
*[http://answers.springlobby.info/ Spring Q&A Forum]
*[http://springlobby.info/ SpringLobby's Redmine] - The SpringLobby group is the biggest collaborative lobby client work in the Spring community. This is their project's homepage, containing bug tracker and helpful information on their wiki.
*[http://www.smoth.net/phpBB3/ Smoth's Development Forum] - the forum for the games Gundam RTS, Expand and Exterminate, Kernel Panic.
*[http://www.irit.fr/ProgAndPlay/index_en.php Prog&Play] - AI programming game/class using Spring and [[Kernel_Panic|Kernel Panic]]

= Lobby Channels =
'''#moddev''' - real game developers answer your questions

'''#lua''' - ask for help how to read tutorials

'''#sy''' - check back when the new enine will be released

= YouTube Channels =
A unsorted list of youtube accounts that uploaded at least some spring contest.

The amount, context and quality varies.

http://www.youtube.com/PROrANDY

http://www.youtube.com/SteveZissouSpring

http://www.youtube.com/xtaboi

http://www.youtube.com/ForbodingAngel

http://www.youtube.com/knorker

http://www.youtube.com/playlist?list=PL3C03292C49A62F81&feature=plcp (sabutai replay playlist )

http://www.youtube.com/omnianti0

http://www.youtube.com/user/rattle235/

http://www.youtube.com/user/jazcash

http://www.youtube.com/user/Cuntipede

http://www.youtube.com/user/Ruwetuin

http://www.youtube.com/user/xtaboi

http://www.youtube.com/user/kile4568

http://www.youtube.com/user/Canonfudder

http://www.youtube.com/user/wagonrepairer

http://www.youtube.com/user/xenoargh

http://www.youtube.com/user/smoth7

http://www.youtube.com/user/OpenMachines

http://www.youtube.com/user/XHC#p/ur

http://www.youtube.com/user/Pendrokar#p/u

http://www.youtube.com/user/XtaReplay

http://www.youtube.com/user/Kleaut

http://www.youtube.com/user/kylelck

[http://www.youtube.com/playlist?list=PLOj_JX39U3OMuthcAPhuT9XcbZWoQaswZ Enetheru's channel] - primarily blender related terrain and feature creation.

https://www.youtube.com/user/gajop

[[Category: Development]]

Associated Development Groups

2015-04-18T05:17:54Z

Forboding angel:

[[Engine_Development|Development]] < {{FULLPAGENAME}}

There are numerous people and groups involved in the Spring project, from development to content creation. This is meant as a cumulative list of associated groups to ease communication between them.

= Websites =
== Games ==
=== Balanced Annhiliation ===
*[https://springrts.com/phpbb/viewforum.php?f=44 Balanced Annihilation] forum

=== Evolution RTS ===

*[http://www.evolutionrts.info/ www.evolutionrts.info] - Official Website & Forums
*[http://www.wiki.evolutionrts.info/ www.wiki.evolutionrts.info] - Evolution RTS Wiki (Game Manual/How to Play/Unit Guide/Etc)
*[https://plus.google.com/+EvolutionrtsInfo https://plus.google.com/+EvolutionrtsInfo] - Evolution RTS Google+ Page (development updates, twitter style)
*[http://www.source.evolutionrts.info/ www.source.evolutionrts.info] - Evolution RTS Source Code SVN Repository (Google Code)
*[http://www.bugs.evolutionrts.info/ www.bugs.evolutionrts.info] - Evolution RTS Bug Tracker
*[http://www.desura.com/games/evolution-rts www.desura.com/games/evolution-rts] - Evolution RTS on Desura

=== Imperial Winter ===
*[http://www.imperialwinter.com ImperialWinter.com] - Official Website & Forums

=== Spring: 1944 ===
*[http://www.spring1944.net Spring1944.net] - Official Website & Forums

=== Zero-K ===
*[http://www.zero-k.info Zero-K.info] - Official Website & Forums

== Misc ==
*[http://www.moddb.com/engines/spring/ Spring on moddb.com]
*[http://answers.springlobby.info/ Spring Q&A Forum]
*[http://springlobby.info/ SpringLobby's Redmine] - The SpringLobby group is the biggest collaborative lobby client work in the Spring community. This is their project's homepage, containing bug tracker and helpful information on their wiki.
*[http://www.smoth.net/phpBB3/ Smoth's Development Forum] - the forum for the games Gundam RTS, Expand and Exterminate, Kernel Panic.
*[http://www.irit.fr/ProgAndPlay/index_en.php Prog&Play] - AI programming game/class using Spring and [[Kernel_Panic|Kernel Panic]]

= Lobby Channels =
'''#moddev''' - real game developers answer your questions

'''#lua''' - ask for help how to read tutorials

'''#sy''' - check back when the new enine will be released

= YouTube Channels =
A unsorted list of youtube accounts that uploaded at least some spring contest.

The amount, context and quality varies.

http://www.youtube.com/PROrANDY

http://www.youtube.com/SteveZissouSpring

http://www.youtube.com/xtaboi

http://www.youtube.com/ForbodingAngel

http://www.youtube.com/knorker

http://www.youtube.com/playlist?list=PL3C03292C49A62F81&feature=plcp (sabutai replay playlist )

http://www.youtube.com/omnianti0

http://www.youtube.com/user/rattle235/

http://www.youtube.com/user/jazcash

http://www.youtube.com/user/Cuntipede

http://www.youtube.com/user/Ruwetuin

http://www.youtube.com/user/xtaboi

http://www.youtube.com/user/kile4568

http://www.youtube.com/user/Canonfudder

http://www.youtube.com/user/wagonrepairer

http://www.youtube.com/user/xenoargh

http://www.youtube.com/user/smoth7

http://www.youtube.com/user/OpenMachines

http://www.youtube.com/user/XHC#p/ur

http://www.youtube.com/user/Pendrokar#p/u

http://www.youtube.com/user/XtaReplay

http://www.youtube.com/user/Kleaut

http://www.youtube.com/user/kylelck

[http://www.youtube.com/playlist?list=PLOj_JX39U3OMuthcAPhuT9XcbZWoQaswZ Enetheru's channel] - primarily blender related terrain and feature creation.

https://www.youtube.com/user/gajop

[[Category: Development]]

EvoGreenLitFAQ

2014-04-18T03:57:54Z

Forboding angel:

__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.

==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 (<b>NOT</b> launch game directly) with engine 96.0 and the latest version of Evolution RTS you can find in the list.

==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/

==Engine download stuck at 100%==

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\

==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 <b>really absolutely</b> 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

EvoGreenLitFAQ

2014-04-17T03:26:02Z

Forboding angel: /* Why so many problems? */

__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.

==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 (<b>NOT</b> launch game directly) with engine 96.0 and the latest version of Evolution RTS you can find in the list.

==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/

==Engine download stuck at 100%==

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.

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\

==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 <b>really absolutely</b> 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

EvoGreenlitList

2014-04-16T20:15:38Z

Forboding angel: /* Soved */

List of most urgent problems currently preventing players from playing evo.

=Current=

==engine detection==

For <s>unknown reasons</s> http://code.google.com/p/springweblobby/wiki/EvoSteamBugs '''often does not work.'''

"stops at 100%"

"nothing happens"

or errors like http://springrts.com/phpbb/viewtopic.php?f=64&p=556182#p556131

=Addressed/Fixed=

==Maps==

===Solved===

A limited maplist was introduced, unsynced players are auto-specced.

The maps from maplist were added in the steam distribution in the operation dubbed "Preload", as well as the engine and pool/packages with the game.
--

Too much random map changes. Too much downloading, too much unsync = no games start.

Some commonly chosen maps are unplayable (space maps etc)

Solve: '''Maplist''' on ALL hosts.

Best only put ONE map so that players do not have to download much and can just play.
Map could be:
http://springfiles.com/spring/spring-maps/eye-horus-v2

Progress:
unsynced players are specced and can not delay gamestart but does not seem to help so much

==Singleplayer==

===Solved===

Preload.
--

Does not work with fresh install because there are no files.

One must first join a MP to download engine,map,mod.

Solve: '''Download files on login''' or something.

==empty room, use !lock==

===Solved===

Springie seems to work correctly now.
--

The common solution to select an empty autohost and then lock the room does not work:

Players need to be manually to use !lock command. The empty hosts are impossible to find because players randomly join&leave all the time. Even if you join an empty host, hardly does one have enough time to type !lock before another player joins.

==Bots, AIs==

===Solved===

Bot filter specific to evo was created.
--

Needs '''filter''' for add-bot menu. Only evo-compatible bots must be listed.
AAI is too often choosen because top of list but it does not work.

Solve:
If nessecarly hard-coded hack in lobby might be needed?
(real solution like implenting validAI.lua probally no time)

CarRepairer: Actually the REAL real solution is to remove AIs from the engine, which should have been done years ago like widgets. That would solve it for future versions only so a validAI list would be needed now of course.

The evo-AIs reportedly "do nothing."<br />
Under investigation at: http://springrts.com/phpbb/viewtopic.php?p=556029#p556029 <br />
Possible quick fix: play on metal maps (Trololo, Trench_Linked).<br />

EvoGreenLitFAQ

2014-04-09T23:22:01Z

Forboding angel: /* Download stuck at 100% */

__NOTOC__

'''EvolutionRTS emergency FAQ'''
----

'''Before you ask a question in chat, please see if it is already answered on this list.'''

==Singleplayer?==
There is a singleplayer tab but with a fresh install it will not work.
(Game files and engine are missing)

'''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. Afterwards you can select the evolutionRTS game in singleplayer menu, or stay in this battleroom and play. See below for adding bots.

==Automatic download of game files does not work==
NOTE: the GAME file.

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.

===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/

===Download stuck at 100%===
Close the lobby and start it again.

If that doesn't help, you can try this:
Download this file... http://springrts.com/dl/buildbot/default/master/96.0/win32/spring_96.0_minimal-portable.7z

Unzip the files into: Documents\My Games\Spring\weblobby\engine\96.0 (if this path doesn't exist, you should create it)

Start Lobby

==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 too 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]]
*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

EvoGreenLitFAQ

2014-04-09T08:22:05Z

Forboding angel:

__NOTOC__

'''EvolutionRTS emergency FAQ'''
----

'''Before you ask a question in chat, please see if it is already answered on this list.'''

==Singleplayer?==
There is a singleplayer tab but with a fresh install it will not work.
(Game files and engine are missing)

'''Solution:''' Join a multiplayer game.

The lobby will download the nessecary files. Afterwards you can select the evolutionRTS game in singleplayer menu.

==Automatic download of game files does not work==
NOTE: the GAME file.

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.

===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/

===Download stuck at 100%===
Close the lobby and start it again.

==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.

ALL OTHER AI BOTS DO NOT WORK! (they are meant for different spring games)

==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 too 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]]
*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 :)

Tutorial:MapDevWithBlueprint(Forb)

2014-02-24T21:52:06Z

Forboding angel: /* Texture Splatting using SSMF */

[[Engine Development|Development]] < {{FULLPAGENAME}}

= Getting Started (Tools) =

'''Blueprint: '''[https://github.com/jk3064/Map-Blueprint https://github.com/jk3064/Map-Blueprint] 

The only other tool really needed is "Mapconv". The other tools available are there simply to make your life easier. A list of common mapping tools are as follows:

[[MapConv|Mapconv]]

[[MapConvNG|MapConvNG - For use with Linux]]

SMFED '''(Deprecated, no longer useful)'''

Grout '''(Deprecated, no longer useful unless texture was generated with L3dt utilizing tiles)'''

SMD Creator '''(Deprecated, no longer useful)'''

[http://springfiles.com/spring/tools/mapping-tools Start Position Editor]

[http://springfiles.com/spring/tools/mapping-tools Das Bruce's Mapconv frontend]

These tools have been compiled into a zip available here: [http://springfiles.com/spring/tools/mapping-tools http://springfiles.com/spring/tools/mapping-tools]

Keep in mind that mapconv is still being developed, so it may be necessary to update the included Mapconv to a later version, located here: [http://springrts.com/phpbb/viewtopic.php?f=56&t=21458 http://springrts.com/phpbb/viewtopic.php?f=56&t=21458]

= The Components of a Map =

== Texture Map ==

<code>'''Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps mus be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).'''</code>

This guide assumes that you understand how to make a texture map and it also assumes that you know how to use terrain generation software.

Commonly used terrain generation programs are:

Spring Map Edit (Does not work on 64bit machines)

L3DT

WorldMachine

Bryce3D

Carrara

Example Texture Map (generated by Carrara):

[[File:exampletexturemap.jpg]]

== Heightmap ==

<code>'''Height Maps are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

You will need a good image editing program to make heightmaps. Many of the aforementioned terrain generation programs will also generate heightmaps as well, but you can draw them by hand. They can be either 8bit or 16bit greyscale PNG. If you have photoshop or the gimp, you can use these programs to help you create your heightmap.

Here is an example of a 16bit heightmap:

[[File:Heightmapexample.png]]

Heightmaps work upon the idea of height according to color values. Black is the lowest, white is the heighest. In spring mapping, the waterline is defined by a negative height value. In other words, you define the heights of the map,  anything below 0 is under water. So on this heightmap, you might use -50 for the lowest value and 300 for the highest height value. The aforementioned tool "Mapconv Gui (a.k.a Das Bruce's MapConv Gui) has a waterline calculator that will help you calculate the correct waterline for your map.

== Metal Map ==

<code>'''Metal Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

In Spring, metal maps are used for the built in resourcing scheme (Metal/Energy). You do not have to use this scheme. In fact, there are several games for Spring who use their own resourcing systems added on using Lua. If you are creating this map for one of those games, a metal map is not strictly necessary (in other words you can just us a black image), however, it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.

Metalmaps show metal areas on a map based upon the amount of red on the image (make sure red is the only color used!). On this map you can see that the "Patch Technique" is used, which is pretty common among spring maps, but you are not limited to using this scheme.

If you do want perfect metal patches, use a 6x6 pixel pencil in your image editor with a red value of 255. This combined with setting the "MaxMetal" tag in the definitions to 1, will result in a perfect 2.0 metal generation per patch (using Balanaced Annihilation values). The game use isn't the point however. The fact is that if you can predict how much each spot will output (typically), using the "MaxMetal" parameter, you can easily scale the values up and down. As an example of another extreme, Evolution RTS dictates that all metal patches will output 0.5 metal regardless of the map settings. So whether you need to put a lot of thought into your metal map values depends entirely upon the game for which you are creating the map.

Example Metal Map:

[[File:Examplemetal.jpg]]

== Feature Map ==

<code>'''Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024'''</code>

Feature maps used to be quite complicated, but all that changed with the advent of Smoth's FeaturePlacer (short featuremap history below).

Now featuremaps are use simply for the purpose of placing grass. Grass coverage is defined by blue pixels on the feature map. The more blue the pixel is (the closer to blue 255 it is), the thicker grass will be at that location. Grass is entirely optional, but can be customized via map parameters and adds a nice touch to your map.

Example Feature Map:

[[File:examplefeature.jpg]]

=== A brief history of featuremaps ===

Feature maps were (and still are) a single RGB image where features such as grass, geothermal vents and trees, as well as structures, etc were "placed" using pixels on the image. This method was extremely imprecise and involved recompiling the map many times in order to simply move a tree from one location to another.

[[Category:Map making|Map_making]]

= Compiling a Map (MapConv) =

== Texture Specifications ==

Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps must be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).

Height Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025

Metal Map dimensions are Texture Map size / 16 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 16 = 512x512

Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024

== Using MapConv ==

[[MapConv]] is a command line program that is generally started via a batch file .

Below is an example set of parameters given to mapconv:

<code>'''MapConv -i -l -c 0 -x 101 -n 100 -o EvoRTS-Craggy_Creek-v01.smf -t terrain.png -a height6.png -m metal.png -f feature.png -z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file"'''</code>

Once compiled, you will get 2 new files: <mapname.smt> and <mapname.smf>

= Utilizing Blueprint =

Unzip the blueprint archive into your Spring Maps folder.

[[File:mapcontainer.jpg]]

You will notice a new folder called "mapcontainer.sdd". The .sdd ending on the folder name is very important for testing as <foldername>.sdd tells spring to load map files from that folder. This way you can work on your maps without having to zip them up over and over again.

== mapcontainer.sdd ==

Inside the map container folder you have the following file/folder structure.

<div>'''<code>LuaGaia</code>'''</div><div>'''<code>mapconfig</code>'''</div><div>'''<code>maphelper</code>'''</div><div>'''<code>maps</code>'''</div><div>'''<code>mapinfo.lua</code>'''</div><div>'''<code>mapoptions.lua</code>'''</div><div><br/></div>
Now, copy your compiled map files (the <code>.smt</code> and <code>.smf</code> files) into the "maps" folder.

= Texture Splatting using SSMF =

SSMF mapping is adding detail textures all over the map based upon specified distribution areas. This will make your map infinitely more detailed and beautiful.

Adding SSMF to a map consists of the following steps:

== Distribution Map ==

The Distribution map is essentially an atlas telling spring where to spread your detail textures. Lets have a look at an example distribution map:

http://www.evolutionrts.info/random/examplesplatdistribution.jpg

Each channel corresponds to a different texture referenced in the detail texture map. These areas are set using the channels of the image and are generally saved using the Targa format ( .tga ), sized at 1024x1024.

http://www.evolutionrts.info/random/examplechannels.jpg

Save your distribution map as splatdistribution.tga, and place it in the maps folder alongside the smf and smt files.

Once you have your distribution map, you need to set up your detail textures

== Detail Textures ==

Detail textures are made by adding a texture to each channel of an image.

http://www.evolutionrts.info/random/examplesplattex.jpg

There are a total of 4 texture slots available. One for R, G, B, and one for the Alpha Channel. When you have your detail textures ready, save the file as splattex.tga (Targa - 1024x1024) and place it in the maps folder alongside splatdistribution.tga

== Specular Map ==

A specular map controls brightness and "shinyness" of your map. The more light you add to a particular portion of your specular map, the brighter and more reflective that portion of the map will be. Specular maps should be 1024x1024 and saved as specularmap.bmp. Of course placed in the maps folder with the other ssmf maps.

http://www.evolutionrts.info/random/examplespecularmap.jpg

== Grass Shading Map ==
By default spring's grass pulls the minimap to use for coloration of the grass patches. You can override this with ''grassShadingTex''. Below is an example

<table><tr><td colspan="2">Grass map</td><td>Grass map in game</td></tr>
<tr><td>[[File:Grassmap_Map_example.jpegâ€Ž|120px|alt=grassmap example |grassmap]]</td><td>This is a section of grassmap image. This image applied to the entire map which determines the color of grass.</td><td>[[File:Grassmap_Map_ingame.jpgâ€Ž|300px|alt=grassmapp applied in game|in game]]</td></tr><tr><td colspan="2">Click image for larger picture</td><td>Click image for larger picture</td></tr></table>

== Normal Map ==

Normal maps (in this case) are used to add "fake" 3d detail to a flat 2d image. It is a technique of manipulating lighting to give the appearance of looking at a 3d object, when actually it is just 2D.

This is what a normal map looks like:
[[File:examplenormalmap.jpg]]

= Placing Features =

As previously mentioned, features can now be placed via LUA based upon a coordinate system that looks similar to this:

<div><code>local features = { </code></div>
<div><code> unitlist = {</code></div>
<div><code> },</code></div>
<div><code> buildinglist = {</code></div>
<div><code> },</code></div>
<div><code> objectlist = {</code></div>
<div><code> { name = 'btreeclo_4', x = 7760, z = 112, rot = "0" },</code></div>
<div><code> { name = 'btreea_3', x = 2520, z = 6904, rot = "0" },</code></div>
<div><code> { name = 'btreeblo_5', x = 7736, z = 536, rot = "0" },</code></div>
<div><code> { name = 'btreeclo_1', x = 2504, z = 7112, rot = "0" },</code></div>
<div><code> { name = 'geovent', x = 177, z = 192, rot = "0" },</code></div>
<div><code> },</code></div>
<div><code>},</code></div>
<div><code>return features</code></div>

<div>Of course, features can be placed by editing the set.lua file in a text editor, but that would take an extremely long time. Enter FeaturePlacer.</div><div><br/></div>
== Feature Placer ==

* [[Map Making: Feature Placer|Feature Placer]]

= Configuring Map Parameters (Mapinfo.lua) =

Admittedly, the default values used in blueprint mapinfo are awful. It may be wise for you to download another map that has used blueprint and copy and paste it's mapinfo contents into yours. However, you are also free to use the default or use the provided example.

In time, the mapinfo tags will be documented and this will like to that page. As it is the tags and values are pretty easy to figure out for the most part.

== MapInfo.lua ==
* [[Map_Making:mapinfo.lua|MapInfo.lua]]

= Skyboxes =

*[[Skyboxcreation|Notes about skyboxes]] notes on a prerendered sky box or cube map.

= Mutators =

Mutators are files that add new content to exiting game files. "[http://springfiles.com/spring/tools/spring-features Spring Features]" is an example of a mutator.

This section needs a proper description.

[http://springrts.com/phpbb/viewtopic.php?f=13&t=21808 http://springrts.com/phpbb/viewtopic.php?f=13&t=21808]

= Archiving a Map =

<div>Spring reads two different archive formats, 7zip and zip. Both archives are named sd7 and sdz, respectively. 7zip files are made by The 7zip archive program, available at [http://www.7-zip.org/ http://www.7-zip.org/]</div><div><br/></div><div>Navigate to your mapcontainer.sdd folder and zip it's contents into either a .7z file or .zip (7zip format is '''HIGHLY RECOMMENDED'''!), usually naming schemes follow the actual mapname (<mapname.sd7>, such as EvoRTS-Craggy_Creek-v08.sd7</div><div><br/></div><div>

<span style="color:red">'''Make sure that the archive is non-solid!''' </span>

[[File:examplearchivewith7zip.jpg]]<br/></div><div><br/></div><div>Once completed, copy the sd7/sdz file to your maps folder. At this point, be sure to remove the .sdd ending from your mapcontainer.sdd folder (or change the map name/version contained withing), otherwise you might get sync errors because spring is reading from the wrong archive source.</div>
<br/>

= Tools =

*[[Maps:SpringMapEdit|Frostregen's SpringMapEdit]]. 3D editing, Compiles and import SM2 directly. Beginner friendly but still powerful.
*[[MapConv]] Map converter program, compiles maps.
*[[MapConvNG]] Rewrite of MapConv that works on linux / 64 bit.
*[[Maps:Map Designer]] '''(Outdated, Deprecated)''' Hugh's 3D map designer. Splatting, heightmap editing, splat painting, SM3
*[http://www.springfiles.com/show_file.php?id=1679 Starting position creator]: Or you can always find out the hard way which x/y coordinates are good by starting spring and having a look at the mouse cursor coordinates.
*[http://code.google.com/p/conflictterra/source/browse/games/CT/luaui/widgets/tp_coordinate_help.lua Coordinate Helper widget] A small widget that helps you with finding coordinates ie for start positions. Every time you put down a marker it will log its position in [[Infolog.txt]] and also in MAPNAME_coordinates.txt Helpfull if you need to get lots of map coordinates and do not want to write them down by hand. (it writes SpawnResource in front of the coordinates but you can ignore or edit the widget)

= Minimal barebones template with no extras =
If you want a completely barebones template with no extra configuration needed (useful for testing), Extract the blueprint files, then delete everything except mapinfo.lua and everything in maps folder (except your .smf and .smt files). Next copy paste following to mapinfo.lua (not the most minimal but minimal enough):
<pre>
local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "",
modtype = 3, --// 3=map

teams = {
[0] = {startPos = {x = 8, z = 8}},
[1] = {startPos = {x = 16, z = 16}},
},
}
return mapinfo
</pre>
In summary: maps folder with .smf.and .smt files and single mapinfo.lua file. You should be now able to test your map immediately (if files are placed to mapcontainer.sdd).

Tutorial:MapDevWithBlueprint(Forb)

2014-02-24T21:48:51Z

Forboding angel: /* The Components of a Map */

[[Engine Development|Development]] < {{FULLPAGENAME}}

= Getting Started (Tools) =

'''Blueprint: '''[https://github.com/jk3064/Map-Blueprint https://github.com/jk3064/Map-Blueprint] 

The only other tool really needed is "Mapconv". The other tools available are there simply to make your life easier. A list of common mapping tools are as follows:

[[MapConv|Mapconv]]

[[MapConvNG|MapConvNG - For use with Linux]]

SMFED '''(Deprecated, no longer useful)'''

Grout '''(Deprecated, no longer useful unless texture was generated with L3dt utilizing tiles)'''

SMD Creator '''(Deprecated, no longer useful)'''

[http://springfiles.com/spring/tools/mapping-tools Start Position Editor]

[http://springfiles.com/spring/tools/mapping-tools Das Bruce's Mapconv frontend]

These tools have been compiled into a zip available here: [http://springfiles.com/spring/tools/mapping-tools http://springfiles.com/spring/tools/mapping-tools]

Keep in mind that mapconv is still being developed, so it may be necessary to update the included Mapconv to a later version, located here: [http://springrts.com/phpbb/viewtopic.php?f=56&t=21458 http://springrts.com/phpbb/viewtopic.php?f=56&t=21458]

= The Components of a Map =

== Texture Map ==

<code>'''Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps mus be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).'''</code>

This guide assumes that you understand how to make a texture map and it also assumes that you know how to use terrain generation software.

Commonly used terrain generation programs are:

Spring Map Edit (Does not work on 64bit machines)

L3DT

WorldMachine

Bryce3D

Carrara

Example Texture Map (generated by Carrara):

[[File:exampletexturemap.jpg]]

== Heightmap ==

<code>'''Height Maps are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

You will need a good image editing program to make heightmaps. Many of the aforementioned terrain generation programs will also generate heightmaps as well, but you can draw them by hand. They can be either 8bit or 16bit greyscale PNG. If you have photoshop or the gimp, you can use these programs to help you create your heightmap.

Here is an example of a 16bit heightmap:

[[File:Heightmapexample.png]]

Heightmaps work upon the idea of height according to color values. Black is the lowest, white is the heighest. In spring mapping, the waterline is defined by a negative height value. In other words, you define the heights of the map,  anything below 0 is under water. So on this heightmap, you might use -50 for the lowest value and 300 for the highest height value. The aforementioned tool "Mapconv Gui (a.k.a Das Bruce's MapConv Gui) has a waterline calculator that will help you calculate the correct waterline for your map.

== Metal Map ==

<code>'''Metal Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025'''</code>

In Spring, metal maps are used for the built in resourcing scheme (Metal/Energy). You do not have to use this scheme. In fact, there are several games for Spring who use their own resourcing systems added on using Lua. If you are creating this map for one of those games, a metal map is not strictly necessary (in other words you can just us a black image), however, it is always nice if you can make your maps as compatible with other games as possible, but this is a choice left entirely up to you.

Metalmaps show metal areas on a map based upon the amount of red on the image (make sure red is the only color used!). On this map you can see that the "Patch Technique" is used, which is pretty common among spring maps, but you are not limited to using this scheme.

If you do want perfect metal patches, use a 6x6 pixel pencil in your image editor with a red value of 255. This combined with setting the "MaxMetal" tag in the definitions to 1, will result in a perfect 2.0 metal generation per patch (using Balanaced Annihilation values). The game use isn't the point however. The fact is that if you can predict how much each spot will output (typically), using the "MaxMetal" parameter, you can easily scale the values up and down. As an example of another extreme, Evolution RTS dictates that all metal patches will output 0.5 metal regardless of the map settings. So whether you need to put a lot of thought into your metal map values depends entirely upon the game for which you are creating the map.

Example Metal Map:

[[File:Examplemetal.jpg]]

== Feature Map ==

<code>'''Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024'''</code>

Feature maps used to be quite complicated, but all that changed with the advent of Smoth's FeaturePlacer (short featuremap history below).

Now featuremaps are use simply for the purpose of placing grass. Grass coverage is defined by blue pixels on the feature map. The more blue the pixel is (the closer to blue 255 it is), the thicker grass will be at that location. Grass is entirely optional, but can be customized via map parameters and adds a nice touch to your map.

Example Feature Map:

[[File:examplefeature.jpg]]

=== A brief history of featuremaps ===

Feature maps were (and still are) a single RGB image where features such as grass, geothermal vents and trees, as well as structures, etc were "placed" using pixels on the image. This method was extremely imprecise and involved recompiling the map many times in order to simply move a tree from one location to another.

[[Category:Map making|Map_making]]

= Compiling a Map (MapConv) =

== Texture Specifications ==

Texture map size is related in pixels and in spring map size. 2x2 MapSquares in spring are equal to 1024x1024 Pixels. Texture maps must be in multiples of 2. I.E. 2x2, 6x10, 12x16, 16x16, etc. No odd sizes are allowed (Example: 15x10).

Height Map dimensions are Texture Map size / 8 + 1 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 + 1 = 1025x1025

Metal Map dimensions are Texture Map size / 16 pixel. In other words, if your texture map is 8192x8192 (16x16), 8192 / 16 = 512x512

Feature Map dimensions are Texture Map size / 8. In other words, if your texture map is 8192x8192 (16x16), 8192 / 8 = 1024x1024

== Using MapConv ==

[[MapConv]] is a command line program that is generally started via a batch file .

Below is an example set of parameters given to mapconv:

<code>'''MapConv -i -l -c 0 -x 101 -n 100 -o EvoRTS-Craggy_Creek-v01.smf -t terrain.png -a height6.png -m metal.png -f feature.png -z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file"'''</code>

Once compiled, you will get 2 new files: <mapname.smt> and <mapname.smf>

= Utilizing Blueprint =

Unzip the blueprint archive into your Spring Maps folder.

[[File:mapcontainer.jpg]]

You will notice a new folder called "mapcontainer.sdd". The .sdd ending on the folder name is very important for testing as <foldername>.sdd tells spring to load map files from that folder. This way you can work on your maps without having to zip them up over and over again.

== mapcontainer.sdd ==

Inside the map container folder you have the following file/folder structure.

<div>'''<code>LuaGaia</code>'''</div><div>'''<code>mapconfig</code>'''</div><div>'''<code>maphelper</code>'''</div><div>'''<code>maps</code>'''</div><div>'''<code>mapinfo.lua</code>'''</div><div>'''<code>mapoptions.lua</code>'''</div><div><br/></div>
Now, copy your compiled map files (the <code>.smt</code> and <code>.smf</code> files) into the "maps" folder.

= Texture Splatting using SSMF =

SSMF mapping is adding detail textures all over the map based upon specified distribution areas. This will make your map infinitely more detailed and beautiful.

Adding SSMF to a map consists of the following steps:

* [[SSMF:_Distribution_Map|Distribution Map]]

* [[SSMF:_Detail_Textures|Detail Textures]]

* [[SSMF:_Specular_Map|Specular Map]]

* [[SSMF:_Grass_Shading_Map|Grass Shading Map]]

* [[SSMF:_Normal_Map|Normal Map]]

= Placing Features =

As previously mentioned, features can now be placed via LUA based upon a coordinate system that looks similar to this:

<div><code>local features = { </code></div>
<div><code> unitlist = {</code></div>
<div><code> },</code></div>
<div><code> buildinglist = {</code></div>
<div><code> },</code></div>
<div><code> objectlist = {</code></div>
<div><code> { name = 'btreeclo_4', x = 7760, z = 112, rot = "0" },</code></div>
<div><code> { name = 'btreea_3', x = 2520, z = 6904, rot = "0" },</code></div>
<div><code> { name = 'btreeblo_5', x = 7736, z = 536, rot = "0" },</code></div>
<div><code> { name = 'btreeclo_1', x = 2504, z = 7112, rot = "0" },</code></div>
<div><code> { name = 'geovent', x = 177, z = 192, rot = "0" },</code></div>
<div><code> },</code></div>
<div><code>},</code></div>
<div><code>return features</code></div>

<div>Of course, features can be placed by editing the set.lua file in a text editor, but that would take an extremely long time. Enter FeaturePlacer.</div><div><br/></div>
== Feature Placer ==

* [[Map Making: Feature Placer|Feature Placer]]

= Configuring Map Parameters (Mapinfo.lua) =

Admittedly, the default values used in blueprint mapinfo are awful. It may be wise for you to download another map that has used blueprint and copy and paste it's mapinfo contents into yours. However, you are also free to use the default or use the provided example.

In time, the mapinfo tags will be documented and this will like to that page. As it is the tags and values are pretty easy to figure out for the most part.

== MapInfo.lua ==
* [[Map_Making:mapinfo.lua|MapInfo.lua]]

= Skyboxes =

*[[Skyboxcreation|Notes about skyboxes]] notes on a prerendered sky box or cube map.

= Mutators =

Mutators are files that add new content to exiting game files. "[http://springfiles.com/spring/tools/spring-features Spring Features]" is an example of a mutator.

This section needs a proper description.

[http://springrts.com/phpbb/viewtopic.php?f=13&t=21808 http://springrts.com/phpbb/viewtopic.php?f=13&t=21808]

= Archiving a Map =

<div>Spring reads two different archive formats, 7zip and zip. Both archives are named sd7 and sdz, respectively. 7zip files are made by The 7zip archive program, available at [http://www.7-zip.org/ http://www.7-zip.org/]</div><div><br/></div><div>Navigate to your mapcontainer.sdd folder and zip it's contents into either a .7z file or .zip (7zip format is '''HIGHLY RECOMMENDED'''!), usually naming schemes follow the actual mapname (<mapname.sd7>, such as EvoRTS-Craggy_Creek-v08.sd7</div><div><br/></div><div>

<span style="color:red">'''Make sure that the archive is non-solid!''' </span>

[[File:examplearchivewith7zip.jpg]]<br/></div><div><br/></div><div>Once completed, copy the sd7/sdz file to your maps folder. At this point, be sure to remove the .sdd ending from your mapcontainer.sdd folder (or change the map name/version contained withing), otherwise you might get sync errors because spring is reading from the wrong archive source.</div>
<br/>

= Tools =

*[[Maps:SpringMapEdit|Frostregen's SpringMapEdit]]. 3D editing, Compiles and import SM2 directly. Beginner friendly but still powerful.
*[[MapConv]] Map converter program, compiles maps.
*[[MapConvNG]] Rewrite of MapConv that works on linux / 64 bit.
*[[Maps:Map Designer]] '''(Outdated, Deprecated)''' Hugh's 3D map designer. Splatting, heightmap editing, splat painting, SM3
*[http://www.springfiles.com/show_file.php?id=1679 Starting position creator]: Or you can always find out the hard way which x/y coordinates are good by starting spring and having a look at the mouse cursor coordinates.
*[http://code.google.com/p/conflictterra/source/browse/games/CT/luaui/widgets/tp_coordinate_help.lua Coordinate Helper widget] A small widget that helps you with finding coordinates ie for start positions. Every time you put down a marker it will log its position in [[Infolog.txt]] and also in MAPNAME_coordinates.txt Helpfull if you need to get lots of map coordinates and do not want to write them down by hand. (it writes SpawnResource in front of the coordinates but you can ignore or edit the widget)

= Minimal barebones template with no extras =
If you want a completely barebones template with no extra configuration needed (useful for testing), Extract the blueprint files, then delete everything except mapinfo.lua and everything in maps folder (except your .smf and .smt files). Next copy paste following to mapinfo.lua (not the most minimal but minimal enough):
<pre>
local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "",
modtype = 3, --// 3=map

teams = {
[0] = {startPos = {x = 8, z = 8}},
[1] = {startPos = {x = 16, z = 16}},
},
}
return mapinfo
</pre>
In summary: maps folder with .smf.and .smt files and single mapinfo.lua file. You should be now able to test your map immediately (if files are placed to mapcontainer.sdd).

Spring Tanks

2013-10-31T09:47:23Z

Forboding angel: /* Advice for Hosting */

= About =
'''Spring Tanks''' started as an experiment but is slowly evolving into a complete game. As it is still being worked on, it is a bit rough around the edges but playable.

[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<br>
http://springfiles.com/spring/spring-maps/desertcliffsv1

'''Aquatic Divide''' - 1v1<br>
http://springfiles.com/spring/spring-maps/aquaticdividetnm05-v2

'''Eye_Of_Horus_v2''' - 1v1, 3ffa, 4ffa, 2v2<br>
http://springfiles.com/spring/spring-maps/eye-horus-v2

'''Saltrock Colony''' - 1v1, 3ffa<br>
http://springfiles.com/spring/spring-maps/saltrockcolonyv2

'''Canyon Crossing''' - 1v1, 3ffa, 4ffa, 2v2<br>
http://springfiles.com/spring/spring-maps/canyon-crossing

'''Into Battle''' - 1v1<br>
http://springfiles.com/spring/spring-maps/battle-v3

'''Castles''' - 1v1, 3ffa, 4ffa, 2v2<br>
http://springfiles.com/spring/spring-maps/castles

'''Mount Dustmore v3''' - 1v1, 3ffa, 4ffa, 2v2<br>
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.<br>
To open it:<br>
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><br>
needs fixing to work with newest Spring release 84.0 (will eventually be done)<br>
development: {{forumlink|thread=26937|title=see forum:}}
paused due to other things being more interessting.

[[Category:Games]]

Main Page

2013-10-29T21:55:42Z

Forboding angel:

{|border="0" cellpadding="4" cellspacing="1"
| width="50%" valign="top" |
== Playing & General ==

'''[[Read Me First]]''' Answers to questions often asked - Everyone should read this first.

'''[[FAQ]]''' Has it been asked before?

'''[[Keyboard]]''' Default Keyboard Layout in the Engine.

'''[[Games]]''' Games that use the Spring engine.

'''[[Maps]]''' All about maps for the Spring engine and where to get them.

'''[[Getting Spring Content and Links]]''' Lists sites related to spring, and sites from which you can download spring Games, Maps, and more

'''[[AI:Skirmish]]''' Skirmish AIs for Singleplayer

'''[[Lua Widgets]]''' All about installing and using LuaUI widgets...

'''[[Hosting Spring]]''' Autohosting and related topics.

'''[[Spring_on_MacOSX |Mac OS]]''' Mac OSX information.

'''[[SetupGuide |Linux]]''' NetBSD / Solaris / Linux / Cross-platform information.

'''[[Spring_Replays |Replays]]''' Watching recordings of previously played matches.

'''[[Statistics]]''' Some links/infos to statistics.

'''[[Advertisement|Advertising Spring RTS]]''' Description of campaigns and available resources.

'''[[The Lighter Side Of Spring]]''' Humour, comics and quotations.
| width="50%" valign="top" |
== Development ==
'''[[Game_and_Unit_development#Mod_development|Game Development]]''' Lots of links to valuable Articles and forum threads regarding Game/Unit Development.

'''[[Mapdev:Main|Map Development]]''' Tutorials and other useful information for creating maps.

'''[[Development:Getting_Started|Engine Development]]''' Starting point for engine development.

'''[[Lua Scripting]]''' Information regarding the use of the supplementary Lua scripting language for Widgets and beyond...

'''[[Map, Mod, And Unit Development Programs|Content Development Programs]]''' Links to all kind of useful programs.

'''[[AI:Development|AI Development]]''' Lots of information about developing Skirmish, Unit and Group AIs for Spring.

'''[[General Resources]]''' Usable textures, sounds and code snippets by the community, for the community.

'''[[Chili|Chili UI framework]]''' Chili Ui framework designed by JK

'''[[Associated Development Groups]]''' Teams, Forums and Groups associated with Spring content and code development.
|}

{||
|
=This wiki needs your help!=

''"A wiki is a web application that allows users to add content, as on an Internet forum, but also allows anyone to edit the content."''
- [http://en.wikipedia.org/wiki/Wiki Wikipedia.org]

The Spring project is very dependent on its community of users to help new players and developers. [[SpringWiki|Learn more here.]]

|}

{| |
|
=Unable to log in?=
The login data for the wiki is the same as on the forum.
If you get the message "You have not specified a valid user name." that is due a [http://springrts.com/mantis/view.php?id=1592 bug] with special characters in account names.
At the moment the only thing you can do, is create a new/second account that consists of letters only.
|}

__NOTOC__
__NOEDITSECTION__
[[Category:Spring]]

Main Page

2013-10-29T21:55:42Z

Forboding angel:

Map Making: Feature Placer

2013-05-08T13:10:17Z

Forboding angel: /* Feature Placer */

{{FIXME}} needs updating to use the information in [http://springrts.com/phpbb/viewtopic.php?f=13&t=29559 thread] about seperation of feature placer
= Feature Placer =

At this point, it is very strongly recommended that you grab Spring Features. Spring features is an archive that contains all the map features ever made for spring mapping. The total number is somewhere around 500 features, so it will give you quite a bit of power when it comes time to spice up your map.

Spring Features is available via the rapid tag: spring-features:stable

Feature placer is available for use via the rapid tag: feature-placer:test

You can use pr-downloader to get the latest version, either by using pr-downlaoder in the command line, or using Forboding Angel's pr-downloader menu ( http://goo.gl/kGJBx - Extract to spring folder, next to pr-downloader.exe (Windows only) ).

= Using Feature Placer =

When the spring starts up you will be presented with a tree that is sparkling green. Select it and you will have the option to build an entire host of features. There are also placement options on the menu such as "Jitter" and "Clustering", etc. Set these as desired.

== Exporting the Feature List ==

Simple click the "export set.lua" button. Then, look in your spring folder, under maps, and look for the file <yourmapname.lua>. Once you have verified that the file was written, you may go ahead and close the game.

= Adding the Feature List to your map =

Open <yourmapname.lua> in a text editor and copy the entire contents. Then navigate to

mapcontainer.sdd/mapconfig/featureplacer/set.lua

Open up set.lua in a text editor, and paste the contents of <yourmapname.lua>t into it.

<br/><br/>

[[Category:Map making|Map_making]] <br/>

Map Making: Feature Placer

2013-05-08T13:09:08Z

Forboding angel: /* Adding the Feature List to your map */

{{FIXME}} needs updating to use the information in [http://springrts.com/phpbb/viewtopic.php?f=13&t=29559 thread] about seperation of feature placer
= Feature Placer =

At this point, it is very strongly recommended that you go download "[http://springfiles.com/spring/tools/spring-features Spring Features]" ( [http://springfiles.com/spring/tools/spring-features http://springfiles.com/spring/tools/spring-features] ) and place it in your games folder. Spring features is an archive that contains all the map features ever made for spring mapping. The total number is somewhere around 500 features, so it will give you quite a bit of power when it comes time to spice up your map.

Spring Features is also available via the rapid tag: spring-features:stable

Feature placer is available for use via the rapid tag: feature-placer:test

You can use pr-downloader to get the latest version, either by using pr-downlaoder in the command line, or using Forboding Angel's pr-downloader menu ( http://goo.gl/kGJBx - Extract to spring folder, next to pr-downloader.exe (Windows only) ).

= Using Feature Placer =

When the spring starts up you will be presented with a tree that is sparkling green. Select it and you will have the option to build an entire host of features. There are also placement options on the menu such as "Jitter" and "Clustering", etc. Set these as desired.

== Exporting the Feature List ==

Simple click the "export set.lua" button. Then, look in your spring folder, under maps, and look for the file <yourmapname.lua>. Once you have verified that the file was written, you may go ahead and close the game.

= Adding the Feature List to your map =

Open <yourmapname.lua> in a text editor and copy the entire contents. Then navigate to

mapcontainer.sdd/mapconfig/featureplacer/set.lua

Open up set.lua in a text editor, and paste the contents of <yourmapname.lua>t into it.

<br/><br/>

[[Category:Map making|Map_making]] <br/>

Map Making: Feature Placer

2013-05-08T13:08:24Z

Forboding angel: /* Using Feature Placer */

{{FIXME}} needs updating to use the information in [http://springrts.com/phpbb/viewtopic.php?f=13&t=29559 thread] about seperation of feature placer
= Feature Placer =

At this point, it is very strongly recommended that you go download "[http://springfiles.com/spring/tools/spring-features Spring Features]" ( [http://springfiles.com/spring/tools/spring-features http://springfiles.com/spring/tools/spring-features] ) and place it in your games folder. Spring features is an archive that contains all the map features ever made for spring mapping. The total number is somewhere around 500 features, so it will give you quite a bit of power when it comes time to spice up your map.

Spring Features is also available via the rapid tag: spring-features:stable

Feature placer is available for use via the rapid tag: feature-placer:test

You can use pr-downloader to get the latest version, either by using pr-downlaoder in the command line, or using Forboding Angel's pr-downloader menu ( http://goo.gl/kGJBx - Extract to spring folder, next to pr-downloader.exe (Windows only) ).

= Using Feature Placer =

When the spring starts up you will be presented with a tree that is sparkling green. Select it and you will have the option to build an entire host of features. There are also placement options on the menu such as "Jitter" and "Clustering", etc. Set these as desired.

== Exporting the Feature List ==

Simple click the "export set.lua" button. Then, look in your spring folder, under maps, and look for the file <yourmapname.lua>. Once you have verified that the file was written, you may go ahead and close the game.

= Adding the Feature List to your map =

Open dumpedunitsfeatures.txt in a text editor and copy the entire contents. Then navigate to

mapcontainer.sdd/mapconfig/featureplacer/set.lua

Open up set.lua in a text editor, and paste the contents of dumpedunitsfeatures.txt into it. Be sure to remove any entries in the unitlist or buildinglist sections.

<br/><br/>

[[Category:Map making|Map_making]] <br/>

Map Making: Feature Placer

2013-05-08T13:06:17Z

Forboding angel: /* Feature Placer */

{{FIXME}} needs updating to use the information in [http://springrts.com/phpbb/viewtopic.php?f=13&t=29559 thread] about seperation of feature placer
= Feature Placer =

At this point, it is very strongly recommended that you go download "[http://springfiles.com/spring/tools/spring-features Spring Features]" ( [http://springfiles.com/spring/tools/spring-features http://springfiles.com/spring/tools/spring-features] ) and place it in your games folder. Spring features is an archive that contains all the map features ever made for spring mapping. The total number is somewhere around 500 features, so it will give you quite a bit of power when it comes time to spice up your map.

Spring Features is also available via the rapid tag: spring-features:stable

Feature placer is available for use via the rapid tag: feature-placer:test

You can use pr-downloader to get the latest version, either by using pr-downlaoder in the command line, or using Forboding Angel's pr-downloader menu ( http://goo.gl/kGJBx - Extract to spring folder, next to pr-downloader.exe (Windows only) ).

= Using Feature Placer =

'''If you use Evolution RTS for feature placer, once ingame be sure to disable the "Integral Menu" widget (f11 - Widget Menu), as the menu does not support paging.'''

<br/>You will need to go into the multiplayer lobby (one that supports modoptions and hosing your own games). Create a new game (not using a relay slave). In the modoptions set the game type to "Featureplacer" and add a NullAI.

When the game starts up you will be presented with a tree that is sparkling green. Select it and you will have the option to build an entire host of features. There are also placement options on the menu such as "Jitter" and "Clustering", etc. Set these as desired.

== Exporting the Feature List ==

Once you have placed all the features on your map and are ready to export the placement, press F11 to bring up the widget menu, and select "Dump All Units Features". Click it 3 times. At this point, before exiting the game, alt+tab out to your spring install folder and look for a file called dumpedunitsfeatures.txt to make sure that the file was written properly. Once you have verified this, you may go ahead and close the game.

= Adding the Feature List to your map =

Open dumpedunitsfeatures.txt in a text editor and copy the entire contents. Then navigate to

mapcontainer.sdd/mapconfig/featureplacer/set.lua

Open up set.lua in a text editor, and paste the contents of dumpedunitsfeatures.txt into it. Be sure to remove any entries in the unitlist or buildinglist sections.

<br/><br/>

[[Category:Map making|Map_making]] <br/>

SpringSettings

2013-05-07T22:37:05Z

Forboding angel: Redirected page to Springsettings.cfg

#REDIRECT [[Springsettings.cfg]]