Spring - User contributions [en]

Gamedev:UnitDefs

2025-04-08T11:16:40Z

Flozi: /* Categories */ A warning about null categories leading to untargetable units

[[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; ATTENTION: unfinished implementation, can be set in UnitDefs but it can't be read in-game}}
|description = How much of the metal resource a unit can store when used as an engine-assisted resource 'harvester'. See also [[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 maximum amount of the energy resource the unit generates which is dependant on the map wind. Works only for structures. If wind speed is higher than this, the unit will still only produce this much. If wind speed is less, it will produce as much as windspeed is.}}

{{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 89.0 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 = Removed in 95.0
|description = Is the unit a hovercraft? Hovercraft can cross water of any depth without a speed penalty. Hover's must also have <code>HOVER</code> within the name of their {{taglink|movementClass}} (see [[Movedefs.lua]]).
}}

{{tag
|name = floater
|type = bool
|default = 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 frame2. If the value is -ve, the absolute value is used.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = frontToSpeed
|type = float
|default = 0.1
|description = 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]]. 
{{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]]). Be aware that if no category is set, by default the unit will not be targetable due to {{taglink|onlyTargetCategory}} defaulting to a null string also.}}

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

{{tag
|name = modelCenterOffset
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = Removed in 89.0 (Now set via lua)
|description = How far from the model's defined centre should the centre of the unit be?}}

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

2022-11-17T19:44:23Z

Flozi: /* Animation of units */ link to examples

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

= Game Development =
This information is meant to help newcomers learn how to develop their own games for the Spring Engine. If you are interested in creating maps for Spring, see [[Mapdev:Main]].

= Templates & Examples =
* [[Gamedev:SpringABC|SpringABC]] - A hierarchical set of empty template games, without examples
* [[SpringTutorialGame|Spring Tutorial Game]] - A tutorial template game with full examples
* [[Gamedev:PublicRepos|Public Repos]] - Publicly readable Spring game code repositories

= Technical Documentation =
== GameData ==
* [[Armordefs.lua]] - armor classes
* [[Icontypes.lua]] - strategic unit icons
* [[Modinfo.lua]] - game identifier file (name, version,...)
* [[Modrules.lua]] - Global game variables
* [[Movedefs.lua]] - MoveClasses for pathfinding
* [[Resources.lua]] - index file for textures
* [[Sidedata.lua]] - playable factions/races/sides
* [[Sounds.lua]] - index file for sounds
* [[Messages.lua]] - Team death messages {{new|95.0}}:deprecated

== Definition Files ==
* [[Gamedev:UnitDefs]] - define the attributes of units
* [[Gamedev:WeaponDefs]] - define the attributes of weapons/projectiles
* [[Gamedev:FeatureDefs]] - define the attributes of static map features and wrecks
* [[CEG:Main]] Particle effects (explosions etc)

== Lua API & Libraries (excerpt) ==
* [[Lua_Scripting|Lua API Documentation]]
* [[Lua_Libraries|Lua Libraries]]

== Animation of units ==
Lua Animations (LUS)
*[[Animation-LuaScripting]]
**[[Animation-LuaCallins]]
**[[Animation-LuaCallouts]]
**[[Animation-CobLuaDifferences]]
**[[Animation:LuaExamples]]

COB Animations (Antiquated)
*[[Animation-CobOverview]]
**[[Animation-CobAnimation]]
**[[Animation-CobCallins]]
**[[Animation-CobConstants]]
**[[Animation-CobThreads]]
**[[Animation-CobHitByWeaponID]]
**[[Lua-LuaCOB]] - how to interface COB with LUA
**[[CEG_For_Units|Game Development:Calling basic CEGs from COB]]
**{{forumlink|topic=7457|title=GPL COB Examples}}

== Models & Textures ==
* [[About_s3o|.s3o]]
* [[Assimp]]
** [[3DModels:AssimpWorkflow]]
* [[3DModels:Textures]]
* [[Shaders:CustomUnitShadingFramework]]
** [[Shaders:PBRShaders]]

== Misc ==
* [[Gamedev:DebugDrawModes]]
* [[Gamedev:Archives]] - packing game/map
* [[Gamedev:Buildpics]]
* [[Gamedev:CollisionVolumes]]
* [[Gamedev:Glossary]]
* [[Gamedev:MouseCursors]]
* [[Gamedev:Sidepics]]
* [[Gamedev:Structure]]
* [[VirtualFileSystem]]

= Tools =
== In-Game Tools ==
*[http://springboard-core.readthedocs.io/en/latest/ SpringBoard] - Powerful map and scenario editor
*[[Map Making: Feature Placer|Feature Placer]] - A Map Feature & NPC Unit Placement Tool

== External Tools ==
* [[Upspring]]
* [[Map,_Mod,_And_Unit_Development_Programs|Development Tools]]

= Engine Related =
* [[Download_Testing]] - Test the compatibility of your game on upcoming versions of the Spring engine.

* [[EngineChangelogForContentDevs]] - New engine versions sometimes require games to adjust. A list of common problems.

* [[EngineSource_for_GameDevs]] - Notes about the engine source, from modding point of view.

= Tutorials =
== Tips, Tricks & Testing ==
[[TestingYourGame|These tricks and commands]] are useful for testing or debugging.

== Game Development Tutorials ==
*[[The Complete Guide To Making A Spring Game]] - A fairly comprehensive getting started tutorial.
*[http://springrts.com/phpbb/viewtopic.php?f=14&t=26409| Porting TA content to Spring]
*<strike>[[Simple Mod Tutorial|Simple Game Tutorial]]</strike> - needs to be updated

==Modelling Tutorials==
'''Wings3D'''
* [[3DModels:Wings3DTutorial]]
* [http://springrts.com/phpbb/viewtopic.php?t=10612 Wings UV Mapping Tutorial]

'''Blender'''
* [[TutorialBlenderWorkFlow|Blender Workflow Tutorial]]

'''3DS Max'''
* [http://springrts.com/phpbb/viewtopic.php?t=10503 Runecrafter's 3DS Max UV Mapping Tutorial]

==Texturing Tutorials==
* [http://springrts.com/phpbb/viewtopic.php?f=57&t=22392 DDS Textures: How To]
* [http://springrts.com/phpbb/viewtopic.php?t=10947 Greeble Tutorial 1]
* [http://springrts.com/phpbb/viewtopic.php?f=9&t=12356 Greeble Tutorial 2]

=Misc=
* [[Ren'Py]]: a visual novel engine that can be used with Spring
* <strike>[http://answers.springlobby.info/ Q&A Site for the Spring Engine]</strike> Currently down.

[[Category:Game Dev]]

Lua:Main

2022-11-17T19:43:51Z

Flozi: /* Tutorials */

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

=Lua FAQ=
Lua scripting is the primary way for developers to customize their games and add new features. Most aspects of the Spring engine can be controlled and extensively modified through the Lua API.

[[Lua_Beginners_FAQ|Introduction to Lua in Spring]] 
[[Lua:Tutorial_GettingStarted|Easy widget examples]]

=Interfaces {{HeaderNotice|(last update: 104)}}=
[[Lua:Environments]] (Details the available environments and shows which interfaces are loaded by each)

[[Lua:Callins]] (Entry points to lua addons)
{{LuaInterfaces}}

=Tutorials=
* [[Lua:Tutorial_GettingStarted|Easy example widgets]]
* [[LuaTutorials::InterCommunications]] (i.e. synced <-> unsynced communications)
* [[Animation:LuaExamples| Lua animation UnitScript examples]]

=Other useful information=
* [[Lua_Libraries | Lua libraries]]
* [[Lua_Performance | Lua performance tips]]
* [[UI_commands]]
* [[Animation-LuaScripting | Unit animation scripting with Lua]]
* [https://github.com/spring/spring/tree/develop/rts/Lua#Source_Code Source code for Lua API]

=Official Lua documentation=
[http://www.lua.org/pil/ 'Programming in Lua' book online] 
[http://www.lua.org/manual/5.1/ Lua 5.1 Reference manual] 
[http://lua-users.org/wiki/TutorialDirectory Lua tutorials]
[[Category: Lua]]

Animation-LuaScripting

2022-11-17T19:38:15Z

Flozi: /* Further reading */ add a link through to skeleton examples page

== Getting started ==

=== Setup ===

Lua unit animation is implemented partially in the engine, and partially in a Lua gadget which is shipped with Spring in [[springcontent.sdz]]. By default, gadget is not loaded, so a bit of setup is required to enable Lua unit scripts. (In some games, gadget is alredy activated, for example in Zero:k)

To enable Lua unit scripts, create a file ''LuaRules/Gadgets/unit_script.lua'', and paste the following into it:

{|border="0" cellpadding="4"
|style="background: #41545c; border: 1px #aaa solid;"|

-- Enables Lua unit scripts by including the gadget from springcontent.sdz

-- Uncomment to override the directory which is scanned for *.lua unit scripts.
--UNITSCRIPT_DIR = "scripts/"

return include("LuaGadgets/Gadgets/unit_script.lua")

|}

Also, do check whether your [http://github.com/spring/spring/blob/master/installer/builddata/springcontent/LuaGadgets/system.lua ''LuaRules/system.lua''] is up to date, if you copied this verbatim into your game. (Must be from a later date than 5 september 2009)

Now this is done, you can start putting *.lua files in your ''scripts/'' folder.

=== Workflow ===

Lua has the major advantage over BOS/COB that you do not need to compile it, which can reduce the time to develop scripts quite a bit.

To save further time, do not restart Spring for each small change. Simply run Spring in an window so you can easily switch between your editor and Spring, and use ''/cheat'' and ''/luarules reload'' to reload all Lua unit scripts.

To be able to use commands above, unzip your game into directory named "myGame.sdd", then you can directly change lua scripts (animations etc.) and reload.

Additionally, for Lua unit scripts operating on Assimp models (primarily .dae and .blend), it is possible to do most of your animating in Blender using the [https://github.com/Anarchid/blender2lus blender2lus] export addon.

=== Workflow for animating S3o models in Blender ===

Anarchids Blendertools can be used to animate (within limits) S3O models. Here are the steps:

1. Export your model into Blender.

2. Restore the Hierarchy in Blender.

https://blender.stackexchange.com/questions/26108/how-do-i-parent-objects
(Ctrl + P) is your friend .

3. If all Pivots are set correctly, create the Animations, one by one.

4. Export the Animations with Anarchids Skript Export tool.

5. Open the resulting Animationskript for postprocesing.

6. Find Move commands like {['c']='move',['p']=LowerJaw, ['a']=x_axis, ['t']=-0.000000, ['s']=0.012682}, and purge them. Replace them with todos- you will have to insert them manually later, with correct axis and values.

7.In the turn commands - exchange the ['a']=z_axis with ['a']=y_axisz and the old ['a']=y_axis with ['a']=z_axis.
Here is a Regex, to make the text-search easier.

{\['c']='turn',\['p']=([^\s]+), \['a']=z_axis, \['t']=\*

{\['c']='turn',\['p']=([^\s]+), \['a']=y_axis, \['t']=\*

8. Invert (change the sign) of the y_axis values.

9. Start the game and call the Animation you want to debug in a Loop.

10. Congratulations you now have smoothly animated S3o Models.

== Further reading ==
* [[Animation:LuaExamples]]
* [http://tvo.github.com/spring/2010/04/19/lus-stumpy.html Stumpy tutorial]
* [http://tvo.github.com/spring/2010/04/26/lus-stumpy-2.html Polishing the stumpy]
* [[Animation-LuaCallins]]
* [[Animation-LuaCallouts]]
* [[Animation-CobLuaDifferences | comparing Lua and COB unit scripts]]
* [[SpringTutorialGame]] contains simple examples unit scripts
* [[SpringRtsTutorialAnimDef]] examples animation scripts

== TODO ==

* Conversion tool
* Performance measurements
* Link to article in piro's magazine
* Coordinate system (axis, direction of rotation, picture)

[[Category:Animation]]

Armordefs.lua

2021-01-23T12:27:37Z

Flozi: /* More efficient with Lua */ delete this section

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

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

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

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

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

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

infantry = {
"dude",
},
}

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

return armorDefs</pre></code>

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

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

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

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

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

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

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

[[Category:gamedata]]

Lua SyncedRead

2020-06-30T20:23:10Z

Flozi: /* Unit Weapon Informations */ some bare minimum doc on what TestTarget/TestRange/TryTarget/HaveFreeLineOfFire actually do

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

== Game ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

Post 95.0 this no longer returns neutral units

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

'''Spring.GetUnitWeaponTryTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success
For a position just checks if the weapon can attackGround. For a unit checks that it exists, category, death status, crashing status, LOS status, neutral status, ally status and transport status.

'''Spring.GetUnitWeaponTestTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success
Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreLineOfFire.

'''Spring.GetUnitWeaponTestRange''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success
Checks target is in range including height modifiers and cylinder targeting if set.

'''Spring.GetUnitWeaponHaveFreeLineOfFire''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success
Runs a raytrace from unit aimpoint respecting collision flags.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Spring.GetFeatureLastAttackedPiece'''

'''Spring.GetFeaturePieceMap'''

'''Spring.GetFeaturePieceList'''

'''Spring.GetFeaturePieceInfo'''

'''Spring.GetFeaturePiecePosition'''

'''Spring.GetFeaturePieceDirection'''

'''Spring.GetFeaturePiecePosDir'''

'''Spring.GetFeaturePieceMatrix'''

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[category: Lua]]

Gamedev:DebugDrawModes

2020-06-25T14:46:40Z

Flozi: /* /DebugColVol (alt+v) */ about the points

= Debug Drawing Modes =
Spring has several drawing modes which are useful for debugging and performance checking.
They are listed below by [[UI commands]] with their default key binding.

== /Debug (alt+b) ==
[[File:Debug.jpg|400px|left|/Debug]]
Draws a toggleable list of engine functions and a breakdown of how much time is spent computing them. When toggled on a line graph is drawn to illustrate the change in performance over time.

Since 97.0 there is a new '''Frame Grapher''' visualisation which shows how the last half-second was spent:

* Green are video frames
* Red are simframes
* Blue is swapBuffer (gpu/vsync)
* Pink is lua gc
 

== /DebugColVol (alt+v) ==
[[File:DebugColVol.jpg|400px|left|/DebugColVol]]
Draws unit and feature [[Gamedev:CollisionVolumes|collision volumes]] as purple meshes. When hit by a weapon the meshes turn red. Since 99.0 weapon debug spheres are also drawn in this mode for the [[Animation-LuaCallins#Weapons|AimFromWeapon()]] position, [[Animation-LuaCallins#Weapons|QueryWeapon()]] (muzzle) position and unit target position. Shields spheres are drawn in blue. Weapon 'Query' points are in red, orange if aiming. Weapon 'AimFrom' points are in yellow. The unit centre is in magenta, and if it is different the target point of the unit is in red.
 

== /DebugPath (alt+p) ==
[[File:DebugPath_Close.jpg|400px|left|/DebugPath Close up view]][[File:DebugPath_Far.jpg|400px|left|/DebugPath Far out view]]

Draws pathfinder routes, colour coded by accuracy.

* Red is the most finely computed pathing
* Green is intermediate paths
* Blue is least accurate long range path
 

== /DebugTraceRay ==
It is meant for debugging trajectories of ballistic projectiles. [https://springrts.com/mantis/view.php?id=4664 Currently broken in 98.0]

 

== /DebugDrawAI ==
[[File:DebugDrawAI_E232AI.jpg|400px|left|/DebugDrawAI implemented in E232AI]]
This mode is toggled through the engine but is up to the native AI to implement itself. The image shows how [[AI:Skirmish:List|E232AI]] implements a real-time threatmap rendering and a real-time performance profiler.

[[Category: Game Dev]]

Animation-LuaCallins

2020-06-10T08:52:52Z

Flozi: /* Transports */ no s

== 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 
'''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 
'''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 
'''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.AimWeapon1(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(weaponNum, 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 
'''script.AimFromWeapon1''' ( ) -> number piece 
'''script.AimWeapon1''' ( heading, pitch ) -> boolean 
'''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 
'''script.Shot1''' ( ) -> nil 
'''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 
'''script.StartBuilding''' ( ) -> nil 
'''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.

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.

== 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) QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first) TransportDrop (each) EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each) EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil 
'''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 
'''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

2020-06-10T08:44:04Z

Flozi: /* Transports */ taglink

== 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 
'''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 
'''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 
'''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.AimWeapon1(heading, pitch)'')
* Combined function which gets weapon number as second argument. (e.g. ''script.AimWeapon(weaponNum, 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 
'''script.AimFromWeapon1''' ( ) -> number piece 
'''script.AimWeapon1''' ( heading, pitch ) -> boolean 
'''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 
'''script.Shot1''' ( ) -> nil 
'''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 
'''script.StartBuilding''' ( ) -> nil 
'''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.

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.

== 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|transportUnloadMethods}} 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) QueryTransport (each)
|EndTransport (last)
|EndTransport (each)
|StartUnload (first) TransportDrop (each) EndTransport (last)
|-
|ground
|TransportPickup (each)
|TransportDrop (each)
|TransportDrop (each)
|TransportDrop (each) EndTransport (last)
|}

=== Air transports ===

'''script.BeginTransport''' ( passengerID ) -> nil 
'''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 
'''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:LuaExamples

2020-06-09T15:38:15Z

Flozi: /* Factory */ should really call YARD_OPEN, too

= LUS Script Examples =

== How to use ==
* <code>FIXME</code> - Indicates a section of code you will need to tweak to suit your own unit / model
* <code>TODO</code> - Indicates an optional section of code is missing that you may wish to pad out e.g. with an animation

== Script Scaffolds ==
=== Air Transport ===
<syntaxhighlight lang="lua">
-- FIXME: This should be whatever piece name you want to attach to in your model
local attachPiece = piece "attach"

-- called for each unit loaded, returns the attaching piece
function script.QueryTransport(passengerID)
return attachPiece
end

-- called for each unit loaded to animate the load process
function script.BeginTransport(passengerID)
-- TODO: any loading animations here
end

--how this is called depends on https://springrts.com/wiki/Gamedev:UnitDefs#transportUnloadMethod
-- 0 (Default) called once on the last unit dropped
-- 1 called for each unit dropped in mid-air
-- 2 called for the last unit dropped
function script.EndTransport(passengerID)
-- TODO: relevant end of transport sequence animations
end

-- Only called if transportUnloadMethod = 2
function script.TransportDrop(passengerID, x,y,z)
-- TODO: animation to unload each individual passenger on the ground
end
</syntaxhighlight>

=== Builder ===
<syntaxhighlight lang="lua">
local nanoPieces = {}
-- FIXME: this example has 2 nano pieces to alternate between
for i = 1, 2 do
-- FIXME: the pieces are named nanoPiece1 and nanoPiece2 in the model
nanoPieces[i] = piece("nanoPiece" .. i)
end
Spring.SetUnitNanoPieces(unitID, nanoPieces)

function script.StartBuilding(heading, pitch)
-- TODO: This is where you would add your unpack / point towards animation
SetUnitValue(COB.INBUILDSTANCE, true)
end
function script.StopBuilding()
-- TODO: This is where you would add your pack-up animation
SetUnitValue(COB.INBUILDSTANCE, false)
end
</syntaxhighlight>

=== Factory ===
<syntaxhighlight lang="lua">
local nanoPieces = {}
-- FIXME: this example has 2 nano pieces to alternate between
for i = 1, 2 do
-- FIXME: the pieces are named nanoPiece1 and nanoPiece2 in the model
nanoPieces[i] = piece("nanoPiece" .. i)
end
Spring.SetUnitNanoPieces(unitID, nanoPieces)

function script.QueryBuildInfo()
-- FIXME: the pad piece is named buildPad in the model
return piece("buildPad")
end

local function OpenCloseAnim(open)
Signal(1) -- Kill any other copies of this thread
SetSignalMask(1) -- Allow this thread to be killed by fresh copies
if open then
-- TODO: This is where you would add your opening up anim
else
-- TODO: This is where you would add your closing up anim
end
SetUnitValue(COB.YARD_OPEN, open)
SetUnitValue(COB.BUGGER_OFF, open)
SetUnitValue(COB.INBUILDSTANCE, open)
end

-- Called when factory yard opens
function script.Activate()
-- OpenCloseAnim must be threaded to call Sleep() or WaitFor functions
StartThread(OpenCloseAnim, true)
end

-- Called when factory yard closes
function script.Deactivate()
-- OpenCloseAnim must be threaded to call Sleep() or WaitFor functions
StartThread(OpenCloseAnim, false)
end

function script.StartBuilding()
-- TODO: You can run any animation that continues throughout the build process here e.g. spin pad
end

function script.StopBuilding()
-- TODO: You can run any animation that signifies the end of the build process here
end
</syntaxhighlight>

=== Wind Generator ===
<syntaxhighlight lang="lua">
-- FIXME: Assumes model has pieces named 'tower' and 'blades'
local tower, blades = piece("tower", "blades")

function script.WindChanged (number heading, number strength)
-- Turn the tower to face the wind at 30deg/s
Turn(tower, y_axis, heading, math.rad(30))
-- Spin the turbine blades relative to wind strength
-- FIXME: Here I set rotational speed to half of strength
Spin(blades, z_axis, strength * 0.5)
end
</syntaxhighlight>

[[Category:Animation]]

Animation:LuaExamples

2020-06-09T15:34:17Z

Flozi: /* Script Scaffolds */ Add Air Transport

= LUS Script Examples =

== How to use ==
* <code>FIXME</code> - Indicates a section of code you will need to tweak to suit your own unit / model
* <code>TODO</code> - Indicates an optional section of code is missing that you may wish to pad out e.g. with an animation

== Script Scaffolds ==
=== Air Transport ===
<syntaxhighlight lang="lua">
-- FIXME: This should be whatever piece name you want to attach to in your model
local attachPiece = piece "attach"

-- called for each unit loaded, returns the attaching piece
function script.QueryTransport(passengerID)
return attachPiece
end

-- called for each unit loaded to animate the load process
function script.BeginTransport(passengerID)
-- TODO: any loading animations here
end

--how this is called depends on https://springrts.com/wiki/Gamedev:UnitDefs#transportUnloadMethod
-- 0 (Default) called once on the last unit dropped
-- 1 called for each unit dropped in mid-air
-- 2 called for the last unit dropped
function script.EndTransport(passengerID)
-- TODO: relevant end of transport sequence animations
end

-- Only called if transportUnloadMethod = 2
function script.TransportDrop(passengerID, x,y,z)
-- TODO: animation to unload each individual passenger on the ground
end
</syntaxhighlight>

=== Builder ===
<syntaxhighlight lang="lua">
local nanoPieces = {}
-- FIXME: this example has 2 nano pieces to alternate between
for i = 1, 2 do
-- FIXME: the pieces are named nanoPiece1 and nanoPiece2 in the model
nanoPieces[i] = piece("nanoPiece" .. i)
end
Spring.SetUnitNanoPieces(unitID, nanoPieces)

function script.StartBuilding(heading, pitch)
-- TODO: This is where you would add your unpack / point towards animation
SetUnitValue(COB.INBUILDSTANCE, true)
end
function script.StopBuilding()
-- TODO: This is where you would add your pack-up animation
SetUnitValue(COB.INBUILDSTANCE, false)
end
</syntaxhighlight>

=== Factory ===
<syntaxhighlight lang="lua">
local nanoPieces = {}
-- FIXME: this example has 2 nano pieces to alternate between
for i = 1, 2 do
-- FIXME: the pieces are named nanoPiece1 and nanoPiece2 in the model
nanoPieces[i] = piece("nanoPiece" .. i)
end
Spring.SetUnitNanoPieces(unitID, nanoPieces)

function script.QueryBuildInfo()
-- FIXME: the pad piece is named buildPad in the model
return piece("buildPad")
end

local function OpenCloseAnim(open)
Signal(1) -- Kill any other copies of this thread
SetSignalMask(1) -- Allow this thread to be killed by fresh copies
if open then
-- TODO: This is where you would add your opening up anim
else
-- TODO: This is where you would add your closing up anim
end
SetUnitValue(COB.INBUILDSTANCE, open)
SetUnitValue(COB.BUGGER_OFF, open)
end

-- Called when factory yard opens
function script.Activate()
-- OpenCloseAnim must be threaded to call Sleep() or WaitFor functions
StartThread(OpenCloseAnim, true)
end

-- Called when factory yard closes
function script.Deactivate()
-- OpenCloseAnim must be threaded to call Sleep() or WaitFor functions
StartThread(OpenCloseAnim, false)
end

function script.StartBuilding()
-- TODO: You can run any animation that continues throughout the build process here e.g. spin pad
end

function script.StopBuilding()
-- TODO: You can run any animation that signifies the end of the build process here
end
</syntaxhighlight>

=== Wind Generator ===
<syntaxhighlight lang="lua">
-- FIXME: Assumes model has pieces named 'tower' and 'blades'
local tower, blades = piece("tower", "blades")

function script.WindChanged (number heading, number strength)
-- Turn the tower to face the wind at 30deg/s
Turn(tower, y_axis, heading, math.rad(30))
-- Spin the turbine blades relative to wind strength
-- FIXME: Here I set rotational speed to half of strength
Spin(blades, z_axis, strength * 0.5)
end
</syntaxhighlight>

[[Category:Animation]]

Template:Xtaglink

2020-06-02T17:55:12Z

Flozi: update xtaglink for changed anchors

{{#css:
span.mono {
font-family: courier, monospace;
}
span.value {
color: #ff6600;
}
}}<includeonly>[[{{{1}}}#{{{2}}}|{{{var|{{{2}}}}}}]]{{#if: {{{3|}}}| = {{value|{{{3}}}}}|}}</includeonly><noinclude>
A template to simplify cross-referencing definition [[Template:Tag|tags]] between different pages. Use [[Template:Taglink]] for links to tags within the same page.

Usage:

<pre>{{xtaglink|Gamedev:UnitDefs|builder}}</pre>

Result:

{{xtaglink|Gamedev:UnitDefs|builder}}

Usage (Optional 3rd param to link to a tag with a given value):

<pre>{{xtaglink|Gamedev:UnitDefs|builder|true}}</pre>

Result:
{{xtaglink|Gamedev:UnitDefs|builder|true}}

N.B. Please do not use this tag ''within'' a <nowiki><code></nowiki> block when documenting a formula tags are used in - it will break the markup and is confusing. See [[Gamedev:WeaponDefs#Tag:burstRate]] for an example of the proper usage in this case.
</noinclude>

Template:Taglink

2020-06-02T17:54:55Z

Flozi: update taglink for changed anchors

{{#css:
span.mono {
font-family: courier, monospace;
}
span.value {
color: #ff6600;
}
}}<includeonly>[[#{{{1}}}|{{{var|{{{1}}}}}}]]{{#if: {{{2|}}}| = {{value|{{{2}}}}}|}}</includeonly><noinclude>
A template to simplify cross-referencing definition [[Template:Tag|tags]] (currently only within a page).

Usage:

<pre>{{taglink|foo}}</pre>

Result:

{{taglink|foo}}

Usage (Optional 2nd param to link to a tag with a given value):

<pre>{{taglink|foo|bar}}</pre>

Result:
{{taglink|foo|bar}}

N.B. Please do not use this tag ''within'' a <nowiki><code></nowiki> block when documenting a formula tags are used in - it will break the markup and is confusing. See [[Gamedev:WeaponDefs#Tag:burstRate]] for an example of the proper usage in this case.
</noinclude>

Gamedev:DebugDrawModes

2020-05-28T12:04:59Z

Flozi: /* /DebugColVol (alt+v) */

= Debug Drawing Modes =
Spring has several drawing modes which are useful for debugging and performance checking.
They are listed below by [[UI commands]] with their default key binding.

== /Debug (alt+b) ==
[[File:Debug.jpg|400px|left|/Debug]]
Draws a toggleable list of engine functions and a breakdown of how much time is spent computing them. When toggled on a line graph is drawn to illustrate the change in performance over time.

Since 97.0 there is a new '''Frame Grapher''' visualisation which shows how the last half-second was spent:

* Green are video frames
* Red are simframes
* Blue is swapBuffer (gpu/vsync)
* Pink is lua gc
 

== /DebugColVol (alt+v) ==
[[File:DebugColVol.jpg|400px|left|/DebugColVol]]
Draws unit and feature [[Gamedev:CollisionVolumes|collision volumes]] as purple meshes. When hit by a weapon the meshes turn red. Since 99.0 weapon debug spheres are also drawn in this mode for the [[Animation-LuaCallins#Weapons|AimFromWeapon()]] position, [[Animation-LuaCallins#Weapons|QueryWeapon()]] (muzzle) position and unit target position. Shields spheres are drawn in blue.
 

== /DebugPath (alt+p) ==
[[File:DebugPath_Close.jpg|400px|left|/DebugPath Close up view]][[File:DebugPath_Far.jpg|400px|left|/DebugPath Far out view]]

Draws pathfinder routes, colour coded by accuracy.

* Red is the most finely computed pathing
* Green is intermediate paths
* Blue is least accurate long range path
 

== /DebugTraceRay ==
It is meant for debugging trajectories of ballistic projectiles. [https://springrts.com/mantis/view.php?id=4664 Currently broken in 98.0]

 

== /DebugDrawAI ==
[[File:DebugDrawAI_E232AI.jpg|400px|left|/DebugDrawAI implemented in E232AI]]
This mode is toggled through the engine but is up to the native AI to implement itself. The image shows how [[AI:Skirmish:List|E232AI]] implements a real-time threatmap rendering and a real-time performance profiler.

[[Category: Game Dev]]

Template:API

2020-03-28T18:43:36Z

Flozi: make name linkable

<includeonly>{{prefix|{{{prefix}}}}}{{name|{{anchor|{{{name}}}}}[[#{{{name}}}|{{{name}}}]]}}{{var|1=({{{args}}})}}{{#if: {{{return|}}}| return: {{var|1={{{return}}}}}|}}{{#if: {{{output|}}}|{{var|1= -> {{{output}}}}}|}}

:{{{info}}}
</includeonly><noinclude>

<pre>
{{API 
|prefix = Spring
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|output = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Imposes a one-off usage of resources on the given team. The return value indicates whether or not the team had sufficient resources to meet the usage demand.
}}</pre>

{{prefix|Spring.}}{{name|UseTeamResource}}{{var|1=({{type|number}} teamID, {{type|string}} {{value|"metal"}} {{pipe}} {{value|"energy"}}, {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount })}}

{{var|-> {{type|nil}} {{pipe}} {{type|bool}} hadEnough}}

:Deduct the specified amount from the team's metal or energy resource.

User:Flozi

2020-03-28T18:26:02Z

Flozi: /* test */

= My User Subpages =
{{Special:PrefixIndex/User:Flozi/}}

= Scratchpad =

== Template:API proposal ==
Note that the number of 'arg1' etc is fixed (i.e. 10) but can be omitted without issue. the 'type' template is just a way to make inserting different styles within the param list easier, [[Template:Pipe]] already exists and is required as it is a special char within mediawiki syntax, could use <nowiki>{{!}}</nowiki> as a shorter alternative to pipe.
<pre>
{{API 
|prefix = Spring
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|output = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Imposes a one-off usage of resources on the given team. The return value indicates whether or not the team had sufficient resources to meet the usage demand.
}}</pre>

{{prefix|Spring.}}{{name|[[#UseTeamResource|UseTeamResource]]}}{{var|1=({{type|number}} teamID, {{type|string}} {{value|"metal"}} {{pipe}} {{value|"energy"}}, {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount })}}

{{var|-> {{type|nil}} {{pipe}} {{type|bool}} hadEnough}}

:Deduct the specified amount from the team's metal or energy resource.

{{prefix|Spring.}}{{name|CreateUnit}}{{var|1=( {{type|string}} "defName" {{pipe}} number unitDefID, {{type|number}} x, {{type|number}} y, {{type|number z}},
({{type|number}} facing {{pipe}} {{type|string}} "facing"),
{{type|number}} teamID
[, {{type|boolean}} build = {{value|false}}]
[, {{type|boolean}} flattenGround = {{value|true}}]
[, {{type|number}} unitID]
[, {{type|number}} builderID ])}}

{{var|-> {{type|number}} unitID {{pipe}} {{type|nil}}}}

<pre>
{{API 
|prefix = addon 
|name = AllowUnitTransfer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} unitDefID
|arg3 = {{type|number}} oldTeam
|arg4 = {{type|number}} newTeam
|arg5 = {{type|bool}} capture
|return = {{type|bool}} allow 
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}</pre>

{{prefix|addon.}}{{name|AllowUnitTransfer}}{{var|1=({{type|number}} unitID, {{type|number}} unitDefID, {{type|number}} oldTeam,
{{type|number}} newTeam, {{type|bool}} capture)}}

return: {{var|{{type|bool}} allow}}

:Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.

=== Using syntaxhighlight instead ===

<syntaxhighlight lang="c">Spring.CreateUnit // offmap positions are clamped! (you still can use MoveCtrl todo so)
( string "defName" | int unitDefID,
int x, int y, int z,
(int facing | string "facing"),
int teamID
[, bool build = false]
[, bool flattenGround = true]
[, int unitID]
[, int builderID]) -> int unitID | nil</syntaxhighlight>

= TODO: =

==Major==
* [[:Category:ShowCase]] template, main page, S44 & MCL as examples
* [[:Category:Tutorial]]
* Continue to improve [[Lua:Callins]] - Fill in blank explanations
* Clickable / right-click copy paste-able anchors in <nowiki>{{tag}}</nowiki> et al
* [[Assimp]] build upon, metadata doc, split tutorial again >_>
* Cleanup old [[:Category:Map_making]] into new [[:Category:Map Dev]]

==Minor==
* Page on spring wiki etiquette ([[SpringWiki]]) / style guide & template usage ([[Mapdev:WikiGuide]]) /namespace conventions ([[Spring:PageNamingConventions]]) - pages are good already; put these in revamped community portal?
* Move all pages in [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation-&namespace=0 Animation-] to [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation%3A&namespace=0 Animation:]
* Continue to improve [[Gamedev:Main]] up to the high standard of [[Mapdev:Main]]

==Undocumented Features==
* cmdcolors.txt (c.f. {{forumlink|topic=7099|title=GUI modifications in SVN}})
* ctrlpanel.txt (c.f. as above)
* isolated mode (isolated.txt 99+ c.f. {{forumlink|topic=26359|title=portable/isolation mode}}, [http://springrts.com/dl/buildbot/default/master/99.0/manpages/spring.6.html Spring manpages])

Template:Tag

2020-03-28T18:24:37Z

Flozi:

<includeonly>{{type|{{{type|type}}}}} {{name|{{anchor|{{{name|name}}}}}[[#{{{name|name}}}|{{{name|name}}}]]}} &emsp;default: {{value|{{{default|?}}}}}{{#if: {{{range|}}}|&emsp;range: {{value|{{{range|}}}}}|}}{{#if: {{{lua|}}}|&emsp;lua: {{var|{{{lua|}}}}}|}}&emsp;{{{special|}}}
: {{{description|{{FIXME}}}}}</includeonly><noinclude>A template for documenting various tags used in the engine (gamedata files, defs etc)

'''Usage:'''
<pre>{{tag}}</pre>
result:
{{tag}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|default=10|description=Then type your description}}

'''Usage:'''
<pre>{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}</pre>
Result:
{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}

</noinclude>

Template:Tag

2020-03-28T18:24:07Z

Flozi:

<includeonly>{{type|{{{type|type}}}}} {{name|{{anchor|{{{name|name}}}}}[[{{{name|name}}}]]}} &emsp;default: {{value|{{{default|?}}}}}{{#if: {{{range|}}}|&emsp;range: {{value|{{{range|}}}}}|}}{{#if: {{{lua|}}}|&emsp;lua: {{var|{{{lua|}}}}}|}}&emsp;{{{special|}}}
: {{{description|{{FIXME}}}}}</includeonly><noinclude>A template for documenting various tags used in the engine (gamedata files, defs etc)

'''Usage:'''
<pre>{{tag}}</pre>
result:
{{tag}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|default=10|description=Then type your description}}

'''Usage:'''
<pre>{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}</pre>
Result:
{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}

</noinclude>

Template:Tag

2020-03-28T18:23:24Z

Flozi:

<includeonly>{{type|{{{type|type}}}}} {{name|{{anchor|{{{name|name}}}}}[[#{{{name|name}}}]]}} &emsp;default: {{value|{{{default|?}}}}}{{#if: {{{range|}}}|&emsp;range: {{value|{{{range|}}}}}|}}{{#if: {{{lua|}}}|&emsp;lua: {{var|{{{lua|}}}}}|}}&emsp;{{{special|}}}
: {{{description|{{FIXME}}}}}</includeonly><noinclude>A template for documenting various tags used in the engine (gamedata files, defs etc)

'''Usage:'''
<pre>{{tag}}</pre>
result:
{{tag}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|default=10|description=Then type your description}}

'''Usage:'''
<pre>{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}</pre>
Result:
{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}

</noinclude>

Template:Anchor

2020-03-28T17:27:16Z

Flozi: Undo revision 31203 by Flozi (talk)

<noinclude>

A small template to manually create an anchor link, see http://meta.wikimedia.org/wiki/Template:Anchor

Usage:

<pre>{{anchor|foo}}</pre>

Creates an invisible anchor which you can link to within the page as <pre>[[#foo]]</pre> or externally by <pre>[[page_name#foo]]</pre>

User:Flozi

2020-03-28T17:21:31Z

Flozi: /* test */

Template:Tag

2020-03-28T17:15:54Z

Flozi:

<includeonly>{{type|{{{type|type}}}}} {{name|{{anchor|{{{name|name|name}}}}}{{{name|name}}}}} &emsp;default: {{value|{{{default|?}}}}}{{#if: {{{range|}}}|&emsp;range: {{value|{{{range|}}}}}|}}{{#if: {{{lua|}}}|&emsp;lua: {{var|{{{lua|}}}}}|}}&emsp;{{{special|}}}
: {{{description|{{FIXME}}}}}</includeonly><noinclude>A template for documenting various tags used in the engine (gamedata files, defs etc)

'''Usage:'''
<pre>{{tag}}</pre>
result:
{{tag}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|default=10|description=Then type your description}}

'''Usage:'''
<pre>{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}</pre>
Result:
{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}

</noinclude>

Template:Tag

2020-03-28T16:35:04Z

Flozi:

Template:Tag

2020-03-28T16:34:26Z

Flozi:

<includeonly>{{type|{{{type|type}}}}} {{name|[[#{{anchor|{{{name|name}}}}}{{{name|name}}}]]}} &emsp;default: {{value|{{{default|?}}}}}{{#if: {{{range|}}}|&emsp;range: {{value|{{{range|}}}}}|}}{{#if: {{{lua|}}}|&emsp;lua: {{var|{{{lua|}}}}}|}}&emsp;{{{special|}}}
: {{{description|{{FIXME}}}}}</includeonly><noinclude>A template for documenting various tags used in the engine (gamedata files, defs etc)

'''Usage:'''
<pre>{{tag}}</pre>
result:
{{tag}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|default=10|description=Then type your description}}

'''Usage:'''
<pre>{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}</pre>
Result:
{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}

</noinclude>

Template:Tag

2020-03-28T16:01:52Z

Flozi:

<includeonly>{{type|{{{type|type}}}}} [[#{{name|{{anchor|{{{name|name}}}}}{{{name|name}}}}}]] &emsp;default: {{value|{{{default|?}}}}}{{#if: {{{range|}}}|&emsp;range: {{value|{{{range|}}}}}|}}{{#if: {{{lua|}}}|&emsp;lua: {{var|{{{lua|}}}}}|}}&emsp;{{{special|}}}
: {{{description|{{FIXME}}}}}</includeonly><noinclude>A template for documenting various tags used in the engine (gamedata files, defs etc)

'''Usage:'''
<pre>{{tag}}</pre>
result:
{{tag}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|range=[0-100]|special=Required|default=10|description=Then type your description}}
'''Usage:'''
<pre>{{tag|name=foo|type=int|default=10|description=Then type your description}}</pre>
Result:
{{tag|name=foo|type=int|default=10|description=Then type your description}}

'''Usage:'''
<pre>{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}</pre>
Result:
{{tag
|name = bar
|type = float
|range = [0-100]
|default = 3.14
|special = {{new|88.0}}
|description = Then your description}}

</noinclude>

Template:Tag

2020-03-28T16:00:30Z

Flozi:

Template:Anchor

2020-03-28T15:50:17Z

Flozi:

{{{1|}}}<noinclude>

A small template to manually create an anchor link, see http://meta.wikimedia.org/wiki/Template:Anchor

Usage:

<pre>{{anchor|foo}}</pre>
<pre>{{anchor|foo|bar}}</pre>

Creates an invisible anchor which you can link to within the page as <pre>[[#foo]]</pre> or externally by <pre>[[page_name#foo]]</pre>

User:Flozi

2020-03-28T13:55:52Z

Flozi: hmmmm

User:Flozi

2020-03-28T13:50:36Z

Flozi: testing linked names in tag / api

MediaWiki:Sidebar

2020-03-03T20:38:22Z

Flozi: capitalise

MediaWiki:Sidebar

2020-03-03T20:35:50Z

Flozi: google site search

Movedefs.lua

2019-08-29T11:12:28Z

Flozi: flow :/

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

=== Flow Field Tags ===
These tags are used in unit avoidance.

{{tag
|name = flowMapping
|type = bool
|default = true
|description = This enables/disables [https://leifnode.com/2013/12/flow-field-pathfinding/ flow field mapping].
}}

{{tag
|name = flowMod
|type = float
|default = 1.0
|description = Multiplied by the objects {{xtaglink|Gamedev:UnitDefs|mass}} for the y-component (up) of the flow vector. No idea what effect this has.
}}

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

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

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

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

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

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

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

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

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

{{tag
|name = maxScale
|type = float
|default = MAX_FLOAT
|description = This is the cap on how severe the depth effect can be. 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]]

Modrules.lua

2019-04-21T20:32:40Z

Flozi: /* los */ fix heading level

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Examples==

===Empty===

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

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

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

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

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

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

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

[[Category:gamedata]]

Animation:LuaExamples

2018-10-21T17:02:04Z

Flozi: /* LUS Script Examples */ <code> -> <syntaxhighlight lang="lua">

= LUS Script Examples =

== How to use ==
* <code>FIXME</code> - Indicates a section of code you will need to tweak to suit your own unit / model
* <code>TODO</code> - Indicates an optional section of code is missing that you may wish to pad out e.g. with an animation

== Script Scaffolds ==
=== Builder ===
<syntaxhighlight lang="lua">
local nanoPieces = {}
-- FIXME: this example has 2 nano pieces to alternate between
for i = 1, 2 do
-- FIXME: the pieces are named nanoPiece1 and nanoPiece2 in the model
nanoPieces[i] = piece("nanoPiece" .. i)
end
Spring.SetUnitNanoPieces(unitID, nanoPieces)

function script.StartBuilding(heading, pitch)
-- TODO: This is where you would add your unpack / point towards animation
SetUnitValue(COB.INBUILDSTANCE, true)
end
function script.StopBuilding()
-- TODO: This is where you would add your pack-up animation
SetUnitValue(COB.INBUILDSTANCE, false)
end
</syntaxhighlight>

=== Factory ===
<syntaxhighlight lang="lua">
local nanoPieces = {}
-- FIXME: this example has 2 nano pieces to alternate between
for i = 1, 2 do
-- FIXME: the pieces are named nanoPiece1 and nanoPiece2 in the model
nanoPieces[i] = piece("nanoPiece" .. i)
end
Spring.SetUnitNanoPieces(unitID, nanoPieces)

function script.QueryBuildInfo()
-- FIXME: the pad piece is named buildPad in the model
return piece("buildPad")
end

local function OpenCloseAnim(open)
Signal(1) -- Kill any other copies of this thread
SetSignalMask(1) -- Allow this thread to be killed by fresh copies
if open then
-- TODO: This is where you would add your opening up anim
else
-- TODO: This is where you would add your closing up anim
end
SetUnitValue(COB.INBUILDSTANCE, open)
SetUnitValue(COB.BUGGER_OFF, open)
end

-- Called when factory yard opens
function script.Activate()
-- OpenCloseAnim must be threaded to call Sleep() or WaitFor functions
StartThread(OpenCloseAnim, true)
end

-- Called when factory yard closes
function script.Deactivate()
-- OpenCloseAnim must be threaded to call Sleep() or WaitFor functions
StartThread(OpenCloseAnim, false)
end

function script.StartBuilding()
-- TODO: You can run any animation that continues throughout the build process here e.g. spin pad
end

function script.StopBuilding()
-- TODO: You can run any animation that signifies the end of the build process here
end
</syntaxhighlight>

=== Wind Generator ===
<syntaxhighlight lang="lua">
-- FIXME: Assumes model has pieces named 'tower' and 'blades'
local tower, blades = piece("tower", "blades")

function script.WindChanged (number heading, number strength)
-- Turn the tower to face the wind at 30deg/s
Turn(tower, y_axis, heading, math.rad(30))
-- Spin the turbine blades relative to wind strength
-- FIXME: Here I set rotational speed to half of strength
Spin(blades, z_axis, strength * 0.5)
end
</syntaxhighlight>

[[Category:Animation]]

User:Flozi

2018-01-05T22:51:04Z

Flozi: /* Template:API proposal */ or use syntaxhighlight with c ?

= My User Subpages =
{{Special:PrefixIndex/User:Flozi/}}

= Scratchpad =

== Template:API proposal ==
Note that the number of 'arg1' etc is fixed (i.e. 10) but can be omitted without issue. the 'type' template is just a way to make inserting different styles within the param list easier, [[Template:Pipe]] already exists and is required as it is a special char within mediawiki syntax, could use <nowiki>{{!}}</nowiki> as a shorter alternative to pipe.
<pre>
{{API 
|prefix = Spring
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|output = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Imposes a one-off usage of resources on the given team. The return value indicates whether or not the team had sufficient resources to meet the usage demand.
}}</pre>

{{prefix|Spring.}}{{name|UseTeamResource}}{{var|1=({{type|number}} teamID, {{type|string}} {{value|"metal"}} {{pipe}} {{value|"energy"}}, {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount })}}

{{var|-> {{type|nil}} {{pipe}} {{type|bool}} hadEnough}}

:Deduct the specified amount from the team's metal or energy resource.

{{prefix|Spring.}}{{name|CreateUnit}}{{var|1=( {{type|string}} "defName" {{pipe}} number unitDefID, {{type|number}} x, {{type|number}} y, {{type|number z}},
({{type|number}} facing {{pipe}} {{type|string}} "facing"),
{{type|number}} teamID
[, {{type|boolean}} build = {{value|false}}]
[, {{type|boolean}} flattenGround = {{value|true}}]
[, {{type|number}} unitID]
[, {{type|number}} builderID ])}}

{{var|-> {{type|number}} unitID {{pipe}} {{type|nil}}}}

<pre>
{{API 
|prefix = addon 
|name = AllowUnitTransfer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} unitDefID
|arg3 = {{type|number}} oldTeam
|arg4 = {{type|number}} newTeam
|arg5 = {{type|bool}} capture
|return = {{type|bool}} allow 
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}</pre>

{{prefix|addon.}}{{name|AllowUnitTransfer}}{{var|1=({{type|number}} unitID, {{type|number}} unitDefID, {{type|number}} oldTeam,
{{type|number}} newTeam, {{type|bool}} capture)}}

return: {{var|{{type|bool}} allow}}

:Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.

=== Using syntaxhighlight instead ===

<syntaxhighlight lang="c">Spring.CreateUnit // offmap positions are clamped! (you still can use MoveCtrl todo so)
( string "defName" | int unitDefID,
int x, int y, int z,
(int facing | string "facing"),
int teamID
[, bool build = false]
[, bool flattenGround = true]
[, int unitID]
[, int builderID]) -> int unitID | nil</syntaxhighlight>

= TODO: =

==Major==
* [[:Category:ShowCase]] template, main page, S44 & MCL as examples
* [[:Category:Tutorial]]
* Continue to improve [[Lua:Callins]] - Fill in blank explanations
* Clickable / right-click copy paste-able anchors in <nowiki>{{tag}}</nowiki> et al
* [[Assimp]] build upon, metadata doc, split tutorial again >_>
* Cleanup old [[:Category:Map_making]] into new [[:Category:Map Dev]]

==Minor==
* Page on spring wiki etiquette ([[SpringWiki]]) / style guide & template usage ([[Mapdev:WikiGuide]]) /namespace conventions ([[Spring:PageNamingConventions]]) - pages are good already; put these in revamped community portal?
* Move all pages in [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation-&namespace=0 Animation-] to [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation%3A&namespace=0 Animation:]
* Continue to improve [[Gamedev:Main]] up to the high standard of [[Mapdev:Main]]

==Undocumented Features==
* cmdcolors.txt (c.f. {{forumlink|topic=7099|title=GUI modifications in SVN}})
* ctrlpanel.txt (c.f. as above)
* isolated mode (isolated.txt 99+ c.f. {{forumlink|topic=26359|title=portable/isolation mode}}, [http://springrts.com/dl/buildbot/default/master/99.0/manpages/spring.6.html Spring manpages])

User:Flozi

2018-01-05T22:42:00Z

Flozi: /* Template:API proposal */ check how ugly this style is with something with long params list like CreateUnit (ugly :( )

= My User Subpages =
{{Special:PrefixIndex/User:Flozi/}}

= Scratchpad =

== Template:API proposal ==
Note that the number of 'arg1' etc is fixed (i.e. 10) but can be omitted without issue. the 'type' template is just a way to make inserting different styles within the param list easier, [[Template:Pipe]] already exists and is required as it is a special char within mediawiki syntax, could use <nowiki>{{!}}</nowiki> as a shorter alternative to pipe.
<pre>
{{API 
|prefix = Spring
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|output = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Imposes a one-off usage of resources on the given team. The return value indicates whether or not the team had sufficient resources to meet the usage demand.
}}</pre>

{{prefix|Spring.}}{{name|UseTeamResource}}{{var|1=({{type|number}} teamID, {{type|string}} {{value|"metal"}} {{pipe}} {{value|"energy"}}, {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount })}}

{{var|-> {{type|nil}} {{pipe}} {{type|bool}} hadEnough}}

:Deduct the specified amount from the team's metal or energy resource.

{{prefix|Spring.}}{{name|CreateUnit}}{{var|1=( {{type|string}} "defName" {{pipe}} number unitDefID, {{type|number}} x, {{type|number}} y, {{type|number z}},
({{type|number}} facing {{pipe}} {{type|string}} "facing"),
{{type|number}} teamID
[, {{type|boolean}} build = {{value|false}}]
[, {{type|boolean}} flattenGround = {{value|true}}]
[, {{type|number}} unitID]
[, {{type|number}} builderID ])}}

{{var|-> {{type|number}} unitID {{pipe}} {{type|nil}}}}

<pre>
{{API 
|prefix = addon 
|name = AllowUnitTransfer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} unitDefID
|arg3 = {{type|number}} oldTeam
|arg4 = {{type|number}} newTeam
|arg5 = {{type|bool}} capture
|return = {{type|bool}} allow 
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}</pre>

{{prefix|addon.}}{{name|AllowUnitTransfer}}{{var|1=({{type|number}} unitID, {{type|number}} unitDefID, {{type|number}} oldTeam,
{{type|number}} newTeam, {{type|bool}} capture)}}

return: {{var|{{type|bool}} allow}}

:Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.

= TODO: =

==Major==
* [[:Category:ShowCase]] template, main page, S44 & MCL as examples
* [[:Category:Tutorial]]
* Continue to improve [[Lua:Callins]] - Fill in blank explanations
* Clickable / right-click copy paste-able anchors in <nowiki>{{tag}}</nowiki> et al
* [[Assimp]] build upon, metadata doc, split tutorial again >_>
* Cleanup old [[:Category:Map_making]] into new [[:Category:Map Dev]]

==Minor==
* Page on spring wiki etiquette ([[SpringWiki]]) / style guide & template usage ([[Mapdev:WikiGuide]]) /namespace conventions ([[Spring:PageNamingConventions]]) - pages are good already; put these in revamped community portal?
* Move all pages in [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation-&namespace=0 Animation-] to [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation%3A&namespace=0 Animation:]
* Continue to improve [[Gamedev:Main]] up to the high standard of [[Mapdev:Main]]

==Undocumented Features==
* cmdcolors.txt (c.f. {{forumlink|topic=7099|title=GUI modifications in SVN}})
* ctrlpanel.txt (c.f. as above)
* isolated mode (isolated.txt 99+ c.f. {{forumlink|topic=26359|title=portable/isolation mode}}, [http://springrts.com/dl/buildbot/default/master/99.0/manpages/spring.6.html Spring manpages])

User:Flozi

2018-01-03T18:25:38Z

Flozi: remove some crap

= My User Subpages =
{{Special:PrefixIndex/User:Flozi/}}

= Scratchpad =

== Template:API proposal ==
Note that the number of 'arg1' etc is fixed (i.e. 10) but can be omitted without issue. the 'type' template is just a way to make inserting different styles within the param list easier, [[Template:Pipe]] already exists and is required as it is a special char within mediawiki syntax, could use <nowiki>{{!}}</nowiki> as a shorter alternative to pipe.
<pre>
{{API 
|prefix = Spring
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|output = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Imposes a one-off usage of resources on the given team. The return value indicates whether or not the team had sufficient resources to meet the usage demand.
}}</pre>

{{prefix|Spring.}}{{name|UseTeamResource}}{{var|1=({{type|number}} teamID, {{type|string}} {{value|"metal"}} {{pipe}} {{value|"energy"}}, {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount })}}

{{var|-> {{type|nil}} {{pipe}} {{type|bool}} hadEnough}}

:Deduct the specified amount from the team's metal or energy resource.

vs.

<pre>
{{API 
|prefix = addon 
|name = AllowUnitTransfer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} unitDefID
|arg3 = {{type|number}} oldTeam
|arg4 = {{type|number}} newTeam
|arg5 = {{type|bool}} capture
|return = {{type|bool}} allow 
|info = Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.
}}</pre>

{{prefix|addon.}}{{name|AllowUnitTransfer}}{{var|1=({{type|number}} unitID, {{type|number}} unitDefID, {{type|number}} oldTeam,
{{type|number}} newTeam, {{type|bool}} capture)}}

return: {{var|{{type|bool}} allow}}

:Called just before a unit is transferred to a different team, the boolean return value determines whether or not the transfer is permitted.

= TODO: =

==Major==
* [[:Category:ShowCase]] template, main page, S44 & MCL as examples
* [[:Category:Tutorial]]
* Continue to improve [[Lua:Callins]] - Fill in blank explanations
* Clickable / right-click copy paste-able anchors in <nowiki>{{tag}}</nowiki> et al
* [[Assimp]] build upon, metadata doc, split tutorial again >_>
* Cleanup old [[:Category:Map_making]] into new [[:Category:Map Dev]]

==Minor==
* Page on spring wiki etiquette ([[SpringWiki]]) / style guide & template usage ([[Mapdev:WikiGuide]]) /namespace conventions ([[Spring:PageNamingConventions]]) - pages are good already; put these in revamped community portal?
* Move all pages in [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation-&namespace=0 Animation-] to [http://springrts.com/mediawiki/index.php?title=Special%3APrefixIndex&prefix=Animation%3A&namespace=0 Animation:]
* Continue to improve [[Gamedev:Main]] up to the high standard of [[Mapdev:Main]]

==Undocumented Features==
* cmdcolors.txt (c.f. {{forumlink|topic=7099|title=GUI modifications in SVN}})
* ctrlpanel.txt (c.f. as above)
* isolated mode (isolated.txt 99+ c.f. {{forumlink|topic=26359|title=portable/isolation mode}}, [http://springrts.com/dl/buildbot/default/master/99.0/manpages/spring.6.html Spring manpages])

Lua Libraries

2017-12-26T12:56:47Z

Flozi: /* Single file libraries */ MCL vector library is extended from s44

=Lua libraries=
This page lists all common Lua libraries that can be used in Spring game and map archives.

If you want to extend this page, please only add working, well-documented libraries and frameworks, and their official links.
It's possible to add early work, but try to make sure it has some documentation, and keep it in its separate repository.

Libraries:
* [https://github.com/jk3064/chiliui ChiliUI]: UI framework [[Chili | docs]]
* [https://github.com/jk3064/lups LUPS]: Lua Particle System for Spring [[LUPS | docs]]
* [https://github.com/jk3064/Custom-Unit-Shader-Framework Custom Unit Shader Framework]: Unit rendering with shaders
* [https://github.com/gajop/liblobby LibLobby]: Spring Lobby protocol library
* [https://github.com/gajop/i18n i18n]: Translations library
* [https://github.com/gajop/Lua-Class-System LCS]: OOP (classes) in Lua
* [https://github.com/gajop/analytics analytics]: Usage analytics reporting [WIP]
* [https://github.com/gajop/chilifx ChiliFX]: Chili effects [WIP]
* [https://github.com/gajop/chotify Chotify]: Notification library in Chili [WIP]

==Single file libraries==
There is also a number of single file libraries that don't have their own repository but can technically still be considered libraries.

Library files:
* [https://github.com/SpringMCLegacy/SpringMCLegacy/blob/master/LuaRules/Gadgets/api_vector.lua Vector]: Small utility for vector operations
* [https://github.com/gajop/liblobby/blob/master/lobby/json.lua JSON]: Serializing to the JSON format
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Gadgets/api_delay.lua Delay]: Delaying gadget calls
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/network.lua Network]: Delta compression for binary strings
* [https://github.com/spring1944/spring1944/blob/master/LuaRules/Includes/camera.lua Camera]: Camera state serialization
* Deferred rendering [http://imolarpg.dyndns.org/svn/branches/BAR/shaders/deferred_lighting.glsl Shader] & [http://imolarpg.dyndns.org/svn/branches/BAR/luaui/widgets/gfx_deferred_rendering.lua Widget]: Deferred rendering (projectile) based lights

[[Category:Lua]] [[Category:Libraries]]

LuaCallinReturn

2017-12-26T12:24:19Z

Flozi: category lua - > deprecated, use Lua:Callins instead

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

==Engine Source==
If you can understand Lua code well and wish to get the most up to date info, you can refer to:
{{sourcelink|file=cont/base/springcontent/LuaGadgets/actions.lua}},
{{sourcelink|file=cont/LuaUI/widgets.lua}} and 
{{sourcelink|file=cont/base/springcontent/LuaGadgets/gadgets.lua}} 
to see how widget/gadget call-ins are distributed, find call-in and widgetHandler function definitions, see how they are processed and what values should be returned from some call ins
(are these the only files?)

==What is a callin anyway?==
Call-ins are calls from the engine, into the gadget or widget script. In other words, these functions are called when a particular ''event'' happens.
Some call-in functions can return values to the engine.
===Blocking events with return values===
The call-in functions named '''''Allow'''''XXX can block their event by returning ''false''. 
For example ''AllowUnitTransfer()'' 
<code>return true</code> = allow transfer 
<code>return false</code> = deny transfer

==Commands, general-purpose:==

Initialize() --> none. 
called when widget/gadget gets (re-)loaded.

Shutdown() --> none.

PlayerChanged --> (playerID).
gadget/widget: Use this to check whether a player has become spectator for instance.

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

CommandNotify() --> "id, params, options", where id = the CommandID

KeyPress() --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

KeyRelease() --> "key"

MouseMove() --> "x, y, dx, dy, button"

MousePress() --> "x, y, button" 
button parameter values: left - 1, middle - 2, right - 3

{{new|>96.0}} buttom param removed {{Sourcelinkhash|4c104344e92256e33d79820e9012c5e1178e212b}}

MouseRelease() --> "x, y, button" 
Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same widget that returns true.

MouseWheel() --> "up, value"

IsAbove() --> "x, y" where x,y = screen coordinates.

GetTooltip() --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

AddConsoleLine() --> "msg, priority"

MapDrawCmd() --> "playerID, cmdType, px, py, pz, labeltext"

AllowCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

CommandFallback() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

CommandsChanged() --> unknown (none?)

AllowUnitCreation() --> "unitDefID, builderID, builderTeam, x, y, z, facing"

AllowUnitTransfer() --> "unitID, unitDefID, oldTeam, newTeam, capture"

AllowUnitBuildStep() --> "builderID, builderTeam, unitID, unitDefID, part"

AllowFeatureCreation() --> "featureDefID, teamID, x, y, z"

AllowFeatureBuildStep() --> unknown, please document.

AllowResourceLevel() --> "teamID, res, level"

AllowResourceTransfer() --> "teamID, res, level"

Update() --> "dt" 
called every screenframe. dt is the time since the last screenframe

DefaultCommand() --> "type,id" 
can return an [[Lua_CMDs|CMD]] to change cursor and command. {{forumlink|topic=26438|title=example usage}}

AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID) -> allowFpsControl 
''return true'' allows fps mode, ''return false'' blocks it.

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, attackerID, attackerDefID, attackerTeam" (prior to 94.0)

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" (as of 94.0)

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" (as of 95.0) 
Can overwrite the taken damage by returning a new number value. 

As of 88.0 for both UnitDamaged and UnitPreDamaged:
weaponDefID -1 --> debris collision
weaponDefID -2 --> ground collision
weaponDefID -3 --> object collision
weaponDefID -4 --> fire damage
weaponDefID -5 --> water damage
weaponDefID -6 --> kill damage
weaponDefID -7 --> crush damage

As of 96.0 {Unit,Feature}{Pre}Damaged events receive the 'attacker' ID when object is crushed

UnitExperience() --> "unitID, unitDefID, unitTeam, experience, oldExperience" 
Spring.SetExperienceGrade must be called first to determine how often it is called

UnitCreated() --> "unitID, unitDefID, teamID, builderID"

UnitFinished() --> "unitID, unitDefID, teamID"

UnitFromFactory() --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

UnitDestroyed() --> "unitID, unitDefID, teamID, attackerID, attackerDefID, attackerTeamID"

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam" 
Unit still belongs to old team

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam" 
Unit now belongs to new team

UnitIdle() --> "unitID, unitDefID, teamID"

UnitCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams, cmdTag" (cmdTag only available from version 95.0)

UnitSeismicPing() --> "x, y, z, strength"

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

UnitLeftLos() --> "unitID, unitDefID, teamID"

UnitLoaded() --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

UnitUnloaded() --> "unitID, unitDefID, teamID, transportID"

UnitCloaked() --> "unitID, unitDefID, teamID"

UnitDecloaked)--> "unitID, unitDefID, teamID"

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"
 Only called for unitDefIDs registered via [[Lua_System#Synced|Script.SetWatchUnit]] since 85.0

StockpileChanged() --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

UnitEnteredWater() --> "unitID, unitDefID, teamID"
(as of 95.0)

UnitEnteredAir() --> "unitID, unitDefID, teamID"
(as of 95.0)

UnitLeftWater() --> "unitID, unitDefID, teamID"
(as of 95.0)

UnitLeftAir() --> "unitID, unitDefID, teamID"
(as of 95.0)

ShieldPreDamaged() --> "proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile"

UnitUnitCollision(colliderID, collideeID) -- needs SetWatchUnit enabled for both parties

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID) Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0

AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defaultPriority)
--> <code>return "targetAllowed, targetPriority"</code>
defaultPriority new in 89.0 

Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0

DrawShield(number unitID, number weaponID) --> boolean

''true'' (<-?) skips Spring's own drawing of shield <weaponID> owned by unit <unitID>

[https://github.com/spring/spring/commit/7bbfd9464d4f74c12163ea0740c8c60d1ba978f1 maybe new in 86.0+]

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag, cmdParams, cmdOptions" cmdParams and cmdOptions are only available from version 95.0

UnitFeatureCollision(colliderID, collideeID, crushKilled) -- needs SetWatchUnit for first and SetWatchFeature for second party

{{new|95.0}} FeatureDamaged() --> "featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam"

{{new|95.0}} FeaturePreDamaged() --> "featureID, featureDefID, featureTeam, damage, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam"

<code>--> return newDamage, impulseMult (=0)</code>

==Drawing:==
Inside these functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

* DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

* DrawWorldPreUnit() --> none.

Spring draws units, features, some water types, cloaked units, and the sun.

* DrawWorld() --> none.

Spring draws command queues, 'map stuff', and map marks.

Each unit might also have a DrawUnit call, [[Lua_UnitRendering|enabled here.]]

DrawUnit(unitID,DrawMode) 
With enum DrawMode { 
notDrawing = 0, 
normalDraw = 1, 
shadowDraw = 2, 
reflectionDraw = 3, 
refractionDraw = 4 
};

DrawFeature(featureID, DrawMode) 

DrawShield(unitID, weaponID, DrawMode) 

DrawProjectile(projectileID, DrawMode) 

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

DrawLoadScreen() --> none. {{new|95.0}}

Only available to LuaIntro, draws custom load screens.

==Game Events:==

GameID() --> "gameID" {{new|89.0}}

Explosion() --> "weaponID, px, py, pz, ownerID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon
 return true to hide the weapon's CEG

ShockFront() --> "power, dx, dy, dz" Not yet implemented!

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail. Not yet implemented!

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) Not yet implemented!

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() -->
number clampedPos.x, number clampedPos.y, number clampedPos.z,
number playerID,
number readyState,
number rawPickPos.x, number rawPickPos.y, number rawPickPos.z

clampedPos = coordinates clamped into startbox, rawPickPos = where player tried to start

{{New|95.0}} the default 'failed to choose' start-position is now just (0,0,0), not (0,-500,0)

readyState can be any one of:
PLAYER_RDYSTATE_UPDATED = 0 -- player picked a position
PLAYER_RDYSTATE_READIED = 1 -- player clicked ready
PLAYER_RDYSTATE_FORCED = 2 -- game was force-started (player did not click ready)
PLAYER_RDYSTATE_FAILED = 3

GameSetup() --> string "state", boolean "ready", table "playerStates"
 return success, newReady

GamePaused() --> "playerID, paused"

PlayerAdded() --> "playerID"

PlayerRemoved() --> "playerID, reason"

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID, weaponDefID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

ProjectileDestroyed() --> "proID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

AllowWeaponInterceptTarget --> "number interceptorUnitID, number interceptorWeaponID, number targetProjectileID"
returns boolean
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

[[Category:Deprecated]]

Lua Beginners FAQ

2017-12-26T12:18:15Z

Flozi: /* What is the difference between LuaUI, LuaRules, widgets and gadgets? */ update links

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

This page is an introduction to using Lua in Spring - it only tries to answer general questions, for more specific Questions please ask in the forum.

==Where should I start?==

You can start by reading general Lua tutorials [http://lua-users.org/wiki/LuaTutorial here].

After that, you could look at the example widget [[Lua:Tutorial_GettingStarted|here]], and try to add some functionality of your own!

Once you're a pro, have a look at the game repos [https://springrts.com/wiki/Gamedev:PublicRepos here], especially their /luaui/Widgets and /luarules/gadgets dirs.

==Where can I find help?==

You can find documentation of Springs Lua API on the [[Lua_Scripting|Lua_Scripting]] page. Discussion of lua coding takes place on the [https://springrts.com/wiki/Read_Me_First lobby] in #moddev and #lua, and there is also a [https://springrts.com/phpbb/viewforum.php?f=23 Lua sub-forum].

==How do I open ".lua" files?==

Any text editor is enough. On Windows i.e. use [http://notepad-plus.sourceforge.net/uk/site.htm Notepad++]. There are also IDEs able to work with Lua, such as Eclipse, if you look for them.

==What is a call-in? And a call-out?==

Call-ins are functions defined in your script that Spring calls when a determined event takes place. For example, the widget:Initialize() call-in is run by Spring when the widget is loaded.
Call-outs are functions defined in Spring you can run at whichever moment you desire. For example, when you call Spring.GetUnitTeam(unitID), the engine returns the teamID of the unit identified by "unitID".

==What is the difference between unsynced and synced lua code?==

Synced code is code that runs, identically and at the same time, on every connected client. In practice, this means code which controls the game state. Unsynced code is code that will run differently (or maybe not at all) on each connected client. Typically, this means the user interface.

For example, lua code to make units explode if they fell down a cliff would need to be synced. But, code that warned a player when one of their own units was getting near a cliff edge, would need to be unsynced.

==What is the difference between LuaUI, LuaRules, widgets and gadgets?==

Spring allows various [[Lua:Environments|Lua Environments]], each with differing functionality. Inside each Lua environment, developers can write addons, which are self-contained pieces of code. There are:
* LuaUI: Used for unsynced GUI related code. Addons in here are often called widgets. Clients can (if the game permits it) control which widgets are running. Widgets contain only unsynced code. They can be bundled inside the game, or loaded from the users "Spring/LuaUI/Wigets" directory.
* LuaRules: Addons in here are often called gadgets. Clients cannot choose which gadgets run. Gadgets can include both synced and unsynced code, and must be bundled inside the game.

Intended for mappers, there is also LuaGaia, which behaves like LuaRules but is separated from it. To see which of the lua environoments has access to which data/functionality, see [[Lua:Environments#Interfaces]] and [[Lua:Callins]].

==What can't Lua do in the current version of Spring?==

Springs Lua interface is very powerful. To work out if some idea is possible you need to ask
* When do I need the engine to tell me something has happened? Check against [[Lua:Callins|Callins]].
* What information will I need to know about the game state? Check against [[Lua_SyncedRead]] (synced) and [[Lua_UnsyncedRead]] (unsynced).
* What do I then need to do about it? Check against [[Lua_SyncedCtrl]] (synced) and[[Lua_UnsyncedCtrl]] (unsynced).
Sometimes you need special functionality, like disk access or OpenGL calls, in which case check against [[Lua_Scripting#Interfaces|Interfaces]].

For completeness, some examples of things you (currently) can't do:
*control the ground LOS - but you can set the los status of units!
*add custom parameters to CEG definitions.

==Where can I find/edit examples?==

You can find some easy example widgets [[Lua:Tutorial_GettingStarted|here]]. The best source of more complicated examples is inside games themselves, in the LuaUI/Widgets and Luarules/gadgets directories. See [[Gamedev:PublicRepos]] for a list of repositories.

To make your own widgets, simply place individual .lua files into your Spring/LuaUI/Widgets dir (create the dir if it is not present. Case-sensitive!!!). Game repositories can be checked out into a folder named "SomeAwesomeGame.sdd", placed in your "/Spring/games" dir; this shoudl give a local copy of the game, recognized by Spring, where you can edit files. Make sure to check the licenses before doing this!

==Can I reload a script without restarting Spring?==

Yes, you can type "/luaui reload" to reload widgets, and if you have "cheats" enabled you can also "/luarules reload" to reload gadgets.

==Why does the print function seem to do nothing?==

Its output is displayed in stdout. If you have no easy way to see it, you can Spring.Echo("some text") which prints to the ingame chat and infolog.txt.

[[Category: Lua]]

GadgetDatabase

2017-12-26T12:11:18Z

Flozi: Category lua -> historical, never went anywhere (flawed concept imo)

[b]Some Logistics thoughts:[/b]

There's already been some worthy gadgets suggested for inclusion (on the thread this idea was discussed). And of course I'd like to see them online! While it wouldn't be too great an effort for me to upload them, for two reasons, I'd prefer not too:

- First, if we get even a fraction of the potential general use gadgets that are out there onto the database, that'd be a considerable workload for me to shoulder alone.
- Second (and perhaps more importantly), a good number of them will continue to be improved or kept up to date - and would thus be outdated pretty soon on the database, if the authors can't easily update it themselves.

For the second reason, I'd also be happy to set up shared accounts for game development groups (since you can only edit gadgets you've uploaded with your account, and there's no way of allowing other accounts edit-powers).

Since the Gadget-DB builds on the great system made for the Widget-Database, if you've ever used the Browser-based interface of that ([url=http://www.springinfo.info/?page_id=690]as seen on Springinfo[/url]) - this is the same. Accordingly, if you happen to have managed Widgets, the system is the same here :) !

some technicalities/suggestions regarding documentation of Gadgets you upload and such
Finally, the technicalities (I'm wondering if there'd be a better place for this info - maybe wiki ?):

And/or have a look at the docu I included with [url=http://gadgetdb.springrts.de/lua_manager.php?m=10&id=356]the KeyboardSteering Gadget[/url]

[b]"Modules"[/b] - As pointed out repeatedly, a lot of gadgets actually require multiple files, and potentially entries in unitdefs (or whatnot) to work properly. Thanks to the setup vbs has made though, it is trivial to upload multiple files and specify different places for them to go different :).

I would suggest that where eg unitdefs are required. I realise anyone more savvy with lua will not require this per se - I think with a little extra effort though, we can keep the database accessible to people with little grasp of lua.

In that vein, the following also seem a pretty much "must-have" to me:
As well as including an "Api" text file explaining how the gadget interfaces with the rest of Spring:
- ie what unitdefs it needs;
- any "calls" it requires (ie global vars be set) from non-generalisable seperate gadgets;
Or to pick up your example:
- what info it passes on to GUI elements;
- CMDs it depends on being given, etc.

Finally, I'd suggest some categories (if you want to categorise that is - as of now there's no functionality, since it's made with SpringDownloader in mind).

UI, (GUI), Map, Unitbehaviour, Unitdefs, Unitvars, Antihack,
(I'm sure there's some more that might be added.)

[[Category: Historical]]

Lua:Environments

2017-12-26T01:31:27Z

Flozi: /* Environments */ underp links

== Environments ==
Here is an exhaustive list of the different lua environments within Spring, roughly in execution order as a game is loaded.
=== LuaMenu ===
Source: {{sourcelink|file=rts/Lua/LuaMenu.cpp}}

Introduced in 104.0, a stripped down environment that starts before the game is loaded and persists through reload.
=== LuaParser ===
Source: {{sourcelink|file=rts/Lua/LuaParser.cpp}}

Minimal environment used to parse and load definition files.
=== LuaIntro ===
Source: {{sourcelink|file=rts/Lua/LuaIntro.cpp}}

Introduced in 95.0, to allow visual customisation of the loading process.
=== LuaRules (synced) ===
Source: {{sourcelink|file=rts/Lua/LuaHandle.cpp}}

Source: {{sourcelink|file=rts/Lua/LuaHandleSynced.cpp#L305}}

The main environment for synced game-controlling mechanics ("gadgets").
=== LuaRules (unsynced) ===
Source: {{sourcelink|file=rts/Lua/LuaHandle.cpp}}

Source: {{sourcelink|file=rts/Lua/LuaHandleSynced.cpp#L57}}

The main environment for unsynced game effects, rendering, UI etc. ("gadgets")
=== LuaGaia (synced) ===
Source: {{sourcelink|file=rts/Lua/LuaGaia.cpp}}

As LuaRules (synced) but for maps.
=== LuaGaia (unsynced) ===
Source: {{sourcelink|file=rts/Lua/LuaGaia.cpp}}

As LuaRules (unsynced) but for maps.
=== LuaUI ===
The main environment for toggleable UI elements and controls ("widgets").

== Interfaces ==
The following table demonstrates which interfaces are available to each environment.
{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em; border: 1px #aaa solid; border-collapse: collapse;"
|
! align="center" | LuaMenu
! align="center" | LuaIntro
! align="center" | LuaParser
! align="center" | LuaRules/Gaia (synced)
! align="center" | LuaRules/Gaia (unsynced)
! align="center" | LuaUI
|-
| align="left" | [[Lua_ConstGame]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstEngine]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstPlatform]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_UnitDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_WeaponDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_FeatureDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_ConstCOB]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -

|-
| align="left" | [[Lua_CMDs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_UnsyncedRead]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_UnsyncedCtrl]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_SyncedRead]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#888800" | +**

|-
| align="left" | [[Lua_SyncedCtrl]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_MoveCtrl]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_PathFinder]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_OpenGL_Api]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_GLSL_Api]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_FBO_and_RBO]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_UnitRendering ]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_Fonts]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstGL]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_VFS]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#888800" | +*
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_Scream]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_BitOps]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_MathExtra]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_Socket]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
|}

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em; border: 1px #aaa solid; border-collapse: collapse;"
|-
| align="center" | *
| align="left"| only VFS.ZIP_ONLY
|-
| align="center" | **
| align="left"| with special LOS handling and decoy unit handling
|-
| align="center" | ***
| align="left"| stripped down environment with certain functions removed
|}

[[Category:Lua]]

Talk:Lua Scripting

2017-12-26T00:21:05Z

Flozi: Flozi moved page Talk:Lua Scripting to Talk:Lua:Main: consistency with Gamedev:Main and MapDev:Main and leaving redirect anyway

#REDIRECT [[Talk:Lua:Main]]

Lua Scripting

2017-12-26T00:21:05Z

Flozi: Flozi moved page Lua Scripting to Lua:Main: consistency with Gamedev:Main and MapDev:Main and leaving redirect anyway

#REDIRECT [[Lua:Main]]

Lua:Main

2017-12-26T00:21:05Z

Flozi: Flozi moved page Lua Scripting to Lua:Main: consistency with Gamedev:Main and MapDev:Main and leaving redirect anyway

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

=Lua FAQ=
Lua scripting is the primary way for developers to customize their games and add new features. Most aspects of the Spring engine can be controlled and extensively modified through the Lua API.

[[Lua_Beginners_FAQ|Introduction to Lua in Spring]] 
[[Lua:Tutorial_GettingStarted|Easy widget examples]]

=Interfaces {{HeaderNotice|(last update: 104)}}=
[[Lua:Environments]] (Details the available environments and shows which interfaces are loaded by each)

[[Lua:Callins]] (Entry points to lua addons)
{{LuaInterfaces}}

=Tutorials=
* [[Lua:Tutorial_GettingStarted|Easy example widgets]]
* [[LuaTutorials::InterCommunications]] (i.e. synced <-> unsynced communications)

=Other useful information=
* [[Lua_Libraries | Lua libraries]]
* [[Lua_Performance | Lua performance tips]]
* [http://springrts.com/wiki/COB_Constants#Custom_Variables COB Custom Variables]
* [http://springrts.com/phpbb/viewtopic.php?f=12&t=19560 Font Drawing System]
* [[UI_commands]]
* [[Animation-LuaScripting | Unit animation scripting with Lua]]

=Official Lua documentation=
[http://www.lua.org/pil/ 'Programming in Lua' book online] 
[http://www.lua.org/manual/5.1/ Lua 5.1 Reference manual] 
[http://lua-users.org/wiki/TutorialDirectory Lua tutorials]
[[Category: Lua]]

Template:Sourcelink

2017-12-25T22:59:35Z

Flozi: usage

<noinclude>
A small template to link to an engine source file on github.

Usage: <nowiki>{{sourcelink|file=path/to/file.cpp}}</nowiki>

</noinclude><includeonly>[https://github.com/spring/spring/blob/{{EngineVersion:Stable}}/{{{file|}}} {{{file|}}}] </includeonly>

Lua:Environments

2017-12-25T22:46:48Z

Flozi: /* Environments */ some source links

== Environments ==
Here is an exhaustive list of the different lua environments within Spring, roughly in execution order as a game is loaded.
=== LuaMenu ===
Source: {{sourcelink|file=Lua/LuaMenu.cpp}}

Introduced in 104.0, a stripped down environment that starts before the game is loaded and persists through reload.
=== LuaParser ===
Source: {{sourcelink|file=Lua/LuaParser.cpp}}

Minimal environment used to parse and load definition files.
=== LuaIntro ===
Source: {{sourcelink|file=Lua/LuaIntro.cpp}}

Introduced in 95.0, to allow visual customisation of the loading process.
=== LuaRules (synced) ===
Source: {{sourcelink|file=Lua/LuaHandle.cpp}}

Source: {{sourcelink|file=Lua/LuaHandleSynced.cpp}}

The main environment for synced game-controlling mechanics ("gadgets").
=== LuaRules (unsynced) ===
Source: {{sourcelink|file=Lua/LuaHandle.cpp}}

The main environment for unsynced game effects, rendering, UI etc. ("gadgets")
=== LuaGaia (synced) ===
Source: {{sourcelink|file=Lua/LuaGaia.cpp}}

As LuaRules (synced) but for maps.
=== LuaGaia (unsynced) ===
Source: {{sourcelink|file=Lua/LuaGaia.cpp}}

As LuaRules (unsynced) but for maps.
=== LuaUI ===
The main environment for toggleable UI elements and controls ("widgets").

== Interfaces ==
The following table demonstrates which interfaces are available to each environment.
{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em; border: 1px #aaa solid; border-collapse: collapse;"
|
! align="center" | LuaMenu
! align="center" | LuaIntro
! align="center" | LuaParser
! align="center" | LuaRules/Gaia (synced)
! align="center" | LuaRules/Gaia (unsynced)
! align="center" | LuaUI
|-
| align="left" | [[Lua_ConstGame]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstEngine]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstPlatform]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_UnitDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_WeaponDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_FeatureDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_ConstCOB]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -

|-
| align="left" | [[Lua_CMDs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_UnsyncedRead]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_UnsyncedCtrl]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_SyncedRead]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#888800" | +**

|-
| align="left" | [[Lua_SyncedCtrl]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_MoveCtrl]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_PathFinder]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_OpenGL_Api]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_GLSL_Api]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_FBO_and_RBO]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_UnitRendering ]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_Fonts]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstGL]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_VFS]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#888800" | +*
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_Scream]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_BitOps]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_MathExtra]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_Socket]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
|}

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em; border: 1px #aaa solid; border-collapse: collapse;"
|-
| align="center" | *
| align="left"| only VFS.ZIP_ONLY
|-
| align="center" | **
| align="left"| with special LOS handling and decoy unit handling
|-
| align="center" | ***
| align="left"| stripped down environment with certain functions removed
|}

[[Category:Lua]]

Lua:Main

2017-12-25T21:21:58Z

Flozi: /* Interfaces {{HeaderNotice|(last update: 101)}} */ -> 104

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

=Lua FAQ=
Lua scripting is the primary way for developers to customize their games and add new features. Most aspects of the Spring engine can be controlled and extensively modified through the Lua API.

[[Lua_Beginners_FAQ|Introduction to Lua in Spring]] 
[[Lua:Tutorial_GettingStarted|Easy widget examples]]

=Interfaces {{HeaderNotice|(last update: 104)}}=
[[Lua:Environments]] (Details the available environments and shows which interfaces are loaded by each)

[[Lua:Callins]] (Entry points to lua addons)
{{LuaInterfaces}}

=Tutorials=
* [[Lua:Tutorial_GettingStarted|Easy example widgets]]
* [[LuaTutorials::InterCommunications]] (i.e. synced <-> unsynced communications)

=Other useful information=
* [[Lua_Libraries | Lua libraries]]
* [[Lua_Performance | Lua performance tips]]
* [http://springrts.com/wiki/COB_Constants#Custom_Variables COB Custom Variables]
* [http://springrts.com/phpbb/viewtopic.php?f=12&t=19560 Font Drawing System]
* [[UI_commands]]
* [[Animation-LuaScripting | Unit animation scripting with Lua]]

=Official Lua documentation=
[http://www.lua.org/pil/ 'Programming in Lua' book online] 
[http://www.lua.org/manual/5.1/ Lua 5.1 Reference manual] 
[http://lua-users.org/wiki/TutorialDirectory Lua tutorials]
[[Category: Lua]]

Lua:Environments

2017-12-22T16:33:23Z

Flozi: /* Interfaces */ add LuaIntro, LuaParser

== Environments ==
Here is an exhaustive list of the different lua environments within Spring, roughly in execution order as a game is loaded.
=== LuaMenu ===
Introduced in 104.0, a stripped down environment that starts before the game is loaded and persists through reload.
=== LuaParser ===
Minimal environment used to parse and load definition files.
=== LuaIntro ===
Introduced in 95.0, to allow visual customisation of the loading process.
=== LuaRules (synced) ===
The main environment for synced game-controlling mechanics ("gadgets").
=== LuaRules (unsynced) ===
The main environment for unsynced game effects, rendering, UI etc. ("gadgets")
=== LuaGaia (synced) ===
As LuaRules (synced) but for maps.
=== LuaGaia (unsynced) ===
As LuaRules (unsynced) but for maps.
=== LuaUI ===
The main environment for toggleable UI elements and controls ("widgets").

== Interfaces ==
The following table demonstrates which interfaces are available to each environment.
{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em; border: 1px #aaa solid; border-collapse: collapse;"
|
! align="center" | LuaMenu
! align="center" | LuaIntro
! align="center" | LuaParser
! align="center" | LuaRules/Gaia (synced)
! align="center" | LuaRules/Gaia (unsynced)
! align="center" | LuaUI
|-
| align="left" | [[Lua_ConstGame]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstEngine]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstPlatform]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_UnitDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_WeaponDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_FeatureDefs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_ConstCOB]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -

|-
| align="left" | [[Lua_CMDs]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_UnsyncedRead]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +

|-
| align="left" | [[Lua_UnsyncedCtrl]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_SyncedRead]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#888800" | +**

|-
| align="left" | [[Lua_SyncedCtrl]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_MoveCtrl]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_PathFinder]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_OpenGL_Api]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_GLSL_Api]]
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#888800" | +***
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_FBO_and_RBO]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_UnitRendering ]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
|-
| align="left" | [[Lua_Fonts]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_ConstGL]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_VFS]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#888800" | +*
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_Scream]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_BitOps]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_MathExtra]]
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#227722" | +
|-
| align="left" | [[Lua_Socket]]
| align="center" bgcolor="#227722" | +
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#772222" | -
| align="center" bgcolor="#227722" | +
|}

{| border="2" cellpadding="4" cellspacing="0" style="margin: 1em 1em 1em; border: 1px #aaa solid; border-collapse: collapse;"
|-
| align="center" | *
| align="left"| only VFS.ZIP_ONLY
|-
| align="center" | **
| align="left"| with special LOS handling and decoy unit handling
|-
| align="center" | ***
| align="left"| stripped down environment with certain functions removed
|}

[[Category:Lua]]

Lua:Main

2017-12-22T15:27:50Z

Flozi: /* Interfaces {{HeaderNotice|(last update: 101)}} */ update links

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

=Lua FAQ=
Lua scripting is the primary way for developers to customize their games and add new features. Most aspects of the Spring engine can be controlled and extensively modified through the Lua API.

[[Lua_Beginners_FAQ|Introduction to Lua in Spring]] 
[[Lua:Tutorial_GettingStarted|Easy widget examples]]

=Interfaces {{HeaderNotice|(last update: 101)}}=
[[Lua:Environments]] (Details the available environments and shows which interfaces are loaded by each)

[[Lua:Callins]] (Entry points to lua addons)
{{LuaInterfaces}}

=Tutorials=
* [[Lua:Tutorial_GettingStarted|Easy example widgets]]
* [[LuaTutorials::InterCommunications]] (i.e. synced <-> unsynced communications)

=Other useful information=
* [[Lua_Libraries | Lua libraries]]
* [[Lua_Performance | Lua performance tips]]
* [http://springrts.com/wiki/COB_Constants#Custom_Variables COB Custom Variables]
* [http://springrts.com/phpbb/viewtopic.php?f=12&t=19560 Font Drawing System]
* [[UI_commands]]
* [[Animation-LuaScripting | Unit animation scripting with Lua]]

=Official Lua documentation=
[http://www.lua.org/pil/ 'Programming in Lua' book online] 
[http://www.lua.org/manual/5.1/ Lua 5.1 Reference manual] 
[http://lua-users.org/wiki/TutorialDirectory Lua tutorials]
[[Category: Lua]]