Spring - User contributions [en]

Lua MoveCtrl

2021-08-16T23:34:24Z

Pepeampere: /* MoveType-Controlling */ adding the repeated values to be listed in all commands docu

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

= ScriptMoveType =
== Enable/Disable ==
'''Spring.MoveCtrl.Enable'''
( number unitID ) -> nil

'''Spring.MoveCtrl.Disable'''
( number unitID ) -> nil

== Tags ==
'''Spring.MoveCtrl.SetTag'''
( number unitID, number tag ) -> nil

'''Spring.MoveCtrl.GetTag'''
( number unitID ) -> nil

'''Spring.MoveCtrl.SetProgressState'''
( number unitID, number state | "done" | "active" | "failed" ) -> nil

== Physics ==
'''Spring.MoveCtrl.SetGravity'''
( number unitID, number gravity ) -> nil
<span class=note>N.B. gravity here is a multiplier to Game.gravity</span>

'''Spring.MoveCtrl.SetDrag'''
( number unitID, number drag ) -> nil

'''Spring.MoveCtrl.SetGroundOffset'''
( number unitID, number offset ) -> nil

'''Spring.MoveCtrl.SetWindFactor'''
( number unitID, number windFactor ) -> nil

'''Spring.MoveCtrl.SetPhysics'''
( number unitID,
number posX, number posY, number posZ,
number velX, number velY, number velZ,
number rotX, number rotY, number rotZ ) -> nil

'''Spring.MoveCtrl.SetPosition'''
( number unitID,
number posX, number posY, number posZ ) -> nil

'''Spring.MoveCtrl.SetVelocity'''
( number unitID,
number velX, number velY, number velZ ) -> nil

'''Spring.MoveCtrl.SetRelativeVelocity'''
( number unitID,
number relvelX, number relvelY, number relvelZ ) -> nil

'''Spring.MoveCtrl.SetRotation'''
( number unitID,
number rotX, number rotY, number rotZ ) -> nil

'''Spring.MoveCtrl.SetRotationVelocity'''
( number unitID,
number rotVelX, number rotVelY, number rotVelZ ) -> nil

'''Spring.MoveCtrl.SetRotationOffset'''
( number unitID,
number rotOffX, number rotOffY, number rotOffZ ) -> nil

'''Spring.MoveCtrl.SetHeading'''
( number unitID, number heading ) -> nil

== Options ==
'''Spring.MoveCtrl.SetNoBlocking'''
( number unitID, boolean noblock ) -> nil

'''Spring.MoveCtrl.SetLimits'''
( number unitID,
number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil

'''Spring.MoveCtrl.SetTrackSlope'''
( number unitID, boolean trackslope ) -> nil

'''Spring.MoveCtrl.SetTrackGround'''
( number unitID, boolean noblock ) -> nil

'''Spring.MoveCtrl.SetExtrapolate'''
( number unitID, boolean on ) -> nil

'''Spring.MoveCtrl.SetShotStop''' <span class="warning">Currently a no-op</span>
( number unitID, boolean shotstop ) -> nil

'''Spring.MoveCtrl.SetSlopeStop''' <span class="warning">Currently a no-op</span>
( number unitID, boolean slopestop ) -> nil

'''Spring.MoveCtrl.SetCollideStop'''
( number unitID, boolean collidestop ) -> nil
<span class=note>Enable both SetCollideStop and SetTrackGround to enable MoveCtrlNotify(unitID, unitDefID, unitTeam, data) call-in, data was supposed to indicate the type of notification but currently never has a value other than 1 (where 1 means "unit hit the ground")</span>

= MoveType-Controlling =

'''Spring.MoveCtrl.SetMoveDef''' {{new|94.0}}
( number unitID, number moveDefID | string moveDefName ) -> boolean success
<span class=note>NOTE: string moveDefName needs to be in '''lowercase''', notwithstanding the fact that it may be in another case in the movedef table.
</span>
<span class=note>NOTE: all Set*MoveTypeData functions support the following number keys:
maxSpeed
maxWantedSpeed
repairBelowHealth
</span>

'''Spring.MoveCtrl.SetAirMoveTypeData''' {{new|0.81}}
( number unitID, string key, value ) -> nil
( number unitID, table values ) -> nil
<span class=note>supported keys:
numbers:
maxSpeed
maxWantedSpeed
repairBelowHealth
wantedHeight
myGravity
maxBank
maxPitch
turnRadius
maxAcc
maxAileron
maxElevator
maxRudder
waterline
attackSafetyDistance -- since 100.0 : fighters abort dive toward target if within attackSafetyDistance and try to climb back to normal altitude while still moving toward target
maneuverBlockTime -- since 104.0.1+(FIXME) : number of frames aircraft will try to keep flying straight past the target after firing
booleans:
collide
useSmoothMesh
NOTE: not all keys and not all values may work correctly.
[[SetMoveTypeDataExample|Example usage]]</span>

'''Spring.MoveCtrl.SetGroundMoveTypeData''' {{new|0.81}}
( number unitID, string key, value ) -> nil
( number unitID, table values ) -> nil
<span class=note>supported keys:
numbers:
baseTurnRate
turnRate
accRate
decRate
maxSpeed
maxWantedSpeed
repairBelowHealth
maxReverseDist
maxReverseSpeed
minReverseAngle
requestedSpeed
requestedTurnRate
sqSkidSpeedMult
waterline
booleans:
floatOnWater
pushResistant
NOTE: not all keys and not all values may work correctly.
[[SetMoveTypeDataExample|Example usage]]</span>
{{new|101.0}} {{var|maxReverseDist}} & {{var|minReverseAngle}} keys

{{new|104.0}} {{var|sqSkidSpeedMult}}, {{var|pushResistant}} & {{var|waterline}} keys

'''Spring.MoveCtrl.SetGunshipMoveTypeData''' {{new|0.81}}
( number unitID, string key, value ) -> nil
( number unitID, table values ) -> nil
<span class=note>supported keys:
numbers:
maxSpeed
maxWantedSpeed
repairBelowHealth
wantedHeight
turnRate
accRate
decRate
altitudeRate
currentBank
currentPitch
waterline
booleans:
collide
useSmoothMesh
bankingAllowed
dontLand
airStrafe
NOTE: not all keys and not all values may work correctly.
[[SetMoveTypeDataExample|Example usage]]</span>

[[category: Lua]]

Lua Fonts

2020-02-08T21:07:55Z

Pepeampere: /* Inlined ColorCodes */ adding comment to reset value

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

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

=Userdata Functions=
'''font:Print'''
(string "text", number x, number y [, number size [, string <span class=note>"options"</span>] ] ) -> nil
<span class=note>
options are:
horizontal alignment:
'c' = center
'r' = right
vertical alignment:
'a' = ascender (is a font specific value)
't' = top (depends on text)
'v' = vertical center
'x' = baseline
'b' = bottom
'd' = descender
decorations:
'o' = black outline
'O' = white outline
's' = shadow
other:
'n' = don't round vertex coords to nearest integer (font may get blurry)
</span>
http://home.arcor.de/jkei/fontlines.png

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

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

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

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

<span class=note><b>If you have multiple font:Print calls, then you can bunch them between a font:Begin() and font:End() to speedup the rendering.</b></span><br>
'''font:Begin'''
( ) -> nil
'''font:End'''
( ) -> nil

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

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

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

[[category: Lua]]

Lua:Callins

2017-05-06T20:47:10Z

Pepeampere: /* Units */

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

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

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

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

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

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

== Unsynced Only ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = KeyPress
|args = key, mods, isRepeat
|return = {{type|bool}} becomeOwner
|info = Called repeatedly when a key is pressed down. If you want an action to occur only once check for {{var|1=isRepeat == {{value|false}}}}. The {{var|mods}} parameter is a {{type|table}}, with keys {{value|"alt"}}, {{value|"ctrl"}}, {{value|"meta"}} and {{value|"shift"}} each having a boolean value. Return {{value|true}} if you don't want other callins or the engine to also receive this keypress.
}}

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

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

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

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

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

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

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

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

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

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

=== Downloads ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Synced - Unsynced Shared ==

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

=== Game ===

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

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

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

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

{{LuaCallin
|name = GamePreload
|info = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = UnitExperience
|args = unitID, unitDefID, unitTeam, experience, oldExperience
|info = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category: Lua]]

GamesDownloads

2016-11-13T00:27:51Z

Pepeampere: /* Spring Lobby */

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Spring Lobby =

For the Spring engine and a variety of games to play on it! Online battlerooms and singleplayer. Also, there is a lobby to chat in.

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=http://springlobby.info/}}
The easiest way to play: download SpringLobby, join the Spring server and enter an online battleroom.

</div>

== Individual game installers ==
A handful of Spring games also provide their own installers (and/or other infrastructure). These usually contain everything you need to play that game, but they might not allow you to play other games too.
<div id="installers" style="padding-left:7px">

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
A well featured lobby that can be used to play any game, but by default only shows Evolution RTS. (Windows & Linux)

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
<span class="warning">(!)</span> Zero-K uses a seperate server that does not fully support other Spring games. (Windows & Linux (mono))

{{Template:GamesDownload|name=NOTA|image=notAgame02.jpg|url=http://nota.machys.net/downloads}}
<span class="warning">(!)</span> This lobby is limited to playing NOTA. (Windows & Linux & Mac OS X)

{{Template:GamesDownload|name=Spring 1944|image=S44_tigers.jpg|notAs44lobby|url=https://trello.com/c/XllGyMqI/}}
<span class="warning">(!)</span> This lobby is limited to playing Spring 1944, NOTA and Kernel Panic. (Windows & Linux)

{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}} <span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

</div>

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

[[Category:Spring]]

Lua SyncedCtrl

2016-07-05T12:26:57Z

Pepeampere: adding Spring.SetFeatureRulesParam

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

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

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

= RulesParams =
<span class=warning>string values are new since 95.0</span>

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

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

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

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

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

'''Spring.SetTeamResource'''
( number teamID, string res, number amount ) -> nil
<font color="#55ee99">
possible values for res are:
"m" = metal
"e" = energy
"ms" = metal storage
"es" = energy storage
</font>

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

'''Spring.ShareTeamResource''' <span class=note>0.82 and later</span>
( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

= Teams =
'''Spring.SetAlly''' {{new|98.0}}
( number firstAllyTeamID, number secondAllyTeamID, boolean ally ) -> nil
<font color="#55ee99">
Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID
</font>

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

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

= Unit Handling =
'''Spring.CreateUnit''' <font color="#55ee99">note: offmap positions are clamped! (you still can use MoveCtrl todo so)</font>
( string "defName" | number unitDefID,
number x, number y, number z,
(number facing | string "facing"),
number teamID
[, boolean build = false]
[, boolean flattenGround = true]
[, number unitID]
[, number builderID]) -> number unitID | nil (meaning unit was not created)
<font color="#55ee99">
possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
if build is true the unit is created in "being built" state, with buildProgress = 0
unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with
a specific ID.
</font>

'''Spring.DestroyUnit'''
( number unitID
[, boolean selfd = false]
[, boolean reclaimed = false]
[, number attackerID ] ) -> nil
<font color="#55ee99">
selfd := makes the unit act like it self-destructed
reclaimed := don't show any DeathSequences, don't leave a wreckage.
NOTE this does _not_ give back the resources to the team!
</font>

'''Spring.TransferUnit'''
( number unitID,
numer newTeamID
[, boolean given = true ] ) -> nil
<font color="#55ee99">if given=false, the unit is captured</font>

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

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

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

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

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

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

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

'''Spring.SetUnitFuel'''
( number unitID, number fuel ) -> nil

'''Spring.SetUnitCrashing''' {{new|83.0}}
( number unitID, boolean crashing ) -> boolean success

'''Spring.SetUnitLineage''' {{removed|83.0}}
( number unitID, number teamID [, boolean isRoot] ) -> nil

'''Spring.SetUnitNeutral'''
( number unitID, boolean neutral ) -> nil

'''Spring.SetUnitTarget''' <span class="warning">userTarget & success new in version 95.0, setting nil target new in 99.0</span>
( number unitID,
number enemyUnitID | number x, number y, number z, | nil,
[ boolean dgun = false ], [ boolean userTarget = false ] ) -> success

'''Spring.SetUnitMaxRange'''
( number unitID, number maxRange ) -> nil

'''Spring.SetUnitBlocking''' <span class="warning">crushable new in version 85.0</span>
( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil

'''Spring.SetUnitBlocking''' {{new|95.0}} changed parameters:
number unitID,
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

'''Spring.SetUnitMetalExtraction'''
( number unitID, number depth [,number range] ) -> nil

'''Spring.SetUnitBuildSpeed'''
( number builderID,
number buildSpeed, [ number repairSpeed [, number reclaimSpeed
[,number resurrectSpeed [, number captureSpeed [, number terraformSpeed ]] ]]] ) -> nil

'''Spring.SetUnitNanoPieces''' {{new|92.0}}
( number builderID, table pieces ) -> nil
This saves a lot of engine calls, by replacing:
function script.QueryNanoPiece() return currentpiece end
Use it!

'''Spring.UnitAttach''' {{new|101.0}}
( number transporterID, number passengerID, number pieceNum ) -> nil

'''Spring.UnitDetach''' {{new|101.0}}
( number passengerID ) -> nil

'''Spring.UnitDetachFromAir''' {{new|101.0}}
( number passengerID ) -> nil

'''Spring.SetUnitLoadingTransport''' {{new|101.0}}
( number passengerID, number transportID ) -> nil

<span class="note">Disables collisions between the two units to allow colvol intersection during the approach.</span>

'''Spring.SetUnitPieceParent''' {{new|101.0}}
( number unitID, number AlteredPiece, number ParentPiece ) -> nil
Changes the pieces hierarchy of a unit, by attaching a piece to a new parent.

'''Spring.SetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID, boolean armored [, number armorMultiple] ) -> nil

'''Spring.SetUnitShieldState'''
( number unitID [, number weaponID = -1] [, boolean enabled] [, number power] ) -> nil

'''Spring.SetUnitFlanking'''
( number unitID, string "mode", number mode ) -> nil
( number unitID, string "moveFactor", number factor) -> nil
( number unitID, string "minDamage", number minDamage ) -> nil
( number unitID, string "mazDamage", number maxDamage ) -> nil
( number unitID, string "dir", number x, number y, number z) -> nil

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
<span class="note">format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,] (*)
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}
(*) if you change the range of a weapon with dynamic damage
make sure you use SetUnitWeaponDamages to change dynDamageRange as well.
</span>

'''Spring.SetUnitWeaponDamages''' {{new|101.0}}
( number unitID, number weaponNum | "selfDestruct" | "explode", table damages ) -> nil
( number unitID, number weaponNum | "selfDestruct" | "explode", string key, number value ) -> nil
<span class="note">format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}
</span>

'''Spring.SetUnitCollisionVolumeData'''
( number unitID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
<span class="note">enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_NUM_TYPES // number of non-disabled collision volume types
};
enum COLVOL_TESTS {
COLVOL_TEST_DISC = 0,
COLVOL_TEST_CONT = 1,
COLVOL_NUM_TESTS = 2 // number of tests
};
enum COLVOL_AXES {
COLVOL_AXIS_X = 0,
COLVOL_AXIS_Y = 1,
COLVOL_AXIS_Z = 2,
COLVOL_NUM_AXES = 3 // number of collision volume axes
};
</span>

'''Spring.SetUnitPieceCollisionVolumeData'''
( number unitID, number pieceIndex, boolean enable,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ
[, number volumeType [, number primaryAxis]]
) -> nil

'''Spring.SetUnitTravel'''
( number unitID, number travel [, number travelPeriod] ) -> nil

'''Spring.SetUnitMoveGoal''' <span class="note">used by default commands to get in build-,attackrange etc.</span>
(number unitID, number goalx, number goaly, number goalz
[, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )
{{new|98.0}} <span class="note">moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]</span>

'''Spring.SetUnitPhysics''' <span class="warning">drag new in version 95.0</span>
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
number dragx, number dragy, number dragz,
) -> nil

'''Spring.SetUnitPosition'''
( number unitID, number x, number z [, boolean alwaysAboveSea] ) -> nil

'''Spring.SetUnitDirection''' {{new|90.0}}
( number unitID, number x, number y, number z ) -> nil

'''Spring.SetUnitVelocity'''
( number unitID, number velx, number vely, number velz ) -> nil

'''Spring.SetUnitRotation'''
( number unitID, number rotx, number roty, number rotz ) -> nil

'''Spring.AddUnitImpulse'''
( number unitID, number x, number y, number z [, decayRate ] ) -> nil

'''Spring.AddUnitSeismicPing'''
( number unitID, number pingSize ) -> nil

'''Spring.RemoveBuildingDecal'''
( number unitID ) -> nil

'''Spring.SetUnitMidAndAimPos''' {{new|89.0}}
( number unitID,
number mpx, number mpy, number mpz,
number apx, number apy, number apz,
[, boolean relative] ) -> boolean success

<font color="#55ee99">
mpx, mpy, mpz: new middle position of unit

apx, apy, apz: new position that enemies aim at on this unit

relative: are the new coordinates relative to world or unit coordinates?
</font>

'''Spring.SetUnitRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

'''Spring.UnitWeaponFire'''
( number unitID, number weaponID ) -> nil
'''Spring.UnitWeaponHoldFire'''
( number unitID, number weaponID ) -> nil

== Unit LOS ==
'''Spring.SetUnitCloak'''
( number unitID,
boolean cloaked | number scriptCloak,
[ number decloakDistance | boolean decloakAbs ] ) -> nil

<font color="#55ee99">
If the 2nd argument is a number, the value works like this:
1:=normal cloak
2:=for free cloak (cost no E)
3:=for free + no decloaking (except the unit is stunned)
4>=ultimative cloak (no ecost, no decloaking, no stunned decloak)

The decloak distance is only changed if the 3th argument is a number or a boolean.
If the boolean is false it takes the default decloak distance for that unitdef,
if the boolean is true it takes the absolute value of it.</font>

'''Spring.SetUnitSonarStealth'''
( number unitID, boolean sonarStealth ) -> nil

'''Spring.SetUnitStealth'''
( number unitID, boolean stealth ) -> nil

'''Spring.SetUnitAlwaysVisible'''
( number unitID, boolean alwaysVisible ) -> nil

'''Spring.SetUnitLosMask'''
( number unitID, number allyTeam, number los | table losTypes ) -> nil
<font color="#55ee99">the 3th argument is either the bit-and combination of the following numbers:
LOS_INLOS = 1
LOS_INRADAR = 2
LOS_PREVLOS = 4
LOS_CONTRADAR = 8
</font><font color="#55ee99">or a table of the following form:
losTypes = {
[los = boolean,]
[radar = boolean,]
[prevLos = boolean,]
[contRadar = boolean,]
}</font>

'''Spring.SetUnitLosState'''
( number unitID, number allyTeam, number los | table losTypes ) -> nil
<font color="#55ee99">see above for more info on the arguments</font>

'''Spring.SetUnitSensorRadius'''
( number unitID, string type, number radius ) -> nil | number newRadius
<font color="#55ee99">type can be:
"los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"</font>

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

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

== Unit Resourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil
<font color="#55ee99">
possible values for res are: "[u|c][u|m][m|e]"
unconditional | conditional
use | make
metal | energy
</font>

'''Spring.AddUnitResource'''
( number unitID, string "m" | "e", number amount ) -> nil

'''Spring.UseUnitResource'''
( number unitID, string "m" | "e", number amount ) -> nil | boolean okay
( number unitID, { ["m" | "metal" | "e" | "energy"] = amount, ... } ) -> nil | boolean okay

'''Spring.SetUnitHarvestStorage''' {{new|97.0}}
( number unitid, number metal )

<span class = "note">See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.</span>

= Feature Handling =
'''Spring.CreateFeature'''
( string "defName" | number featureDefID,
number x, number y, number z
[, number heading
[, number AllyTeamID
[, number featureID ]]] ) -> number featureID

'''Spring.DestroyFeature'''
( number featureID ) -> nil

'''Spring.TransferFeature'''
( number featureID, number teamID ) -> nil

== Feature Control ==
'''Spring.SetFeatureHealth'''
( number featureID, number health) -> nil

'''Spring.SetFeatureReclaim'''
( number featureID, number reclaimLeft) -> nil

'''Spring.SetFeatureResurrect'''
( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil
<font color="#55ee99">
possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
</font>

'''Spring.SetFeaturePosition'''
( number featureID, number x, number y, number z [, boolean snapToGround]) -> nil

'''Spring.SetFeatureDirection'''
( number featureID, number x, number y, number z ) -> nil

'''Spring.SetFeatureVelocity''' {{New|95.0}}

'''Spring.SetFeaturePhysics''' {{New|95.0}}

(like their feature counterparts at [[Lua_SyncedCtrl#Unit_Control]])

'''Spring.SetFeatureNoSelect'''
( number featureID, boolean noSelect ) -> nil

'''Spring.SetFeatureAlwaysVisible'''
( number featureID, boolean enable ) -> nil

'''Spring.SetFeatureCollisionVolumeData'''
( number featureID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
<span class=note>check Spring.SetUnitCollisionVolumeData for further explanation of the arguments</span>

'''Spring.SetFeatureMidAndAimPos''' {{new|89.0}}
( number unitID,
number mpx, number mpy, number mpz,
number apx, number apy, number apz,
[, boolean relative] ) -> boolean success

<span class=note>check Spring.SetUnitMidAndAimPos for further explanation of the arguments</span>

'''Spring.SetFeatureRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

'''Spring.SetFeatureBlocking'''
(number featureID, boolean blocking, boolean collidable) --> boolean

'''Spring.SetFeatureBlocking''' {{new|95.0}} changed parameters:
number featureID,
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

= Lua to COB =
'''Spring.CallCOBScript'''
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number retArg1, number retArg2, ...

'''Spring.CallCOBScriptCB'''<br>
<font style="color:red;font-weight:600">broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement</font>
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

'''Spring.GetCOBScriptID'''
( number unitID, string funcName ) -> nil | number funcID

<span class="warning"><b>Note: Don't use Spring.[Get|Set]UnitCOBValue in LUS just because you are familar with it since bos/cob, use the mighty LuaSpringAPI instead!</b></span>

'''Spring.GetUnitCOBValue'''
( number unitID [, boolean splitData=false], number COBValue
[, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
-> number result | number result1, number result2
<span class=note>you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]</span>
<span class=note> also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]</span>

'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
<span class=note>you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]</span>
<span class=note> also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]</span>

= Give Order =
<font color="#55ee99">options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation)<br>
see [[Lua CMDs]] for relevant constants
</font>

'''Spring.GiveOrderToUnit'''
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

'''Spring.GiveOrderToUnitMap'''
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

'''Spring.GiveOrderToUnitArray'''
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

'''Spring.GiveOrderArrayToUnitMap'''
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
{number, etc...}, <font color="#55ee99">params</font>
{"alt", "ctrl", "shift", "right"} <font color="#55ee99">options</font>
}, ..
}
) -> nil

'''Spring.GiveOrderArrayToUnitArray'''
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
{number, etc...}, <font color="#55ee99">params</font>
{"alt", "ctrl", "shift", "right"} <font color="#55ee99">options</font>
}, ..
}
) -> nil

=Ground=
== Grass ==
'''Spring.AddGrass'''
( number x, number z ) -> nil

'''Spring.RemoveGrass'''
( number x, number z ) -> nil

== Heightmap ==
<span class="note">Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is [[Lua_ConstGame|Game.squareSize]].</span>

'''Spring.LevelHeightMap'''
( number x1, number z1 [, number x2, number z2], number height ) -> nil

'''Spring.AdjustHeightMap''' <span class="note">(heightmap[x][z] += height;)</span>
( number x1, number z1 [, number x2, number z2], number height ) -> nil

'''Spring.RevertHeightMap'''
( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil

'''Spring.SetHeightMapFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
<span class="note">Example code:</span><code><pre>
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for x=0,Game.mapSizeX, Game.squareSize do
Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
end
end
end)
</pre></code>
'''Spring.AddHeightMap''' <span class="warning">can only be called in SetHeightMapFunc()</span>
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' <span class="warning">can only be called in SetHeightMapFunc()</span>
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
<span class="note">the terraform argument is a scaling factor:
so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.</span>

'''Spring.LevelSmoothMesh'''
( number x1, number z1 [, number x2, number z2], number height ) -> nil
'''Spring.AdjustSmoothMesh'''
( number x1, number z1 [, number x2, number z2], number height ) -> nil
'''Spring.RevertSmoothMesh'''
( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil

'''Spring.SetSmoothMeshFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
'''Spring.AddSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff

== TerrainTypes ==
'''Spring.SetMapSquareTerrainType'''
( number x, number z, int newType ) -> nil | int oldType
'''Spring.SetTerrainTypeData'''
( int typeIndex
[, number speedTanks = nil ]
[, number speedKBOTs = nil ]
[, number speedHovers = nil ]
[, number speedShips = nil ] ) -> nil | boolean true

== MetalAmount ==
'''Spring.SetMetalAmount''' {{new|83.0}}
( number x, number z, number metalAmount)
<span class="note">x & z coords are in worldspace/16<br>metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua)</span>

= Command Descriptions =
<font color="red" style="font-size:120%; font-weight:600">Doesn't work in unsynced code!</font><br><br>

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil
<font color="#55ee99">
structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}
</font>

'''Spring.InsertUnitCmdDesc'''
( number unitID [, number cmdDescID ] , table cmdArray ) -> nil

'''Spring.RemoveUnitCmdDesc'''
( number unitID [, number cmdDescID ] ) -> nil

= Other =
'''Spring.SetNoPause'''
( boolean noPause ) -> nil

'''Spring.SetUnitToFeature'''
( boolean tofeature ) -> nil
<font color="#55ee99">
an ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag)
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]
</font>

'''Spring.SetExperienceGrade'''
( number expGrade
<font color=#55ee99>[, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]]</font> ) -> nil

<font color="#55ee99">expGrade defines how often UnitExperience() will be called,
it is based on the following equation:
(int) [exp/(exp+1)] / expGrade
If this integer differs from the one before the experience change
it will call UnitExperience().
Also those 3 last params are only available in .cheat
</font>

'''Spring.SpawnCEG'''
( string "cegname" | number cegID,
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil | boolean success, cegID
<span class="warning">cegID new in 95.0</span>

= Projectiles =
'''Spring.SpawnProjectile'''
( number weaponDefID, table projectileParams ) -> nil | number projectileID
<span class=note>possible keys of projectileParams are:
pos = {number x, number y, number z},
end = {number x, number y, number z},
speed = {number x, number y, number z},
spread = {number x, number y, number z},
error = {number x, number y, number z},
owner = number,
team = number,
ttl = number,
gravity = number,
tracking = number,
maxRange = number,
startAlpha = number,
endAlpha = number,
model = string,
cegTag = string,
</span>

'''Spring.SetProjectileTarget'''

<span class = "warning">Pre 95.0:</span> ( number projectileID,
[ number targetID, string targetTypeStr ] | [ number posX, number posY, number posZ ] )
-> nil | boolean validTarget

<span class = "warning">Post 95.0:</span> ( number projectileID,
[ number targetID [, number targetType]] | [number posX, number posY, number posZ])
--> nil | boolean validTarget
<span class=note>targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE
</span>
'''Spring.SetProjectileIsIntercepted''' {{new|99.0}}
( number projID ) -> nil

'''Spring.SetProjectileMoveControl''' <span class=note>(disables engine movecontrol, so lua can fully control the physics)</span>
( number projID, boolean enable ) -> nil
'''Spring.SetProjectilePosition'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileVelocity'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
( number projID ) -> nil
'''Spring.SetProjectileGravity'''
( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle''' {{new|95.0}} Deprecated
( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed''' {{new|95.0}} Deprecated
( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec''' {{new|95.0}} Deprecated
( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
( number projID, string ceg_name ) -> nil

'''Spring.SetPieceProjectileParams''' {{new|95.0}}
(number projectileID,
[ number explosionFlags, [ number spinAngle, [ number spinSpeed,
[ number spinVector.x, [ number spinVector.y, [ number spinVector.z ]]]]]]) --> nil

'''Spring.SetProjectileAlwaysVisible''' {{new|95.0}}
(number projectileID, boolean alwaysVisible) --> nil

'''Spring.SetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, table damages ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
<span class="note">format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}
</span>

[[category: Lua]]

Lua SyncedCtrl

2016-06-05T23:25:54Z

Pepeampere: /* Heightmap */

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

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

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

= RulesParams =
<span class=warning>string values are new since 95.0</span>

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

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

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

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

'''Spring.SetTeamResource'''
( number teamID, string res, number amount ) -> nil
<font color="#55ee99">
possible values for res are:
"m" = metal
"e" = energy
"ms" = metal storage
"es" = energy storage
</font>

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

'''Spring.ShareTeamResource''' <span class=note>0.82 and later</span>
( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

= Teams =
'''Spring.SetAlly''' {{new|98.0}}
( number firstAllyTeamID, number secondAllyTeamID, boolean ally ) -> nil
<font color="#55ee99">
Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID
</font>

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

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

= Unit Handling =
'''Spring.CreateUnit''' <font color="#55ee99">note: offmap positions are clamped! (you still can use MoveCtrl todo so)</font>
( string "defName" | number unitDefID,
number x, number y, number z,
(number facing | string "facing"),
number teamID
[, boolean build = false]
[, boolean flattenGround = true]
[, number unitID]
[, number builderID]) -> number unitID | nil (meaning unit was not created)
<font color="#55ee99">
possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
if build is true the unit is created in "being built" state, with buildProgress = 0
unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with
a specific ID.
</font>

'''Spring.DestroyUnit'''
( number unitID
[, boolean selfd = false]
[, boolean reclaimed = false]
[, number attackerID ] ) -> nil
<font color="#55ee99">
selfd := makes the unit act like it self-destructed
reclaimed := don't show any DeathSequences, don't leave a wreckage.
NOTE this does _not_ give back the resources to the team!
</font>

'''Spring.TransferUnit'''
( number unitID,
numer newTeamID
[, boolean given = true ] ) -> nil
<font color="#55ee99">if given=false, the unit is captured</font>

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

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

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

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

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

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

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

'''Spring.SetUnitFuel'''
( number unitID, number fuel ) -> nil

'''Spring.SetUnitCrashing''' {{new|83.0}}
( number unitID, boolean crashing ) -> boolean success

'''Spring.SetUnitLineage''' {{removed|83.0}}
( number unitID, number teamID [, boolean isRoot] ) -> nil

'''Spring.SetUnitNeutral'''
( number unitID, boolean neutral ) -> nil

'''Spring.SetUnitTarget''' <span class="warning">userTarget & success new in version 95.0, setting nil target new in 99.0</span>
( number unitID,
number enemyUnitID | number x, number y, number z, | nil,
[ boolean dgun = false ], [ boolean userTarget = false ] ) -> success

'''Spring.SetUnitMaxRange'''
( number unitID, number maxRange ) -> nil

'''Spring.SetUnitBlocking''' <span class="warning">crushable new in version 85.0</span>
( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil

'''Spring.SetUnitBlocking''' {{new|95.0}} changed parameters:
number unitID,
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

'''Spring.SetUnitMetalExtraction'''
( number unitID, number depth [,number range] ) -> nil

'''Spring.SetUnitBuildSpeed'''
( number builderID,
number buildSpeed, [ number repairSpeed [, number reclaimSpeed
[,number resurrectSpeed [, number captureSpeed [, number terraformSpeed ]] ]]] ) -> nil

'''Spring.SetUnitNanoPieces''' {{new|92.0}}
( number builderID, table pieces ) -> nil
This saves a lot of engine calls, by replacing:
function script.QueryNanoPiece() return currentpiece end
Use it!

'''Spring.UnitAttach''' {{new|101.0}}
( number transporterID, number passengerID, number pieceNum ) -> nil

'''Spring.UnitDetach''' {{new|101.0}}
( number passengerID ) -> nil

'''Spring.UnitDetachFromAir''' {{new|101.0}}
( number passengerID ) -> nil

'''Spring.SetUnitLoadingTransport''' {{new|101.0}}
( number passengerID, number transportID ) -> nil

<span class="note">Disables collisions between the two units to allow colvol intersection during the approach.</span>

'''Spring.SetUnitPieceParent''' {{new|101.0}}
( number unitID, number AlteredPiece, number ParentPiece ) -> nil
Changes the pieces hierarchy of a unit, by attaching a piece to a new parent.

'''Spring.SetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID, boolean armored [, number armorMultiple] ) -> nil

'''Spring.SetUnitShieldState'''
( number unitID [, number weaponID = -1] [, boolean enabled] [, number power] ) -> nil

'''Spring.SetUnitFlanking'''
( number unitID, string "mode", number mode ) -> nil
( number unitID, string "moveFactor", number factor) -> nil
( number unitID, string "minDamage", number minDamage ) -> nil
( number unitID, string "mazDamage", number maxDamage ) -> nil
( number unitID, string "dir", number x, number y, number z) -> nil

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
<span class="note">format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,] (*)
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}
(*) if you change the range of a weapon with dynamic damage
make sure you use SetUnitWeaponDamages to change dynDamageRange as well.
</span>

'''Spring.SetUnitWeaponDamages''' {{new|101.0}}
( number unitID, number weaponNum | "selfDestruct" | "explode", table damages ) -> nil
( number unitID, number weaponNum | "selfDestruct" | "explode", string key, number value ) -> nil
<span class="note">format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}
</span>

'''Spring.SetUnitCollisionVolumeData'''
( number unitID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
<span class="note">enum COLVOL_TYPES {
COLVOL_TYPE_DISABLED = -1,
COLVOL_TYPE_ELLIPSOID = 0,
COLVOL_TYPE_CYLINDER,
COLVOL_TYPE_BOX,
COLVOL_TYPE_SPHERE,
COLVOL_NUM_TYPES // number of non-disabled collision volume types
};
enum COLVOL_TESTS {
COLVOL_TEST_DISC = 0,
COLVOL_TEST_CONT = 1,
COLVOL_NUM_TESTS = 2 // number of tests
};
enum COLVOL_AXES {
COLVOL_AXIS_X = 0,
COLVOL_AXIS_Y = 1,
COLVOL_AXIS_Z = 2,
COLVOL_NUM_AXES = 3 // number of collision volume axes
};
</span>

'''Spring.SetUnitPieceCollisionVolumeData'''
( number unitID, number pieceIndex, boolean enable,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ
[, number volumeType [, number primaryAxis]]
) -> nil

'''Spring.SetUnitTravel'''
( number unitID, number travel [, number travelPeriod] ) -> nil

'''Spring.SetUnitMoveGoal''' <span class="note">used by default commands to get in build-,attackrange etc.</span>
(number unitID, number goalx, number goaly, number goalz
[, number goalRadius [, number moveSpeed [, bool moveRaw ]]] )
{{new|98.0}} <span class="note">moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]</span>

'''Spring.SetUnitPhysics''' <span class="warning">drag new in version 95.0</span>
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
number dragx, number dragy, number dragz,
) -> nil

'''Spring.SetUnitPosition'''
( number unitID, number x, number z [, boolean alwaysAboveSea] ) -> nil

'''Spring.SetUnitDirection''' {{new|90.0}}
( number unitID, number x, number y, number z ) -> nil

'''Spring.SetUnitVelocity'''
( number unitID, number velx, number vely, number velz ) -> nil

'''Spring.SetUnitRotation'''
( number unitID, number rotx, number roty, number rotz ) -> nil

'''Spring.AddUnitImpulse'''
( number unitID, number x, number y, number z [, decayRate ] ) -> nil

'''Spring.AddUnitSeismicPing'''
( number unitID, number pingSize ) -> nil

'''Spring.RemoveBuildingDecal'''
( number unitID ) -> nil

'''Spring.SetUnitMidAndAimPos''' {{new|89.0}}
( number unitID,
number mpx, number mpy, number mpz,
number apx, number apy, number apz,
[, boolean relative] ) -> boolean success

<font color="#55ee99">
mpx, mpy, mpz: new middle position of unit

apx, apy, apz: new position that enemies aim at on this unit

relative: are the new coordinates relative to world or unit coordinates?
</font>

'''Spring.SetUnitRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

'''Spring.UnitWeaponFire'''
( number unitID, number weaponID ) -> nil
'''Spring.UnitWeaponHoldFire'''
( number unitID, number weaponID ) -> nil

== Unit LOS ==
'''Spring.SetUnitCloak'''
( number unitID,
boolean cloaked | number scriptCloak,
[ number decloakDistance | boolean decloakAbs ] ) -> nil

<font color="#55ee99">
If the 2nd argument is a number, the value works like this:
1:=normal cloak
2:=for free cloak (cost no E)
3:=for free + no decloaking (except the unit is stunned)
4>=ultimative cloak (no ecost, no decloaking, no stunned decloak)

The decloak distance is only changed if the 3th argument is a number or a boolean.
If the boolean is false it takes the default decloak distance for that unitdef,
if the boolean is true it takes the absolute value of it.</font>

'''Spring.SetUnitSonarStealth'''
( number unitID, boolean sonarStealth ) -> nil

'''Spring.SetUnitStealth'''
( number unitID, boolean stealth ) -> nil

'''Spring.SetUnitAlwaysVisible'''
( number unitID, boolean alwaysVisible ) -> nil

'''Spring.SetUnitLosMask'''
( number unitID, number allyTeam, number los | table losTypes ) -> nil
<font color="#55ee99">the 3th argument is either the bit-and combination of the following numbers:
LOS_INLOS = 1
LOS_INRADAR = 2
LOS_PREVLOS = 4
LOS_CONTRADAR = 8
</font><font color="#55ee99">or a table of the following form:
losTypes = {
[los = boolean,]
[radar = boolean,]
[prevLos = boolean,]
[contRadar = boolean,]
}</font>

'''Spring.SetUnitLosState'''
( number unitID, number allyTeam, number los | table losTypes ) -> nil
<font color="#55ee99">see above for more info on the arguments</font>

'''Spring.SetUnitSensorRadius'''
( number unitID, string type, number radius ) -> nil | number newRadius
<font color="#55ee99">type can be:
"los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"</font>

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

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

== Unit Resourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil
<font color="#55ee99">
possible values for res are: "[u|c][u|m][m|e]"
unconditional | conditional
use | make
metal | energy
</font>

'''Spring.AddUnitResource'''
( number unitID, string "m" | "e", number amount ) -> nil

'''Spring.UseUnitResource'''
( number unitID, string "m" | "e", number amount ) -> nil | boolean okay
( number unitID, { ["m" | "metal" | "e" | "energy"] = amount, ... } ) -> nil | boolean okay

'''Spring.SetUnitHarvestStorage''' {{new|97.0}}
( number unitid, number metal )

<span class = "note">See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.</span>

= Feature Handling =
'''Spring.CreateFeature'''
( string "defName" | number featureDefID,
number x, number y, number z
[, number heading
[, number AllyTeamID
[, number featureID ]]] ) -> number featureID

'''Spring.DestroyFeature'''
( number featureID ) -> nil

'''Spring.TransferFeature'''
( number featureID, number teamID ) -> nil

== Feature Control ==
'''Spring.SetFeatureHealth'''
( number featureID, number health) -> nil

'''Spring.SetFeatureReclaim'''
( number featureID, number reclaimLeft) -> nil

'''Spring.SetFeatureResurrect'''
( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil
<font color="#55ee99">
possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
</font>

'''Spring.SetFeaturePosition'''
( number featureID, number x, number y, number z [, boolean snapToGround]) -> nil

'''Spring.SetFeatureDirection'''
( number featureID, number x, number y, number z ) -> nil

'''Spring.SetFeatureVelocity''' {{New|95.0}}

'''Spring.SetFeaturePhysics''' {{New|95.0}}

(like their feature counterparts at [[Lua_SyncedCtrl#Unit_Control]])

'''Spring.SetFeatureNoSelect'''
( number featureID, boolean noSelect ) -> nil

'''Spring.SetFeatureAlwaysVisible'''
( number featureID, boolean enable ) -> nil

'''Spring.SetFeatureCollisionVolumeData'''
( number featureID, number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil
<span class=note>check Spring.SetUnitCollisionVolumeData for further explanation of the arguments</span>

'''Spring.SetFeatureMidAndAimPos''' {{new|89.0}}
( number unitID,
number mpx, number mpy, number mpz,
number apx, number apy, number apz,
[, boolean relative] ) -> boolean success

<span class=note>check Spring.SetUnitMidAndAimPos for further explanation of the arguments</span>

'''Spring.SetFeatureRadiusAndHeight''' {{new|89.0}}
( number unitID, number radius, number height ) -> boolean success

'''Spring.SetFeatureBlocking'''
(number featureID, boolean blocking, boolean collidable) --> boolean

'''Spring.SetFeatureBlocking''' {{new|95.0}} changed parameters:
number featureID,
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges

= Lua to COB =
'''Spring.CallCOBScript'''
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number retArg1, number retArg2, ...

'''Spring.CallCOBScriptCB'''<br>
<font style="color:red;font-weight:600">broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement</font>
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

'''Spring.GetCOBScriptID'''
( number unitID, string funcName ) -> nil | number funcID

<span class="warning"><b>Note: Don't use Spring.[Get|Set]UnitCOBValue in LUS just because you are familar with it since bos/cob, use the mighty LuaSpringAPI instead!</b></span>

'''Spring.GetUnitCOBValue'''
( number unitID [, boolean splitData=false], number COBValue
[, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
-> number result | number result1, number result2
<span class=note>you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]</span>
<span class=note> also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]</span>

'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
<span class=note>you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]</span>
<span class=note> also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]]</span>

= Give Order =
<font color="#55ee99">options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation)<br>
see [[Lua CMDs]] for relevant constants
</font>

'''Spring.GiveOrderToUnit'''
( number unitID,
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

'''Spring.GiveOrderToUnitMap'''
( unitMap = { [unitID] = dontCare, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

'''Spring.GiveOrderToUnitArray'''
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = {number, etc...},
options = {"alt", "ctrl", "shift", "right"} ) -> nil

'''Spring.GiveOrderArrayToUnitMap'''
( unitMap = { [number unitID] = dontCare, etc... },
orderArray = {
{ number cmdID,
{number, etc...}, <font color="#55ee99">params</font>
{"alt", "ctrl", "shift", "right"} <font color="#55ee99">options</font>
}, ..
}
) -> nil

'''Spring.GiveOrderArrayToUnitArray'''
( unitArray = { [1] = number unitID, etc... },
orderArray = {
{ number cmdID,
{number, etc...}, <font color="#55ee99">params</font>
{"alt", "ctrl", "shift", "right"} <font color="#55ee99">options</font>
}, ..
}
) -> nil

=Ground=
== Grass ==
'''Spring.AddGrass'''
( number x, number z ) -> nil

'''Spring.RemoveGrass'''
( number x, number z ) -> nil

== Heightmap ==
<span class="note">Note that x & z coords are in worldspace (Game.mapSizeX/Z), still the heightmap resolution is [[Lua_ConstGame|Game.squareSize]].</span>

'''Spring.LevelHeightMap'''
( number x1, number z1 [, number x2, number z2], number height ) -> nil

'''Spring.AdjustHeightMap''' <span class="note">(heightmap[x][z] += height;)</span>
( number x1, number z1 [, number x2, number z2], number height ) -> nil

'''Spring.RevertHeightMap'''
( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil

'''Spring.SetHeightMapFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
<span class="note">Example code:</span><code><pre>
Spring.SetHeightMapFunc(function()
for z=0,Game.mapSizeZ, Game.squareSize do
for x=0,Game.mapSizeX, Game.squareSize do
Spring.SetHeightMap( x, z, 200 + 20 * math.cos((x + z) / 90) )
end
end
end)
</pre></code>
'''Spring.AddHeightMap''' <span class="warning">can only be called in SetHeightMapFunc()</span>
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' <span class="warning">can only be called in SetHeightMapFunc()</span>
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
<span class="note">the terraform argument is a scaling factor:
so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.</span>

'''Spring.LevelSmoothMesh'''
( number x1, number z1 [, number x2, number z2], number height ) -> nil
'''Spring.AdjustSmoothMesh'''
( number x1, number z1 [, number x2, number z2], number height ) -> nil
'''Spring.RevertSmoothMesh'''
( number x1, number z1 [, number x2, number z2], number origFactor ) -> nil

'''Spring.SetSmoothMeshFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
'''Spring.AddSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetSmoothMesh''' <span class="warning">can only be called in SetSmoothMeshFunc()</span>
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff

== TerrainTypes ==
'''Spring.SetMapSquareTerrainType'''
( number x, number z, int newType ) -> nil | int oldType
'''Spring.SetTerrainTypeData'''
( int typeIndex
[, number speedTanks = nil ]
[, number speedKBOTs = nil ]
[, number speedHovers = nil ]
[, number speedShips = nil ] ) -> nil | boolean true

== MetalAmount ==
'''Spring.SetMetalAmount''' {{new|83.0}}
( number x, number z, number metalAmount)
<span class="note">x & z coords are in worldspace/16<br>metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua)</span>

= Command Descriptions =
<font color="red" style="font-size:120%; font-weight:600">Doesn't work in unsynced code!</font><br><br>

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil
<font color="#55ee99">
structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}
</font>

'''Spring.InsertUnitCmdDesc'''
( number unitID [, number cmdDescID ] , table cmdArray ) -> nil

'''Spring.RemoveUnitCmdDesc'''
( number unitID [, number cmdDescID ] ) -> nil

= Other =
'''Spring.SetNoPause'''
( boolean noPause ) -> nil

'''Spring.SetUnitToFeature'''
( boolean tofeature ) -> nil
<font color="#55ee99">
an ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag)
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]
</font>

'''Spring.SetExperienceGrade'''
( number expGrade
<font color=#55ee99>[, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]]</font> ) -> nil

<font color="#55ee99">expGrade defines how often UnitExperience() will be called,
it is based on the following equation:
(int) [exp/(exp+1)] / expGrade
If this integer differs from the one before the experience change
it will call UnitExperience().
Also those 3 last params are only available in .cheat
</font>

'''Spring.SpawnCEG'''
( string "cegname" | number cegID,
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil | boolean success, cegID
<span class="warning">cegID new in 95.0</span>

= Projectiles =
'''Spring.SpawnProjectile'''
( number weaponDefID, table projectileParams ) -> nil | number projectileID
<span class=note>possible keys of projectileParams are:
pos = {number x, number y, number z},
end = {number x, number y, number z},
speed = {number x, number y, number z},
spread = {number x, number y, number z},
error = {number x, number y, number z},
owner = number,
team = number,
ttl = number,
gravity = number,
tracking = number,
maxRange = number,
startAlpha = number,
endAlpha = number,
model = string,
cegTag = string,
</span>

'''Spring.SetProjectileTarget'''

<span class = "warning">Pre 95.0:</span> ( number projectileID,
[ number targetID, string targetTypeStr ] | [ number posX, number posY, number posZ ] )
-> nil | boolean validTarget

<span class = "warning">Post 95.0:</span> ( number projectileID,
[ number targetID [, number targetType]] | [number posX, number posY, number posZ])
--> nil | boolean validTarget
<span class=note>targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE
</span>
'''Spring.SetProjectileIsIntercepted''' {{new|99.0}}
( number projID ) -> nil

'''Spring.SetProjectileMoveControl''' <span class=note>(disables engine movecontrol, so lua can fully control the physics)</span>
( number projID, boolean enable ) -> nil
'''Spring.SetProjectilePosition'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileVelocity'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
( number projID ) -> nil
'''Spring.SetProjectileGravity'''
( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle''' {{new|95.0}} Deprecated
( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed''' {{new|95.0}} Deprecated
( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec''' {{new|95.0}} Deprecated
( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
( number projID, string ceg_name ) -> nil

'''Spring.SetPieceProjectileParams''' {{new|95.0}}
(number projectileID,
[ number explosionFlags, [ number spinAngle, [ number spinSpeed,
[ number spinVector.x, [ number spinVector.y, [ number spinVector.z ]]]]]]) --> nil

'''Spring.SetProjectileAlwaysVisible''' {{new|95.0}}
(number projectileID, boolean alwaysVisible) --> nil

'''Spring.SetProjectileDamages''' {{new|101.0}}
( number unitID, number weaponNum, table damages ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
<span class="note">format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}
</span>

[[category: Lua]]

GamesDownloads

2016-04-11T18:54:29Z

Pepeampere: /* Game installers (for players) */

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=http://springlobby.info/}}
(Multiplatform)

</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

= Game installers (for players) =
Below are some Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
A well featured lobby that can act as a universal downloader, but by default filters battlerooms to only show Evolution RTS. (Windows & Linux)

{{Template:GamesDownload|name=NOTA|image=notAgame02.jpg|url=http://nota.machys.net/downloads}}
(Windows & Linux & Mac OS X)

<span class="warning">(!)</span> This lobby is limited to playing game NOTA and the client itself in not open source.

{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}} <span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows & Linux (mono))
<span class="warning">(!)</span> Can not connect to spring multiplayer server. zero-K uses a seperate server and the lobby does not fully support other games.

</div>

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

[[Category:Spring]]

Gamedev:WeaponDefs

2016-04-06T20:09:43Z

Pepeampere: /* BeamLaser */ adding missleading names for lua calls

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

==Location==
WeaponDef files are .lua files stored in the <code>Weapons/</code> directory of a Spring Game. Alternatively they can be integrated into [[Gamedev:UnitDefs|UnitDefs]].

==Purpose==
WeaponDef files have one purpose; to define the properties of weapons. They are the main description file for what attributes your weapon should have and how it should behave. Since version 100.0, Spring will record a warning whenever it finds an unknown tag.

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

* {{sourcelink|file=rts/Sim/Weapons/WeaponDef.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 WeaponDef table the internal <code>weaponName</code> desired for the weapon.

===Common===
The following tags are common to all or at least a majority of '''WeaponTypes''', depending on the tag.

====General====
{{tag
|name = weaponType
|type = string
|default = "Cannon"
|description = Spring has 14 '''WeaponTypes''' which provide game developers with basic behaviours which they can customise to an extent with the '''WeaponDef''' tags. Some tags are specific to certain '''WeaponTypes''' and not implemented for others, [https://docs.google.com/spreadsheet/ccc?key=0Am5BbZxm93S9dEZXc1Q4dXR4TFRYTFM4NlR4OFJFdWc#gid=0 this two-way table] indicates which tags work for which types.}} The possible values are:
* [[#AircraftBomb|AircraftBomb]]
* [[#BeamLaser|BeamLaser]]
* [[#Cannon|Cannon]]
* [[#DGun|Dgun]]
* [[#EmgCannon|EmgCannon]]
* [[#Flame|Flame]]
* [[#LaserCannon|LaserCannon]]
* [[#LightningCannon|LightningCanon]]
* [[#Melee|Melee]]
* [[#MissileLauncher|MissileLauncher]]
* [[#Rifle|Rifle]]
* [[#Shield (WeaponType)|Shield]]
* [[#StarburstLauncher|StarburstLauncher]]
* [[#TorpedoLauncher|TorpedoLauncher]]

{{tag
|name = name
|type = string
|default = "Weapon"
|description = The descriptive name of the weapon as listed in FPS mode.}}

{{tag
|name = turret
|type = bool
|default = false
|description = Does the unit aim within an arc (up-to and including full 360Â° turret traverse) or always aim along the owner's heading?}}

{{tag
|name = noSelfDamage
|type = bool
|default = false
|description = Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.}}

{{tag
|name = impactOnly
|type = bool
|default = false
|description = Does the weapon only deal damage through direct hits and not 'splash' damage through {{taglink|areaOfEffect}}?}}

{{tag
|name = noExplode
|type = bool
|default = false
|description = Does the weapon explode on impact with a target or continue through? Note that these weapons will do damage every single frame they are inside the [[Gamedev:CollisionVolumes|collision volume]] of an object, underground or under water, massively multiplying their damage.}}

{{tag
|name = burnblow
|type = bool
|default = false
|special = lua: selfExplode
|description = Does the weapon explode when it reaches its maximum range or continue on its path? The name is an [[OTAism]].}}

{{tag
|name = range
|type = float
|default = 10.0
|description = The maximum range in [[elmo]]s that the weapon can fire at.}}

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile. Since 99.0 <code>maxVelocity</code> is a synonym.}}

{{tag
|name = reloadTime
|type = float
|default = 1.0
|description = The time in seconds between shots fired.}}

{{tag
|name = metalPerShot
|type = float
|default = 0.0
|description = Metal used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = energyPerShot
|type = float
|default = 0.0
|description = Energy used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = myGravity
|type = float
|default = 0.0
|description = Overrides the map gravity for ballistic weapons. The default of <code>0.0</code> disables the tag in favour of map gravity.}}

{{tag
|name = fireStarter
|type = float
|default = 0.0
|description = The percentage chance (<code>0.0</code> to <code>100.0</code>) of the weapon setting fire to static map features on impact.}}

{{tag
|name = cameraShake
|type = float
|default = damage (0.0 for paralyzers)
|description = Passed to the [[LuaCallinReturn#Game_Events:|ShockFront() callin]] as the first argument. Intended as a means to make the camera shake if in range of detonation.}}

{{tag
|name = stockpile
|type = bool
|default = false
|description = Does each round of the weapon have to be built and stockpiled by the player? Will only correctly function for the first of each stockpiled weapons a unit has.}}

{{tag
|name = stockpileTime
|type = float
|default = reloadTime
|description = The time in seconds taken to stockpile one round of the weapon.}}

{{tag
|name = interceptedByShieldType
|type = int
|default = Depends on {{taglink|weaponType}}
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of shields that can intercept this weapon. Each digit of binary that is set to one means that a shield with the corresponding digit in its {{taglink|interceptType}} will intercept this weapon. A value of <code>0</code> means that no shields will intercept the weapon. The defaults are as follows:
* <code>0</code> - [[#DGun]]
* <code>1</code> - [[#Cannon]] and [[#EmgCannon]]
* <code>2</code> - [[#LaserCannon]] and [[#BeamLaser]]
* <code>4</code> - [[#MissileLauncher]] and [[#StarburstLauncher]]
* <code>8</code> - [[#AircraftBomb]]
* <code>16</code> - [[#Flame]]
* <code>32</code> - [[#TorpedoLauncher]]
* <code>64</code> - [[#LightningCannon]]
* <code>128</code> - [[#Rifle]]
* <code>256</code> - [[#Melee]]
(See [[Shield Interception Tag Use]]).}}

====Collision & Avoidance====

{{tag
|name = avoidGround
|type = bool
|default = true
|description = Should the weapon avoid firing if terrain blocks the line of fire?}}

{{tag
|name = avoidFriendly
|type = bool
|default = true
|description = Should the weapon avoid firing if a friendly unit is in the line of fire?}}

{{tag
|name = avoidFeature
|type = bool
|default = true
|description = Should the weapon avoid firing if a static map feature is in the line of fire?}}

{{tag
|name = avoidNeutral
|type = bool
|default = false
|description = Should the weapon avoid firing if a neutral unit is in the line of fire?}}

{{tag
|name = collideEnemy
|type = bool
|default = true
|special = lua: noEnemyCollide
|description = Does the weapon projectile collide with enemy units or pass through?}}

{{tag
|name = collideFriendly
|type = bool
|default = true
|special = lua: noFriendlyCollide
|description = Does the weapon projectile collide with friendly units or pass through?}}

{{tag
|name = collideFeature
|type = bool
|default = true
|special = lua: noFeatureCollide
|description = Does the weapon projectile collide with static map features or pass through?}}

{{tag
|name = collideNeutral
|type = bool
|default = true
|special = lua: noNeutralCollide
|description = Does the weapon projectile collide with neutral units or pass through?}}

{{tag
|name = collideGround
|type = bool
|default = true
|special = lua: noGroundCollide
|description = Does the weapon projectile collide with terrain or pass through?}}

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = Modifies visual size of EMG and Flame projectiles, and physical size '''only''' for hitscan interceptor weapons (e.g. antinuke lasers). [[https://github.com/spring/spring/blob/3034e5f5a8f5b9fb4624a97f7a85cb5c90457725/rts/Sim/Projectiles/WeaponProjectiles/WeaponProjectile.cpp#L250 1]][[https://github.com/spring/spring/blob/master/rts/Sim/Misc/CollisionHandler.cpp#L33 2]]}}

====Targeting & Accuracy====
{{tag
|name = commandFire
|type = bool
|default = false
|description = Determines if the weapon will automatically fire on enemy units in range or only when manually ordered to attack.}}

{{tag
|name = canAttackGround
|type = bool
|default = true
|description = Determines if the weapon can be force-fired on ground positions or only fire on targeted units.}}

{{tag
|name = waterWeapon
|type = bool
|default = false
|description = Determines if the weapon can pass through water and target underwater units.}}

{{tag
|name = fireSubmersed
|type = bool
|default = waterWeapon
|description = Determines if the weapon can fire whilst underwater.}}

{{tag
|name = targetBorder
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon aims for the centre or the edge of its target's [[Gamedev:CollisionVolumes|collision volume]]. Clamped between <code>-1.0</code> - target the far border, and <code>1.0</code> - target the near border.}}

{{tag
|name = cylinderTargeting
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of this tag multiplied by the {{taglink|range}}. Clamped between <code>0.0</code> and <code>128.0</code>.}}

{{tag
|name = tolerance
|type = float
|default = 3000.0 (+/- ~18 degrees)
|description = The amount (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For {{taglink|turret|false}} or {{taglink|fixedLauncher|true}} weapons this determines in what arc the unit will fire.}}

{{tag
|name = fireTolerance
|type = float
|default = 32768.0 (+/- 180 degrees)
|special = {{new|99.0}}
|description = Final check to prevent weapons from shooting sideways. If a weapon is about to fire but the difference between its old aim and requested aim is greater than this angle (in [[Gamedev:UnitsOfMeasurement#Angular|cau]]) then it will not fire.}}

{{tag
|name = allowNonBlockingAim
|type = bool
|default = false
|special = {{new|99.0}}
|description = When enabled it makes [[Animation-LuaCallins#Weapons|AimWeapon()]] script calls non-blocking (still the {{taglink|fireTolerance}} tag might prevent the weapon firing). This is very useful for fast units that need to re-target often.}}

{{tag
|name = targetMoveError
|type = float
|default = 0.0
|description = The degree to which a weapon's aiming will fail to keep up with its target's movement. If set very low or not set at all, a weapon will lead its target and almost always hit.}}

{{tag
|name = leadLimit
|type = float
|default = -1.0
|description = Limits the maximum distance a unit will lead a target. The default of <code>-1</code> allows an infinite distance.}}

{{tag
|name = leadBonus
|type = float
|default = 0.0
|description = Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the {{taglink|leadLimit}}.}}

{{tag
|name = predictBoost
|type = float
|default = 0.0 (0.5 for {{taglink|burnblow|true}} weapons)
|description = Controls how well the weapon predicts unit speeds. Works in a similar way to {{taglink|targetMoveError}} except that it is 1-dimensional. This tag spreads the shots in a line based on the direction of the target whereas {{taglink|targetMoveError}} spreads the shots all around based on the movement.}}

{{tag
|name = heightMod
|type = float
|default = 0.2 (0.8 for [[#Cannon]], 1.0 for [[#BeamLaser]] and [[#LightningCannon]])
|description = Changes the spherical weapon range into an ellipsoid. Values above <code>1.0</code> mean the weapon cannot target as high as it can far, values below <code>1.0</code> mean it can target higher than it can far. For example <code>0.5</code> would allow the weapon to target twice as high as far.}}

{{tag
|name = proximityPriority
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance to the target in the priority calculation. Note that negative values make weapons prefer distant targets.}}

{{tag
|name = accuracy
|type = float
|default = 0.0
|description = How accurate the weapon is. Lower values are more accurate. Accuracy is relative to the distance to the target; for instance, if the target is very close, even a very high value will probably still hit. If a target is very far away, even a very low value will likely cause the weapon to miss.}}

{{tag
|name = movingAccuracy
|type = float
|default = accuracy
|description = A weapon's {{taglink|accuracy}} whilst the owning unit is moving.}}

{{tag
|name = sprayAngle
|type = float
|default = 0.0
|description = How wide the the angle of a burst from a [[#Bursts|burst weapon]] can be. Very similar to {{taglink|accuracy}}, except that this tag affects each projectile in a burst, whilst the former does not.}}

{{tag
|name = ownerExpAccWeight
|type = float
|default = 0.0 (See description)
|description = A multiplier to {{taglink|accuracy}} and {{taglink|sprayAngle}} that reduces inaccuracy as a units experience increases. Defaults are as follows:
* <code>0.9</code> - [[#Cannon]], [[#Rifle]]
* <code>0.7</code> - [[#LaserCannon]], [[#BeamLaser]], [[#StarburstLauncher]]
* <code>0.5</code> - [[#MissileLauncher]], [[#LightningCannon]], [[#EmgCannon]], [[#DGun]]
* <code>0.2</code> - [[#Flame]]
}}

{{tag
|name = targetable
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapon that can intercept this weapon. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptor}} tag will intercept this weapon. Instant-hitting weapons such as [[#BeamLaser]], [[#LightningCannon]] and [[#Rifle]] cannot be targeted.
}}

{{tag
|name = interceptor
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this weapon can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|targetable}} tag will be intercepted by this weapon.
}}

{{tag
|name = interceptSolo
|type = bool
|default = true
|special = {{new|92.0}}
|description = If <code>true</code> no other interceptors may target the same projectile.
}}

{{tag
|name = coverage
|type = float
|default = 0.0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = The radius in [[elmo]]s within which an {{taglink|interceptor}} weapon will fire on {{taglink|targetable}} weapons.
}}

====Bouncing====

{{tag
|name = waterBounce
|type = bool
|default = false
|description = Does the weapon bounce on water impacts?}}

{{tag
|name = groundBounce
|type = bool
|default = false
|description = Does the weapon bounce on ground impacts?}}

{{tag
|name = bounceSlip
|type = float
|default = 1.0
|description = The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.}}

{{tag
|name = bounceRebound
|type = float
|default = 1.0
|description = The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.}}

{{tag
|name = numBounce
|type = int
|default = -1
|description = The number of times the weapon will bounce on impact before exploding. The default value of <code>-1</code> allows infinite bounces (at least until velocity reaches 0).}}

====Area Of Effect, Impulse & Cratering====

{{tag
|name = areaOfEffect
|type = float
|default = 8.0 * 0.5
|special = lua: damageAreaOfEffect
|description = The ''diameter'' in [[elmo]]s in which the weapons explosion will cause damage.}}

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering. Behaviour changed slightly in 98.0 as previously craters were 1.5x {{taglink|craterAreaOfEffect}} whilst decals were 1.0x, they are now both the same size.}}

{{tag
|name = edgeEffectiveness
|type = float
|default = 0.0
|description = Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's {{taglink|areaOfEffect}}. Falls off from the epicentre according to the formula <code>damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))]</code>, a graph of the function for various values is available [[Media:EdgeEffectiveness.png|here]].}}

{{tag
|name = explosionSpeed
|type = float
|default = See description
|description = The speed at which the weapon's explosion propagates from the epicentre. The default is calculated by this complex formula: <code>defExpSpeed = {8.0 + [max(30.0, default_damage / 20.0) * 2.5]} / {9.0f + [sqrt(max(30.0, default_damage / 20.0f)) * 0.7]} * 0.5</code>.}}

{{tag
|name = impulseFactor
|type = float
|default = 1.0
|description = A multiplier to the impulse given to units within the explosion {{taglink|areaOfEffect}}, which is otherwise equal to the damage dealt after {{taglink|edgeEffectiveness}} is taken into account. For [[#Melee]] weapons this is instead multiplied by the owning unit's mass (See [[Gamedev:UnitDefs#Tag:mass|Gamedev:UnitDefs]]).}}

{{tag
|name = impulseBoost
|type = float
|default = 0.0
|description = A constant amount added to the weapon's impulse, regardless of distance from the epicentre or the damage potential of the explosion, prior to the application of {{taglink|impulseFactor}}}}

{{tag
|name = craterMult
|type = float
|default = impulseFactor
|description = A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.}}

{{tag
|name = craterBoost
|type = float
|default = 0.0
|description = A constant amount, added to the weapon's cratering depth before the application of {{taglink|craterMult}}.}}

====Bursts====

{{tag
|name = burst
|type = int
|default = 1
|special = lua: salvoSize
|description = How many shots to fire per burst.
}}

{{tag
|name = burstRate
|type = float
|default = 0.1
|special = lua: salvoDelay
|description = The time in seconds between shots in a burst. Note that {{taglink|reloadTime}} starts to count down from the ''first'' round fired, not the last so if <code>reloadTime < burst * burstRate</code> the weapon will fire continuously.
}}

{{tag
|name = projectiles
|type = int
|default = 1
|description = How many projectiles released per shot (shotgun style). e.g. a weapon with {{taglink|burst|5}}, {{taglink|burstRate|0.5}} and {{taglink|projectiles|2}} will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for {{taglink|reloadTime}}. Best used in conjunction with {{taglink|sprayAngle}} or changing the firing piece using [[Animation-LuaCallins#Weapons|ShotX]] as otherwise they'll all be clumped in one shot.
}}

====Paralyzing====
{{tag
|name = paralyzer
|type = bool
|default = false
|description = Is the weapon a paralyzer? If <code>true</code> the weapon only stuns enemy units and does not cause damage in the form of lost hit-points.
}}

{{tag
|name = paralyzeTime
|type = int
|default = 10
|special = lua: damages.paralyzeDamageTime
|description = Determines the maximum length of time in seconds that the target will be paralyzed. The timer is restarted every time the target is hit by the weapon. Cannot be less than <code>0</code>.
}}

====Dynamic Damage====
The following set of tags allow for a weapon's damage potential to vary with the distance to its target.

{{tag
|name = dynDamageExp
|type = float
|default = 0.0
|description = Exponent of the range-dependent damage formula, the default of <code>0.0</code> disables dynamic damage, <code>1.0</code> means linear scaling, <code>2.0</code> quadratic and so on.
}}

{{tag
|name = dynDamageMin
|type = float
|default = 0.0
|description = The minimum floor value that range-dependent damage can drop to.
}}

{{tag
|name = dynDamageRange
|type = float
|default = 0.0
|description = If set to non-zero values the weapon will use this value in the range-dependant damage formula instead of the actual {{taglink|range}}.
}}

{{tag
|name = dynDamageInverted
|type = bool
|default = false
|description = If <code>true</code> the damage curve is inverted i.e. the weapon does more damage at greater ranges as opposed to less.
}}

====Sounds====
{{tag
|name = soundTrigger
|type = bool
|default = false (true for [[#Melee]], [[#Rifle]] and non-beamBurst [[#BeamLaser]])
|description = Does the weapon play {{taglink|soundStart}} only once for each salvo (<code>true</code>) or for every round in a burst (<code>false</code>)?}}

{{tag
|name = soundStart
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon fires.}}

{{tag
|name = soundHitDry
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with solid ground. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

{{tag
|name = soundHitWet
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with water. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

====Visuals====

{{tag
|name = cegTag
|type = string
|default = ""
|description = The name, without prefixes, of a [[CEG]] to be emitted by the projectile each frame.
}}

{{tag
|name = intensity
|type = float
|default = 0.9 (0.2 for [[#Cannon]])
|description = Alpha transparency for non-3D model projectiles. Lower values are more opaque, but <code>0.0</code> will cause the projectile to disappear entirely.
}}

{{tag
|name = model
|type = string
|default = ""
|description = The filename of a 3D model to use when rendering the projectile. Note that only the root piece of a projectile model is rendered. Currently only for [[#Cannon]], [[#LaserCannon]], [[#MissileLauncher]], [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = explosionScar
|type = bool
|default = false
|description = Does the weapon's explosion leave a scar decal on the ground? For all types except [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If <code>true</code> the weapon is always rendered regardless of whether or not it is in LOS range of a player's units.
}}

{{tag
|name = rgbColor
|type = float[3]
|default = {1.0, 0.0, 0.0} (See Description)
|description = The primary colour for sprite rendering weapons. Additional defaults are as follows:
* [[#Cannon]] - <code>{1.0, 0.5, 0.0}</code>
* [[#EmgCannon]] - <code>{0.9, 0.9, 0.2}</code>
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of a [[CEG]], with <code>custom:</code> prefix, to spawn as the weapon's explosion. Does not currently work for [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = bounceExplosionGenerator
|type = string
|default = ""
|description = For weapons which can use {{taglink|groundBounce|true}}, the name of a [[CEG]], with <code>custom:</code> prefix, to spawn when weapon the bounces.
}}

{{tag
|name = texture1
|type = string
|default = ""
|description = The projectile texture for [[#AircraftBomb]], [[#Cannon]], [[#EmgCannon]], [[#Flame]]; beam texture for [[#LaserCannon]], [[#BeamLaser]], [[#LightningCannon]]; flare texture for [[#MissileLauncher]], [[#StarburstLauncher]] and dome texture for the [[#Shield]].
}}

{{tag
|name = texture2
|type = string
|default = ""
|description = The end-of-beam texture for [[#LaserCannon]], [[#BeamLaser]] and {{taglink|smoketrail}} texture for [[#MissileLauncher]], [[#StarburstLauncher]].
}}

{{tag
|name = texture3
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]], or muzzle texture if {{taglink|largeBeamLaser|true}}. Also used as the flame texture for [[#StarburstLauncher]].
}}

{{tag
|name = texture4
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]] with {{taglink|largeBeamLaser|true}}.
}}

===AircraftBomb===
Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. Visually drawn as a billboarded sprite as used by the [[#Cannon]], but more commonly used with a 3D model.

There are no tags specific to this '''WeaponType'''

====AircraftBomb Visuals====

When not using a {{taglink|model}}, the AircraftBomb is the same as [[#Cannon Visuals]].

===BeamLaser===
An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be [[Animation-LuaCallouts#Effects|script emitted]] if it has a {{taglink|beamTime}} longer than one frame. Visually drawn as a [http://en.wikipedia.org/wiki/Star_Trek Star Trek] Phaser-style laser weapon. The {{taglink|largeBeamLaser}} tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

{{tag
|name = minIntensity
|type = float
|default = 0.0
|description = The minimum percentage the weapon's damage can fall-off to over its range. Setting to <code>1.0</code> will disable fall off entirely. Unrelated to the visual-only {{taglink|intensity}} tag.
}}

{{tag
|name = beamTime
|type = float
|default = 1.0
|special = lua: beamtime (all lowercase!)
|description = How long in seconds to fire the laser before waiting for {{taglink|reloadTime}} to start. Damage is distributed over the duration of the {{taglink|beamTime}}, and the weapon will aim to hit the target when the beam is in the middle of its {{taglink|beamTime}} (i.e. using prediction).
}}

{{tag
|name = beamBurst
|type = bool
|default = false
|special = lua: beamburst (all lowercase!)
|description = Makes the laser fire a burst of beams that are all aimed towards the target (instead of aimed with the piece). A [[#BeamLaser]] can do its full damage with every shot if {{taglink|beamBurst}} is enabled. Disables {{taglink|beamTime}} in favour of the [[#Bursts|burst tags]].
}}

{{tag
|name = sweepFire
|type = bool
|default = false
|description = Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Reimplemented in 95.0, still has no script interaction so use with care. Respects {{taglink|reloadTime}} constraint but not much else.
}}

====BeamLaser Visuals====

See also {{taglink|thickness}} and {{taglink|coreThickness}}.

{{tag
|name = beamTTL
|type = int
|default = 0
|description = The time in frames for which the laser beam remains visible.
}}

{{tag
|name = beamDecay
|type = float
|default = 1.0
|description = How fast the beam fades out. Each frame the {{taglink|intensity}} is multiplied by this value.
}}

{{tag
|name = laserFlareSize
|type = float
|default = 15.0
|description = Determines the size of the firing flare.
}}

{{tag
|name = largeBeamLaser
|type = bool
|default = false
|description = Changes the visual effect allowing tiling and scrolling of the texture and a pulsating firing flare.
}}

{{tag
|name = tileLength
|type = float
|default = 200.0
|description = Defines the length before the texture used is repeated (tiled). Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = scrollSpeed
|type = float
|default = 5.0
|description = Controls how fast the texture scrolls. Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = pulseSpeed
|type = float
|default = 1.0
|description = Controls how fast the pulsating effect at the start of the beam is. Only if {{taglink|largeBeamLaser|true}}.
}}

===Cannon===
The default '''WeaponType'''. Fires a ballistic projectile, for the best result (without under/overshooting) the {{taglink|weaponVelocity}} should be set so as to give an elevation of 45Â° when firing at the maximum {{taglink|range}}. Substituting the angle into the [http://en.wikipedia.org/wiki/Trajectory#Range_and_height trajectory equation] and rearranging, we get:
<code><pre>weaponVelocity = âˆš(range * g)</pre></code>
where <code>g</code> is the map gravity, usually around <code>120</code> for most Spring maps (You can use the {{taglink|myGravity}} tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

{{tag
|name = highTrajectory
|type = int
|default = 2
|description = Can this weapon be fired in a high trajectory (>45Â° angle). Can be <code>0</code> - low trajectory only, <code>1</code> - high trajectory only or <code>2</code> - enables a high/low toggle button on the unit.
}}

{{tag
|name = heightBoostFactor
|type = float
|default = -1.0
|description = Controls the boost given to {{taglink|range}} by high terrain. Values > <code>1.0</code> result in increased range, <code>0.0</code> means the cannon has fixed range regardless of height difference to target. Any value < <code>0.0</code> (i.e. the default value) result in an automatically calculated value based on {{taglink|range}} and theoretical maximum range.
}}

====Cannon Visuals====

{{tag
|name = size
|type = float
|default = 2.0 + min(default_damage * 0.0025, {{taglink|areaOfEffect}} * 0.1)
|description = The drawing radius of the billboarded sprite. Also for [[#AircraftBomb Visuals]], [[#EmgCannon Visuals]] (default: <code>3.0</code>) and [[#Flame Visuals]].
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = A set of RGB colours to transition between over the projectile's lifetime. Can be given as a string of RGB digits or an image filename (See [[CColorMap]]). Also for [[#Flame Visuals]].
}}

{{tag
|name = sizeDecay
|type = float
|default = 0.0
|description = How quickly each particle of the Cannon shot decays in size.
}}

{{tag
|name = alphaDecay
|type = float
|default = 1.0
|description = How quickly each particle of the Cannon shot fades out.
}}

{{tag
|name = separation
|type = float
|default = 0.0
|description = The distance between each particle of the Cannon shot.
}}

{{tag
|name = noGap
|type = bool
|default = true
|description = Switch between the distance between particles being proportional to the size of the two particles (<code>true</code>) or proportional to the size of the first particle (<code>false</code>).
}}

{{tag
|name = stages
|type = int
|default = 5
|description = The number of particles in each Cannon shot.
}}

===DGun===
Fires a line-of-sight or ballistic projectile (selected via the {{taglink|gravityAffected}} tag). Visually represented by a fireball effect that cannot be customised, however it can be replaced by a 3D model. The name and visual effect are [[OTAism]]s.

{{tag
|name = gravityAffected
|type = bool
|default = false
|description = Does the fireball projectile lose height due to map gravity?
}}

===EmgCannon===
A line-of-sight weapon. Visually drawn as a billboarded sprite very similar to that of the [[#Cannon]], however not as customisable, or a 3D model. The name is another [[OTAism]].

There are no tags specific to this '''WeaponType'''.

===Flame===
A line-of-sight weapon intended for use as a flamethrower or similar. Visually drawn as a stream of textured particles, the colour of which can be controlled very precisely using the {{taglink|colorMap}} tag (see [[CColorMap]]).

====Flame Visuals====
See also {{taglink|colorMap}}.

{{tag
|name = sizeGrowth
|type = float
|default = 0.5
|description = How much the draw radius of the flame projectile increases each frame.
}}

{{tag
|name = flameGFXTime
|type = float
|default = 1.2
|description = Makes the flamethrower projectile stay alive as a visual-only effect (i.e. does not deal any damage) after it has reached maximum {{taglink|range}}. It is a percentage multiplier, e.g. <code>1.2</code> makes the projectile stay alive until it reaches 20% beyond {{taglink|range}}.
}}

===LaserCannon===
A particularly versatile line-of-sight weapon. Visually drawn like a [http://en.wikipedia.org/wiki/Star_Wars Star Wars] Blaster-style laser weapon, or a 3D model.

====LaserCannon Visuals====

{{tag
|name = duration
|type = float
|default = 0.05
|description = Multiplied against {{taglink|weaponVelocity}} to determine the visual length of the beam projectile.
}}

{{tag
|name = hardStop
|type = bool
|default = false
|description = Does the laser projectile stop dead or fade out?
}}

{{tag
|name = fallOffRate
|type = float
|default = 0.5
|description = Rate at which the beam fades out after it goes past its maximum {{taglink|range}} if {{taglink|hardStop|false}}. A value of <code>0.0</code> is never fade out, <code>1.0</code> is finish fading out exactly at maximum {{taglink|range}}.
}}

{{tag
|name = lodDistance
|type = int
|default = 1000
|description = Minimum camera distance at which the default LaserCannon projectile is simplified to a single rectangle.
}}

{{tag
|name = thickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = coreThickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = rgbColor2
|type = float
|default = {1.0, 1.0, 1.0}
|description = The colour of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

===LightningCannon===
An instant-hit weapon similar to the [[#BeamLaser]], but which does all its damage at once. Visually drawn like [http://en.wikipedia.org/wiki/Star_Wars Star Wars] 'Force Lightning' or [http://en.wikipedia.org/wiki/Command_%26_Conquer:_Red_Alert CnC: Red Alert] [http://en.wikipedia.org/wiki/Tesla_coil Tesla Coil] weapons, the effect is not very customisable.

There are no tags specific to this '''WeaponType'''.

===Melee===
A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters [http://en.wikipedia.org/wiki/Melee#Use_in_gaming 'melee'] weapon. It does not fire a projectile and does not care about the line of fire.

There are no tags specific to this '''WeaponType'''.

===MissileLauncher===
A versatile weapon which can optionally track targets and accelerate from a low initial velocity. It can also use {{taglink|trajectoryHeight}} to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = startVelocity
|type = float
|default = 0.0
|description = The initial velocity of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = weaponAcceleration
|type = float
|default = 0.0
|description = The initial acceleration of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Note that if it is <code>0.0</code> the weapon can never increase from its {{taglink|startVelocity}} and will not reach its maximum {{taglink|weaponVelocity}}. Since 99.0 <code>acceleration</code> is a synonym.
}}

{{tag
|name = tracks
|type = bool
|default = false
|description = Can the weapon projectile track a moving target? Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = The rate (in [[Elmo#Angular|cau]]) at which {{taglink|tracks|true}} weapons turn towards their target. This is relative to a projectile's current velocity; a weapon with a higher velocity will need a higher value in order to be able to hit targets that turn suddenly.}}

{{tag
|name = flightTime
|type = float
|default = 0.0
|description = The time in seconds before a missile projectile's fuel runs out; it ceases to obey {{taglink|tracks}}, loses velocity and falls to the ground. Also for [[#StarburstLauncher]]. Large values may cause over/undershoot problems.
}}

{{tag
|name = fixedLauncher
|type = bool
|default = false
|description = Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Weapons may not correctly obey [[#Collision & Avoidance|avoidance settings]] when using this tag.
}}

{{tag
|name = wobble
|type = float
|default = 0.0
|description = Adds a random vector to the direction of travel every 16 frames, multiplied by the value of the tag. The effect is reduced as the firing unit gains experience. As this missiles direction is changed, wobbling swarm of missiles will diverge.
}}

{{tag
|name = dance
|type = float
|default = 0.0
|description = Adds a random vector to the position of a missile projectile every 8 frames, multiplied by the value of the tag. As the projectile is not rotated, a dancing swarm of missiles will remain relatively coherent.
}}

{{tag
|name = trajectoryHeight
|type = float
|default = 0.0
|description = Determines the height of the arc the missile will reach as it moves towards its target. A value of <code>0.0</code> will result in a flat trajectory, <code>1.0</code> will launch at 45°. Can be any value >= <code>0.0</code>; extreme values may require the {{taglink|tracks}} tag to be able to hit a target.
}}

====MissileLauncher Visuals====
A note about the missile exhaust flare: the size of the flare is determined by the model radius. The emit position of the flare is at (0,0,-radius) so the model may need careful adjustment to get the flare looking right.

{{tag
|name = smokeTrail
|type = bool
|default = false
|description = Does the missile projectile emit a smoke trail as it travels? Also for [[#StarburstLauncher]].
}}

===Rifle===
An instant hit weapon which does all its damage at once. Visually represented by a hardcoded tracer, firing and hitting effects. Rarely used.

There are no tags specific to this '''WeaponType'''.

===Shield (WeaponType)===
As the name suggests, not a weapon but a defensive shield. Can absorb or deflect ({{taglink|repulsor|true}}) projectiles. Individual weapons can be set to be intercepted or not by the shield using a [http://en.wikipedia.org/wiki/Mask_(computing) bitmask] (see [[Shield Interception Tag Use]]). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible ({{taglink|visible|false}}).

See the [[#shield]] sub-table section for other tags specific to this type.

===StarburstLauncher===
Fires a projectile that rises vertically for {{taglink|weaponTimer}} seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. Before spring 92.0 was the only weapon that can be {{taglink|targetable}} and act as an {{taglink|interceptor}}. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = weaponTimer
|type = float
|default = 0.0
|description = The time in seconds during which the missile ascends vertically before turning towards its target.
}}

===TorpedoLauncher===
Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with {{taglink|waterWeapon|true}} so they can fire underwater and target underwater units. An aircraft carrying a [[#TorpedoLauncher]] is a special case, the weapon turns into an [[#AircraftBomb]] projectile that will spawn a torpedo projectile on impact with water. Visually represented by a pointed black cuboid, usually the default object is replaced by a 3D model.

{{tag
|name = subMissile
|type = bool
|default = false
|description = Can the torpedo leave the water and target units and positions on land?
}}

===NoWeapon===
Not actually a '''WeaponType''', but an individual weapon requested by Spring to 'fill in the gaps' if a unit claims to have a weapon which isn't actually defined. There needs to be only one of these weapons and it is created by setting {{taglink|weaponName|"NOWEAPON"}} rather than by the {{taglink|weaponType}} tag.

==Sub Tables==

===damage===
The damage subtable lists how many hit points the weapon depletes against each armor class (See [[Armordefs.lua]]). It is a key-value map of armor class names and damage values. The special <code>default</code> entry is as the name suggests the default damage applied to any unit which does not belong to a listed armor class, or to shields.

For example a weapon which deals 100 damage by default but only 50 to units in the 'tank' armor class:

<code><pre>damage = {
default = 100,
tank = 50,
}</pre></code>

===shield===
The preferred way to create a shield or repulser is to use the shield subtable rather than the old shield tags.

The following tags are repulser specific:

{{tag
|name = repulser
|type = bool
|default = false
|description = Does the shield [http://dictionary.reference.com/browse/repulse?s=t repulse] (deflect) projectiles or absorb them? Btw its [http://springrts.com/mantis/view.php?id=4206 not repulsOr, but repulsEr]!}}

{{tag
|name = force
|type = float
|default = 0.0
|description = The force applied by the repulser to the weapon - higher values will deflect weapons away at higher velocities.}}

{{tag
|name = maxSpeed
|type = float
|default = 0.0
|description = The maximum speed the repulser will impart to deflected projectiles.}}

{{tag
|name = visibleRepulse
|type = bool
|default = false
|description = Is the (hard-coded) repulse effect rendered or not?}}

The following tags are general behaviour for all shields:

{{tag
|name = interceptType
|type = int
|default = 0
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this shield can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptedByShieldType}} will be intercepted by this shield (See [[Shield Interception Tag Use]]).}}

{{tag
|name = armorType
|type = string
|default = ""
|description = Specifies the armorclass of the shield; you can input either an [[Armordefs.lua|armorclass]] name OR a unitdef {{xtaglink|Gamedev:UnitDefs|name}} to share that unit's armorclass.}}

{{tag
|name = smart
|type = bool
|default = false
|description = Determines whether or not projectiles fired by allied units can pass through the shield (<code>true</code>) or are intercepted as enemy weapons are (<code>false</code>).}}

{{tag
|name = exterior
|type = bool
|default = false
|description = Determines whether or not projectiles fired within the shield's radius can pass through the shield (<code>true</code>) or are intercepted (<code>false</code>).}}

{{tag
|name = energyUse
|type = float
|default = 0.0
|description = The amount of the energy resource consumed by the shield to absorb or repulse weapons, continually drained by a repulser as long as the projectile is in range.}}

{{tag
|name = radius
|type = float
|default = 0.0
|description = The radius of the circular area the shield covers.}}

{{tag
|name = power
|type = float
|default = 0.0
|description = Essentially the maximum allowed hit-points of the shield - reduced by the <code>damage</code> of a weapon upon impact.}}

{{tag
|name = startingPower
|type = float
|default = 0.0
|description = How many hit-points the shield starts with - otherwise the shield must regenerate from <code>0</code> until it reaches maximum {{taglink|power}}.}}

{{tag
|name = powerRegen
|type = float
|default = 0.0
|description = How many hit-points the shield regenerates each second.}}

{{tag
|name = powerRegenEnergy
|type = float
|default = 0.0
|description = How much energy resource is consumed to regenerate each hit-point.}}

{{tag
|name = rechargeDelay
|type = float
|default = 0.0
|description = The delay in seconds before a shield begins to regenerate after it is hit.}}

The following tags control the visual aspects of the shield:

{{tag
|name = visible
|type = bool
|default = false
|description = Is the shield visible or not?}}

{{tag
|name = visibleHitFrames
|type = int
|default = 0
|description = The number of frames a shield becomes visible for when hit.}}

{{tag
|name = badColor
|type = float[3]
|default = {1.0, 0.5, 0.5} (Red)
|description = The RGB colour the shield transitions to as its hit-points are reduced towards <code>0</code>.}}

{{tag
|name = goodColor
|type = float[3]
|default = {0.5, 0.5, 1.0} (Blue)
|description = The RGB colour the shield transitions to as its hit-points are regenerated towards its maximum {{taglink|power}}.}}

{{tag
|name = alpha
|type = float
|default = 0.2
|description = The alpha transparency of the shield whilst it is visible.}}

===customParams===
The <code>customParams</code> subtable of a WeaponDef allows the game designer to give their weapons 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==
Some games may have most WeaponDefs integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]].

S44 and MC:L implement an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance].

{{ExampleRepoLinks
|path = weapons/
|entity = WeaponDefs
}}

[[Category: Game Dev]]

Lua:Callins

2016-04-04T19:33:45Z

Pepeampere: /* Projectiles */

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

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

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

== Common ==
{{LuaCallin
|name = Initialize
|params =
|return = none
|description = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|params =
|return = none
|description = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

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

{{LuaCallin
|name = CommandNotify
|params = cmdID, cmdParams, cmdOptions
|return = bool removeCmd
|description = Called when a command is issued. Returning <code>true</code> deletes the command and does not send it through the network.
}}

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

{{LuaCallin
|name = WorldTooltip
|params = ttType, data1, data2, data3
|return = string newTooltip
|description = The parameters can be <code>"unit"</code>, <code>unitID</code>; <code>"feature"</code>, <code>featureID</code>; <code>"ground"</code>, <code>posX</code>, <code>posY</code>, <code>posZ</code> or <code>"selection"</code>.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|params = ???
|return = none
|description = Called when the unsynced copy of the height-map is altered.
}}

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

{{LuaCallin
|name = GameSetup
|params = state, ready, playerStates
|return = bool success, bool newReady
|description = ???
}}

{{LuaCallin
|name = SunChanged
|params = ???
|return = none
|description = ???
}}

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

{{LuaCallin
|name = RecvSkirmishAIMessage
|params = aiTeam, dataStr
|return = ???
|description = ???
}}

{{LuaCallin
|name = RecvFromSynced
|params = ...
|return = none
|description = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

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

{{LuaCallin
|name = LoadProgress
|params = message, replaceLastLine
|return = none
|description = Only available to LuaIntro.
}}

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

{{LuaCallin
|name = ConfigureLayout
|params = ???
|return = ???
|description = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|params = x, y
|return = bool isAbove
|description = Called every Update. Must return <code>true</code> for <code>Mouse*</code> events and <code>GetToolTip</code> to be called.
}}

{{LuaCallin
|name = GetTooltip
|params = x, y
|return = string tooltip
|description = Called when <code>IsAbove</code> returns true.
}}

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = bool becomeOwner
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value. Return <code>true</code> if you don't want other callins or the engine to also receive this keypress.
}}

{{LuaCallin
|name = KeyRelease
|params = key
|return = bool
|description = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|params = utf8char
|return = none
|description = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = MousePress
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is pressed. The <code>button</code> parameter supports up to 7 buttons. Must return <code>true</code> for <code>MouseRelease</code> and other functions to be called.
}}

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

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

{{LuaCallin
|name = MouseMove
|params = x, y, dx, dy, button
|return = none
|description = Called when the mouse is moved. The <code>dx</code> and <code>dy</code> parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|params = playerID
|return = none
|description = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|params = playerID
|return = none
|description = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|params = playerID, reason
|return = none
|description = Called whenever a player is removed from the game.
}}

=== Drawing ===

{{LuaCallin
|name = ViewResize
|params = viewSizeX, viewSizeY
|return = none
|description = Called whenever the window is resized.
}}

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

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

{{LuaCallin
|name = DrawGenesis
|params =
|return = none
|description = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

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

{{LuaCallin
|name = DrawWorld
|params =
|return = none
|description = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreen
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|params = vsx, vsy
|return = none
|description = Where <code>vsx</code>, <code>vsy</code> are screen coordinates.
}}

{{LuaCallin
|name = DrawLoadScreen
|params =
|return = none
|description = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls <code>drawMode</code> can be one of the following, <code>notDrawing = 0</code>, <code>normalDraw = 1</code>, <code>shadowDraw = 2</code>, <code>reflectionDraw = 3</code>, <code>refractionDraw = 4</code>.

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

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

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

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

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|params = msg, player
|return = none
|description = Called when a player issues a UI command e.g. types <code>/foo</code> or <code>/luarules foo</code>.
}}

=== Game ===

{{LuaCallin
|name = GameID
|params = gameID
|return = none
|description = Called once to deliver the gameID.
}}

{{LuaCallin
|name = GamePaused
|params =
|return = none
|description = Called when the game is paused.
}}

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

{{LuaCallin
|name = GameFrame
|params = frame
|return = none
|description = Called for every game simulation frame (30 per second).
}}

{{LuaCallin
|name = GamePreload
|params =
|return = none
|description = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|params =
|return = none
|description = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|params = teamID
|return = none
|description = ???
}}

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

=== Units ===
{{LuaCallin
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|return = none
|description = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|return = none
|description = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is damaged (after <code>UnitPreDamaged</code>).
}}

{{LuaCallin
|name = UnitDestroyed
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is destroyed.
}}

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

{{LuaCallin
|name = UnitStunned
|params = unitID, unitDefID, unitTeam, stunned
|return = none
|description = Called when a unit changes its stun status. {{new|99.0}}
}}

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

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

{{LuaCallin
|name = UnitCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}

{{LuaCallin
|name = UnitCmdDone
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|return = none
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

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

{{LuaCallin
|name = UnitEnteredLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

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

=== Features ===
{{LuaCallin
|name = FeatureCreated
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is created.
}}

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

{{LuaCallin
|name = FeatureDestroyed
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|params = ???
|return = none
|description = ???
}}

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

{{LuaCallin
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|return = none
|description = Called when the projectile is created.
}}

:<span class=warning>note1 <code>weaponDefID</code> is missing in case the projectile is spawned as part of the burst</span>
:
:note2: <code>Spring.GetProjectileDefID</code> and <code>Spring.GetProjectileName</code> still work in callin scope using <code>proID</code>

{{LuaCallin
|name = ProjectileDestroyed
|params = proID
|return = none
|description = Called when the projectile is destroyed.
}}

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = AllowStartPosition
|params = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = bool allow
|description = <code>clamped</code> are the coordinates clamped into start-boxes, <code>raw</code> is where player tried to place their marker. The <code>readyState</code> can be any one of
* <code>0</code> - player picked a position,
* <code>1</code> - player clicked ready,
* <code>2</code> - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* <code>3</code> - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or <code>(0,0,0)</code> if they do not have a startbox.
}}

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

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

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

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

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

{{LuaCallin
|name = Explosion
|params = weaponDefID, px, py, pz, AttackerID
|return = bool noGfx
|description = Called when an explosion occurs. If it returns <code>true</code> then no graphical effects are drawn by the engine for this explosion.
}}

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

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

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

{{LuaCallin
|name = Load
|params = zip
|return = none
|description = Called after <code>GamePreload</code> and before <code>GameStart</code>. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

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

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

{{LuaCallin
|name = ShieldPreDamaged
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = bool handleCollision
|description = Called before any engine shield-vs-projectile logic executes. If the return value is <code>true</code> the gadget handles the collision event and the engine does not remove the projectile.
}}

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

[[Category: Lua]]

Lua:Callins

2016-04-04T19:31:11Z

Pepeampere: /* Projectiles */

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

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

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

== Common ==
{{LuaCallin
|name = Initialize
|params =
|return = none
|description = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|params =
|return = none
|description = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

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

{{LuaCallin
|name = CommandNotify
|params = cmdID, cmdParams, cmdOptions
|return = bool removeCmd
|description = Called when a command is issued. Returning <code>true</code> deletes the command and does not send it through the network.
}}

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

{{LuaCallin
|name = WorldTooltip
|params = ttType, data1, data2, data3
|return = string newTooltip
|description = The parameters can be <code>"unit"</code>, <code>unitID</code>; <code>"feature"</code>, <code>featureID</code>; <code>"ground"</code>, <code>posX</code>, <code>posY</code>, <code>posZ</code> or <code>"selection"</code>.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|params = ???
|return = none
|description = Called when the unsynced copy of the height-map is altered.
}}

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

{{LuaCallin
|name = GameSetup
|params = state, ready, playerStates
|return = bool success, bool newReady
|description = ???
}}

{{LuaCallin
|name = SunChanged
|params = ???
|return = none
|description = ???
}}

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

{{LuaCallin
|name = RecvSkirmishAIMessage
|params = aiTeam, dataStr
|return = ???
|description = ???
}}

{{LuaCallin
|name = RecvFromSynced
|params = ...
|return = none
|description = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

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

{{LuaCallin
|name = LoadProgress
|params = message, replaceLastLine
|return = none
|description = Only available to LuaIntro.
}}

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

{{LuaCallin
|name = ConfigureLayout
|params = ???
|return = ???
|description = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|params = x, y
|return = bool isAbove
|description = Called every Update. Must return <code>true</code> for <code>Mouse*</code> events and <code>GetToolTip</code> to be called.
}}

{{LuaCallin
|name = GetTooltip
|params = x, y
|return = string tooltip
|description = Called when <code>IsAbove</code> returns true.
}}

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = bool becomeOwner
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value. Return <code>true</code> if you don't want other callins or the engine to also receive this keypress.
}}

{{LuaCallin
|name = KeyRelease
|params = key
|return = bool
|description = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|params = utf8char
|return = none
|description = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = MousePress
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is pressed. The <code>button</code> parameter supports up to 7 buttons. Must return <code>true</code> for <code>MouseRelease</code> and other functions to be called.
}}

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

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

{{LuaCallin
|name = MouseMove
|params = x, y, dx, dy, button
|return = none
|description = Called when the mouse is moved. The <code>dx</code> and <code>dy</code> parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|params = playerID
|return = none
|description = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|params = playerID
|return = none
|description = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|params = playerID, reason
|return = none
|description = Called whenever a player is removed from the game.
}}

=== Drawing ===

{{LuaCallin
|name = ViewResize
|params = viewSizeX, viewSizeY
|return = none
|description = Called whenever the window is resized.
}}

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

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

{{LuaCallin
|name = DrawGenesis
|params =
|return = none
|description = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

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

{{LuaCallin
|name = DrawWorld
|params =
|return = none
|description = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreen
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|params = vsx, vsy
|return = none
|description = Where <code>vsx</code>, <code>vsy</code> are screen coordinates.
}}

{{LuaCallin
|name = DrawLoadScreen
|params =
|return = none
|description = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls <code>drawMode</code> can be one of the following, <code>notDrawing = 0</code>, <code>normalDraw = 1</code>, <code>shadowDraw = 2</code>, <code>reflectionDraw = 3</code>, <code>refractionDraw = 4</code>.

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

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

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

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

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|params = msg, player
|return = none
|description = Called when a player issues a UI command e.g. types <code>/foo</code> or <code>/luarules foo</code>.
}}

=== Game ===

{{LuaCallin
|name = GameID
|params = gameID
|return = none
|description = Called once to deliver the gameID.
}}

{{LuaCallin
|name = GamePaused
|params =
|return = none
|description = Called when the game is paused.
}}

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

{{LuaCallin
|name = GameFrame
|params = frame
|return = none
|description = Called for every game simulation frame (30 per second).
}}

{{LuaCallin
|name = GamePreload
|params =
|return = none
|description = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|params =
|return = none
|description = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|params = teamID
|return = none
|description = ???
}}

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

=== Units ===
{{LuaCallin
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|return = none
|description = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|return = none
|description = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is damaged (after <code>UnitPreDamaged</code>).
}}

{{LuaCallin
|name = UnitDestroyed
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is destroyed.
}}

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

{{LuaCallin
|name = UnitStunned
|params = unitID, unitDefID, unitTeam, stunned
|return = none
|description = Called when a unit changes its stun status. {{new|99.0}}
}}

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

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

{{LuaCallin
|name = UnitCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}

{{LuaCallin
|name = UnitCmdDone
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|return = none
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

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

{{LuaCallin
|name = UnitEnteredLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

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

=== Features ===
{{LuaCallin
|name = FeatureCreated
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is created.
}}

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

{{LuaCallin
|name = FeatureDestroyed
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|params = ???
|return = none
|description = ???
}}

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

{{LuaCallin
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|return = none
|description = Called when the projectile is created.
}}

<span class=warning>note1 '''weaponDefID''' is missing in case the projectile is spawned as part of the burst</span>

note2: Spring.GetProjectileDefID and Spring.GetProjectileName still work in callin scope using proID

{{LuaCallin
|name = ProjectileDestroyed
|params = proID
|return = none
|description = Called when the projectile is destroyed.
}}

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = AllowStartPosition
|params = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = bool allow
|description = <code>clamped</code> are the coordinates clamped into start-boxes, <code>raw</code> is where player tried to place their marker. The <code>readyState</code> can be any one of
* <code>0</code> - player picked a position,
* <code>1</code> - player clicked ready,
* <code>2</code> - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* <code>3</code> - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or <code>(0,0,0)</code> if they do not have a startbox.
}}

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

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

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

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

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

{{LuaCallin
|name = Explosion
|params = weaponDefID, px, py, pz, AttackerID
|return = bool noGfx
|description = Called when an explosion occurs. If it returns <code>true</code> then no graphical effects are drawn by the engine for this explosion.
}}

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

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

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

{{LuaCallin
|name = Load
|params = zip
|return = none
|description = Called after <code>GamePreload</code> and before <code>GameStart</code>. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

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

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

{{LuaCallin
|name = ShieldPreDamaged
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = bool handleCollision
|description = Called before any engine shield-vs-projectile logic executes. If the return value is <code>true</code> the gadget handles the collision event and the engine does not remove the projectile.
}}

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

[[Category: Lua]]

Lua:Callins

2016-04-04T19:22:57Z

Pepeampere: /* Projectiles */ issue with ProjectileCreated

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

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

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

== Common ==
{{LuaCallin
|name = Initialize
|params =
|return = none
|description = Called when the addon is (re)loaded.
}}

{{LuaCallin
|name = Shutdown
|params =
|return = none
|description = Called when the addon or the game is shutdown.
}}

== Unsynced Only ==

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

{{LuaCallin
|name = CommandNotify
|params = cmdID, cmdParams, cmdOptions
|return = bool removeCmd
|description = Called when a command is issued. Returning <code>true</code> deletes the command and does not send it through the network.
}}

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

{{LuaCallin
|name = WorldTooltip
|params = ttType, data1, data2, data3
|return = string newTooltip
|description = The parameters can be <code>"unit"</code>, <code>unitID</code>; <code>"feature"</code>, <code>featureID</code>; <code>"ground"</code>, <code>posX</code>, <code>posY</code>, <code>posZ</code> or <code>"selection"</code>.
}}

{{LuaCallin
|name = UnsyncedHeightMapUpdate
|params = ???
|return = none
|description = Called when the unsynced copy of the height-map is altered.
}}

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

{{LuaCallin
|name = GameSetup
|params = state, ready, playerStates
|return = bool success, bool newReady
|description = ???
}}

{{LuaCallin
|name = SunChanged
|params = ???
|return = none
|description = ???
}}

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

{{LuaCallin
|name = RecvSkirmishAIMessage
|params = aiTeam, dataStr
|return = ???
|description = ???
}}

{{LuaCallin
|name = RecvFromSynced
|params = ...
|return = none
|description = Receives data sent via [[Lua_System#Synced|SendToUnsynced]] callout.
}}

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

{{LuaCallin
|name = LoadProgress
|params = message, replaceLastLine
|return = none
|description = Only available to LuaIntro.
}}

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

{{LuaCallin
|name = ConfigureLayout
|params = ???
|return = ???
|description = ???
}}

=== Input ===
{{LuaCallin
|name = IsAbove
|params = x, y
|return = bool isAbove
|description = Called every Update. Must return <code>true</code> for <code>Mouse*</code> events and <code>GetToolTip</code> to be called.
}}

{{LuaCallin
|name = GetTooltip
|params = x, y
|return = string tooltip
|description = Called when <code>IsAbove</code> returns true.
}}

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = bool becomeOwner
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value. Return <code>true</code> if you don't want other callins or the engine to also receive this keypress.
}}

{{LuaCallin
|name = KeyRelease
|params = key
|return = bool
|description = Called when the key is released.
}}

{{LuaCallin
|name = TextInput
|params = utf8char
|return = none
|description = Called whenever a key press results in text input. Introduced in 97.0.
}}

{{LuaCallin
|name = JoystickEvent
|params = ???
|return = none
|description = ???
}}

{{LuaCallin
|name = MousePress
|params = x, y, button
|return = bool becomeMouseOwner
|description = Called when a mouse button is pressed. The <code>button</code> parameter supports up to 7 buttons. Must return <code>true</code> for <code>MouseRelease</code> and other functions to be called.
}}

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

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

{{LuaCallin
|name = MouseMove
|params = x, y, dx, dy, button
|return = none
|description = Called when the mouse is moved. The <code>dx</code> and <code>dy</code> parameters indicate the distance travelled, whereas the first two indicate the final position.
}}

=== Players ===
{{LuaCallin
|name = PlayerChanged
|params = playerID
|return = none
|description = Called whenever a player's status changes e.g. becoming a spectator.
}}

{{LuaCallin
|name = PlayerAdded
|params = playerID
|return = none
|description = Called whenever a new player joins the game.
}}

{{LuaCallin
|name = PlayerRemoved
|params = playerID, reason
|return = none
|description = Called whenever a player is removed from the game.
}}

=== Drawing ===

{{LuaCallin
|name = ViewResize
|params = viewSizeX, viewSizeY
|return = none
|description = Called whenever the window is resized.
}}

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

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

{{LuaCallin
|name = DrawGenesis
|params =
|return = none
|description = Doesn't render to screen! Use this callin to update textures, shaders, etc.
}}

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

{{LuaCallin
|name = DrawWorld
|params =
|return = none
|description = Spring draws command queues, 'map stuff', and map marks.
}}

{{LuaCallin
|name = DrawWorldShadow
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldReflection
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawWorldRefraction
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreen
|params =
|return = none
|description = ???
}}

{{LuaCallin
|name = DrawScreenEffects
|params = vsx, vsy
|return = none
|description = Where <code>vsx</code>, <code>vsy</code> are screen coordinates.
}}

{{LuaCallin
|name = DrawLoadScreen
|params =
|return = none
|description = {{new|95.0}} Only available to LuaIntro, draws custom load screens.
}}

{{LuaCallin
|name = DrawInMinimap
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

{{LuaCallin
|name = DrawInMinimapBackground
|params = sx, sy
|return = none
|description = Where <code>sx</code>, <code>sy</code> are values relative to the minimap's position and scale.
}}

=== Custom Object Rendering ===
For the following calls <code>drawMode</code> can be one of the following, <code>notDrawing = 0</code>, <code>normalDraw = 1</code>, <code>shadowDraw = 2</code>, <code>reflectionDraw = 3</code>, <code>refractionDraw = 4</code>.

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

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

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

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

== Synced - Unsynced Shared ==

{{LuaCallin
|name = GotChatMsg
|params = msg, player
|return = none
|description = Called when a player issues a UI command e.g. types <code>/foo</code> or <code>/luarules foo</code>.
}}

=== Game ===

{{LuaCallin
|name = GameID
|params = gameID
|return = none
|description = Called once to deliver the gameID.
}}

{{LuaCallin
|name = GamePaused
|params =
|return = none
|description = Called when the game is paused.
}}

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

{{LuaCallin
|name = GameFrame
|params = frame
|return = none
|description = Called for every game simulation frame (30 per second).
}}

{{LuaCallin
|name = GamePreload
|params =
|return = none
|description = Called before the 0 gameframe.
}}

{{LuaCallin
|name = GameStart
|params =
|return = none
|description = Called upon the start of the game.
}}

=== Teams ===
{{LuaCallin
|name = TeamChanged
|params = teamID
|return = none
|description = ???
}}

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

=== Units ===
{{LuaCallin
|name = UnitCreated
|params = unitID, unitDefID, unitTeam, builderID
|return = none
|description = Called at the moment the unit is created.
}}

{{LuaCallin
|name = UnitFinished
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called at the moment the unit is completed.
}}

{{LuaCallin
|name = UnitFromFactory
|params = unitID, unitDefID, unitTeam, factID, factDefID, userOrders
|return = none
|description = Called when a factory finishes construction of a unit.
}}

{{LuaCallin
|name = UnitGiven
|params = unitID, unitDefID, newTeam, oldTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitTaken
|params = unitID, unitDefID, oldTeam, newTeam
|return = none
|description = Called when a unit is transferred between teams.
}}

{{LuaCallin
|name = UnitDamaged
|params = unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is damaged (after <code>UnitPreDamaged</code>).
}}

{{LuaCallin
|name = UnitDestroyed
|params = unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam
|return = none
|description = Called when a unit is destroyed.
}}

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

{{LuaCallin
|name = UnitStunned
|params = unitID, unitDefID, unitTeam, stunned
|return = none
|description = Called when a unit changes its stun status. {{new|99.0}}
}}

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

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

{{LuaCallin
|name = UnitCommand
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called after when a unit accepts a command, after <code>AllowCommand</code> returns <code>true</code>.
}}

{{LuaCallin
|name = UnitCmdDone
|params = unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOpts, cmdTag
|return = none
|description = Called when a unit completes a command.
}}

{{LuaCallin
|name = UnitLoaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is loaded by a transport.
}}

{{LuaCallin
|name = UnitUnloaded
|params = unitID, unitDefID, unitTeam, transportID, transportTeam
|return = none
|description = Called when a unit is unloaded by a transport.
}}

{{LuaCallin
|name = UnitExperience
|params = unitID, unitDefID, unitTeam, experience, oldExperience
|return = none
|description = Called when a unit gains experience greater or equal to the minimum limit set by calling [[Lua_SyncedCtrl#Other|Spring.SetExperienceGrade]].
}}

{{LuaCallin
|name = UnitIdle
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit is idle (empty command queue).
}}

{{LuaCallin
|name = UnitCloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit cloaks.
}}

{{LuaCallin
|name = UnitDecloaked
|params = unitID, unitDefID, unitTeam
|return = none
|description = Called when a unit decloaks.
}}

{{LuaCallin
|name = UnitMoved
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

{{LuaCallin
|name = UnitMoveFailed
|params = ???
|return = none
|description = ??? Not implemented in base handler
}}

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

{{LuaCallin
|name = UnitEnteredLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters LOS of an allyteam.
}}

{{LuaCallin
|name = UnitLeftLos
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves LOS of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit enters radar of an allyteam.
}}

{{LuaCallin
|name = UnitLeftRadar
|params = unitID, unitTeam, allyTeam, unitDefID
|return = none
|description = Called when a unit leaves radar of an allyteam.
}}

{{LuaCallin
|name = UnitEnteredAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftAir
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitEnteredWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

{{LuaCallin
|name = UnitLeftWater
|params = ???
|return = none
|description = ??? Not implemented by base handler
}}

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

=== Features ===
{{LuaCallin
|name = FeatureCreated
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is created.
}}

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

{{LuaCallin
|name = FeatureDestroyed
|params = featureID, allyTeamID
|return = none
|description = Called when a feature is destroyed.
}}

{{LuaCallin
|name = FeatureMoved
|params = ???
|return = none
|description = ???
}}

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

{{LuaCallin
|name = ProjectileCreated
|params = proID, proOwnerID, weaponDefID
|return = none
|description = Called when the projectile is created.
}}

<span class=warning>! '''weaponDefID''' is missing in case the projectile is spawned as part of the burst</span>

{{LuaCallin
|name = ProjectileDestroyed
|params = proID
|return = none
|description = Called when the projectile is destroyed.
}}

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = AllowStartPosition
|params = clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ
|return = bool allow
|description = <code>clamped</code> are the coordinates clamped into start-boxes, <code>raw</code> is where player tried to place their marker. The <code>readyState</code> can be any one of
* <code>0</code> - player picked a position,
* <code>1</code> - player clicked ready,
* <code>2</code> - player pressed ready OR the game was force-started (player did not click ready, but is now forcibly readied) or
* <code>3</code> - the player failed to load.
* {{new|95.0}} the default 'failed to choose' start-position is the north-west point of their startbox, or <code>(0,0,0)</code> if they do not have a startbox.
}}

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

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

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

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

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

{{LuaCallin
|name = Explosion
|params = weaponDefID, px, py, pz, AttackerID
|return = bool noGfx
|description = Called when an explosion occurs. If it returns <code>true</code> then no graphical effects are drawn by the engine for this explosion.
}}

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

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

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

{{LuaCallin
|name = Load
|params = zip
|return = none
|description = Called after <code>GamePreload</code> and before <code>GameStart</code>. See [[Lua_SaveLoad#Load_.28_zip_.29_-.3E_nil|Lua_SaveLoad]].
}}

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

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

{{LuaCallin
|name = ShieldPreDamaged
|params = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile
|return = bool handleCollision
|description = Called before any engine shield-vs-projectile logic executes. If the return value is <code>true</code> the gadget handles the collision event and the engine does not remove the projectile.
}}

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

[[Category: Lua]]

GamesDownloads

2015-11-29T19:45:15Z

Pepeampere: fixing typo

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}} <span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows & Linux (mono))
<span class="warning">(!)</span> Can not connect to spring multiplayer server. zero-K uses a seperate server and the lobby does not fully support other games.

{{Template:GamesDownload|name=NOTA|image=notAgame02.jpg|url=http://nota.machys.net/downloads}}
(Windows)

<span class="warning">(!)</span> This lobby is limited to playing game NOTA and the client itself in not open source.

</div>

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=https://github.com/springlobby/springlobby/wiki/Install}}
(Multiplatform)

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
(Windows & Linux)

{{Template:GamesDownload|name=pr-downloader (command-line)|url=http://springrts.com/wiki/Pr-downloader}}

</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

[[Category:Spring]]

GamesDownloads

2015-11-29T19:44:52Z

Pepeampere: updating the link and rephrasing the warning

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}} <span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows & Linux (mono))
<span class="warning">(!)</span> Can not connect to spring multiplayer server. zero-K uses a seperate server and the lobby does not fully support other games.

{{Template:GamesDownload|name=NOTA|image=notAgame02.jpg|url=link=http://nota.machys.net/downloads}}
(Windows)

<span class="warning">(!)</span> This lobby is limited to playing game NOTA and the client itself in not open source.

</div>

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=https://github.com/springlobby/springlobby/wiki/Install}}
(Multiplatform)

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
(Windows & Linux)

{{Template:GamesDownload|name=pr-downloader (command-line)|url=http://springrts.com/wiki/Pr-downloader}}

</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

[[Category:Spring]]

GamesDownloads

2015-11-08T14:08:04Z

Pepeampere: update nota screenshot

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}} <span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows & Linux (mono))
<span class="warning">(!)</span> Can not connect to spring multiplayer server. zero-K uses a seperate server and the lobby does not fully support other games.

{{Template:GamesDownload|name=NOTA|image=notAgame02.jpg|url=http://nota.machys.net/lobby/download_lobby.php}}
(Windows)

<span class="warning">(!)</span> This lobby is limited to playing NOTA content and uses a proprietary license / is closed source.

</div>

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=https://github.com/springlobby/springlobby/wiki/Install}}
(Multiplatform)

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
(Windows & Linux)

{{Template:GamesDownload|name=pr-downloader (command-line)|url=http://springrts.com/wiki/Pr-downloader}}

</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

[[Category:Spring]]

Games

2015-11-08T14:07:25Z

Pepeampere: update nota screenshot

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Game can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| | <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://springfiles.com/spring/games/edge-1}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|-
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
| width=40 |
| align="center" width="300px" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|
| align="center" |
|-
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|
| align="justify" valign="top" |
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
| width=40 |
| align="center" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" |
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| | <h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
| width=40 |
| | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| | {{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)

|-
| | <h2>[http://nota.machys.net/downloads NOTA]</h2>
| width=40 |
| | <h2> [[XTA]] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=notAgame02.jpg|link=http://nota.machys.net/downloads}}
| width=40 |
| | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
| width=40 |
| valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

File:NotAgame02.jpg

2015-11-08T14:05:46Z

Pepeampere: notAgame

notAgame

Games

2015-11-07T21:42:42Z

Pepeampere: not direct link to downloaded of NOTA, just to download page

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Game can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| | <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://springfiles.com/spring/games/edge-1}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|-
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
| width=40 |
| align="center" width="300px" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|
| align="center" |
|-
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|
| align="justify" valign="top" |
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
| width=40 |
| align="center" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" |
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| | <h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
| width=40 |
| | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| | {{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)

|-
| | <h2>[http://nota.machys.net/downloads NOTA]</h2>
| width=40 |
| | <h2> [[XTA]] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://nota.machys.net/downloads}}
| width=40 |
| | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
| width=40 |
| valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

GamesDownloads

2015-11-04T14:18:25Z

Pepeampere: moved warning for old engine to prope palce

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}} <span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows & Linux (mono))

{{Template:GamesDownload|name=NOTA|image=Nota2nukes.jpg|url=http://nota.machys.net/lobby/download_lobby.php}}
(Windows)

</div>

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=https://github.com/springlobby/springlobby/wiki/Install}}
(Multiplatform)

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
(Windows & Linux)

{{Template:GamesDownload|name=pr-downloader (command-line)|url=http://springrts.com/wiki/Pr-downloader}}

</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

[[Category:Spring]]

Games

2015-11-04T14:16:18Z

Pepeampere: forgotten link, same comment as edit before

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Game can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| | <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://springfiles.com/spring/games/edge-1}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|-
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
| width=40 |
| align="center" width="300px" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|
| align="center" |
|-
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|
| align="justify" valign="top" |
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
| width=40 |
| align="center" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" |
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| | <h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
| width=40 |
| | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| | {{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)

|-
| | <h2>[http://nota.machys.net/lobby/download_lobby.php NOTA]</h2>
| width=40 |
| | <h2> [[XTA]] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://nota.machys.net/lobby/download_lobby.php}}
| width=40 |
| | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
| width=40 |
| valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Games

2015-11-04T12:52:06Z

Pepeampere: Adding new link to NOTA downloads based on this: https://springrts.com/phpbb/viewtopic.php?f=1&t=34014

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

You can download games automatically, using your lobby (see [[Read_Me_First|Read Me First]]).

Game can also be [[Getting_Spring_Content_and_Links|downloaded manually]], as sdz files, and placed into ../Spring/Games. Read the advice on [[Read_Me_First|this page]] if your lobby does not find your games. Some games also offer a stand-alone installer.

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| | <h2>'''[http://springfiles.com/spring/games/edge-1 On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://springfiles.com/spring/games/edge-1}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|-
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
([http://creativecommons.org/licenses/by-nc-sa/4.0 CC-BY-NC-SA])
| width=40 |
| align="center" width="300px" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|
| align="center" |
|-
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|
| align="justify" valign="top" |
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games include large GPL-friendly content collections.''

{|
|-
| width="300px" | <h2> [https://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter] </h2>
| width=40 |
| align="center" |
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=https://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" |
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| | <h2> [http://springrts.com/wiki/Balanced_Annihilation Balanced Annihilation] </h2>
| width=40 |
| | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://springrts.com/phpbb/viewforum.php?f=44}}
|
| | {{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)

|-
| | <h2>[http://nota.machys.net/lobby/download_lobby.php NOTA]</h2>
| width=40 |
| | <h2> [[XTA]] </h2>
|-
| | {{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://springfiles.com/spring/games/nota-37}}
| width=40 |
| | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
| width=40 |
| valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

GamesDownloads

2015-11-04T12:50:25Z

Pepeampere:

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}}

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows & Linux (mono))

{{Template:GamesDownload|name=NOTA|image=Nota2nukes.jpg|url=http://nota.machys.net/lobby/download_lobby.php}}
(Windows)

</div>

<span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=https://github.com/springlobby/springlobby/wiki/Install}}
(Multiplatform)

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
(Windows & Linux)

{{Template:GamesDownload|name=pr-downloader (command-line)|url=http://springrts.com/wiki/Pr-downloader}}

</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

[[Category:Spring]]

GamesDownloads

2015-11-04T12:49:42Z

Pepeampere: added NOTA installer, based on this https://springrts.com/phpbb/viewtopic.php?f=1&t=34014

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}}

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows & Linux (mono))

{{Template:GamesDownload|name=NOTA|image=image=Nota2nukes.jpg|url=http://nota.machys.net/lobby/download_lobby.php}}
(Windows)

</div>

<span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=https://github.com/springlobby/springlobby/wiki/Install}}
(Multiplatform)

{{Template:GamesDownload|name=Spring Web Lobby|image=Blobby.png|url=http://weblobby.springrts.com}}
(Windows & Linux)

{{Template:GamesDownload|name=pr-downloader (command-line)|url=http://springrts.com/wiki/Pr-downloader}}

</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

[[Category:Spring]]

CollectionOfStuff

2014-05-17T18:02:41Z

Pepeampere:

At least a million widgets and gadgets have been done in Spring. But alot of cool things are lost because the game vanished or the idea never made it into a public release. Many items from [[Monthly_Topic_Rotation]] are actually done or could be done.

It also annoyed me that there are often forum threads where somebody explains in detail how to do something but its just lost in spam.
So here is a collection of random things.

Some of the stuff might be outdated or rough "proves of concept":

===Linked Units: if parent units dies, child units die too===
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435
pseudo code + working gadget

===Widget+Gadget - CEG Spawner===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24499
working widget+gadget with chili ui

===picture in picture screen===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24485
working widget

===Tower Defense===
http://springrts.com/phpbb/viewtopic.php?f=14&t=22816
ideas how it could be done

http://springrts.com/phpbb/viewtopic.php?f=55&t=28696
TTD = Transportable Tower Defence mission - working example

===cover system / units taking cover behind features etc===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24820
ideas, code to check if unit is in cover.
is now in spring tanks and evoRTS

===collecting data from spring games===
====Unit path tracer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=23584
====build order visualizer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=26360
====unit movement, destruction, building placement====
http://springrts.com/phpbb/viewtopic.php?f=1&t=22571
====unit effectiveness by reading XP on destruction====
http://springrts.com/phpbb/viewtopic.php?f=44&t=26092
====unit movement, automatic visual replay in SVG ====
http://springrts.com/phpbb/viewtopic.php?f=55&t=28808
notAtv

===Ingame hitbox editor===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24882
dynamic hitboxes, reading button presses from keyboard

===Teleport areas (for units entering them), wrap around map===
http://springrts.com/phpbb/viewtopic.php?f=43&t=24611
working map with gadget

===Posing units ingame by moving/rotating pieces to create keyframes or w/e===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25104
hackish but working widget,gadget,unitscript brew

===non clumping aircraft===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24811
tags that make aircraft not clump

===Multiple parts units, targeting parts of units (ie head or turret)===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24590
discussion

===different resource names (ie "wood" instead of "metal")===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24771&p=462461&hilit=wood+metal#p462461
an ugly widget

===Units that die after a specified life time===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25461
different ways to do it, working example

===3D drawing library, weapon ranges in 3D, animated water===
http://springrts.com/phpbb/viewtopic.php?f=23&t=17935
zip file with various stuff

===finite/limited metal===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26026

===maps with lava===
http://springrts.com/phpbb/viewtopic.php?f=13&t=25517
nicer lava with shaders:
http://springrts.com/phpbb/viewtopic.php?f=13&t=26698 ,
http://springrts.com/phpbb/viewtopic.php?f=23&t=31159

===multi touch interaction===
http://springrts.com/phpbb/viewtopic.php?f=12&t=25865

===game mode: score points by dealing damage to a neutral unit===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26241

===neat animations===
http://springrts.com/phpbb/viewtopic.php?f=9&t=8864&start=7962

===tech tree===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20680

===seperate players by a wall & timer===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
map with working gadget

===colored text===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26341
some info about colors

===How to make a ballistic weapon arc just a little===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26660
different ways to do it

===melee combat===
http://springrts.com/phpbb/viewtopic.php?f=14&t=14373
ideas, some pictures, script pieces

===peace time to seperate teams before they can attack each other===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
a map that does that

===CEGs and unitDefs===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26612
some other way to do it

===noobs coming to mod spring===
collection of "hi iam new" threads
http://springrts.com/phpbb/viewtopic.php?f=14&t=26642
http://springrts.com/phpbb/viewtopic.php?f=14&t=26604
http://springrts.com/phpbb/viewtopic.php?f=14&t=26519
http://springrts.com/phpbb/viewtopic.php?f=14&t=26216
http://springrts.com/phpbb/viewtopic.php?f=1&t=27739

===creating new units in unitdefs_post.lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26078

===Turret rotating independant from unit chassis===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26727&p=499627
example script pieces

===units avoiding enemy units===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26811
widget based on a paper

===nicer map edges===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26732
discussion, "endless texture"-widget on page 2<br>
several versions from different people now in various games

===Spring with 3D glasses===
http://springrts.com/phpbb/viewtopic.php?f=1&t=19995
widget

===AI Ladder "SpringGrid"===
http://springrts.com/phpbb/viewtopic.php?f=15&t=20830
now dead project, source files available

===Moving Metal Extractors (Mobile Mex)===
http://springrts.com/phpbb/viewtopic.php?f=23&t=11335 http://springrts.com/phpbb/viewtopic.php?f=14&t=26877
working scripts

===fun with factories===
====mobile factory====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27503
script
====Multiple build pads possible?====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27615
====building multiple units at once====
http://springrts.com/phpbb/viewtopic.php?f=14&t=28092

===web lobby in browser===
http://springrts.com/phpbb/viewtopic.php?f=64&t=26414

===chat about engine trees===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27189

===BA with "Red Alert" eco===
http://springrts.com/phpbb/viewtopic.php?f=44&t=27173
working game with ore based economy

===can I force a unit to shoot allies?===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27114
ideas, talk

===forest fires with Lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27015
experiments

=== sharing variables across widgets (and making sure they all get them) ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27408

=== pixel shaders with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20932 simple shader example

http://springrts.com/phpbb/viewtopic.php?f=23&t=27269 even more primitive

=== railroad / train units ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=17137
very old but cool techdemo (probally needs fixing for current spring)

=== benchmarking spring ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27411 something about some tool and similiar threads (Phoronix Test Suite)

=== Lua Lobby ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27329 blabla about how to (not) implent it

http://springrts.com/phpbb/viewtopic.php?f=12&t=27526
Lua Sockets implented in engine

=== "Mini Games" with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=19300
http://springrts.com/phpbb/viewtopic.php?f=23&t=19030
Tetris, Pacman, Snake, Pong

=== Camera at fixed height ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20818
widget code

=== Lua IDE ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27608
my text editor is better than yours

=== common Lua mistakes ===
a widget ''so bad'' we can all learn from it \o/
http://springrts.com/phpbb/viewtopic.php?f=23&t=28113

=== (mapping) Good way to generate detail texture distribution ===
http://springrts.com/phpbb/viewtopic.php?f=13&t=28026

=== (mapping) Proceduraly created map ===
http://springrts.com/phpbb/viewtopic.php?f=55&t=31122
notAmap - procedural shape of map + set of nice hills

=== visible LOS / fog of war ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=28062
lua, engine

=== third person controlling a unit ===
http://springrts.com/phpbb/viewtopic.php?f=54&t=27013&start=10
gadget, mutator

=== Lua weapondefs with inheritance ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=28123

=== Multiple unit/feature/weapon defs per file ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26888

=== texture size and atlases ===
http://springrts.com/phpbb/viewtopic.php?f=9&t=29938&p=538020

=== scale a unit bigger in gadget:DrawWorld ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=29934

=== projectiles, SetProjectileTarget ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=31799
example gadget

[[Category:Game Dev]]

CollectionOfStuff

2014-05-17T17:57:59Z

Pepeampere: /* collecting data from spring games */

At least a million widgets and gadgets have been done in Spring. But alot of cool things are lost because the game vanished or the idea never made it into a public release. Many items from [[Monthly_Topic_Rotation]] are actually done or could be done.

It also annoyed me that there are often forum threads where somebody explains in detail how to do something but its just lost in spam.
So here is a collection of random things.

Some of the stuff might be outdated or rough "proves of concept":

===Linked Units: if parent units dies, child units die too===
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435
pseudo code + working gadget

===Widget+Gadget - CEG Spawner===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24499
working widget+gadget with chili ui

===picture in picture screen===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24485
working widget

===Tower Defense===
http://springrts.com/phpbb/viewtopic.php?f=14&t=22816
ideas how it could be done

http://springrts.com/phpbb/viewtopic.php?f=55&t=28696
TTD = Transportable Tower Defence mission - working example

===cover system / units taking cover behind features etc===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24820
ideas, code to check if unit is in cover.
is now in spring tanks and evoRTS

===collecting data from spring games===
====Unit path tracer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=23584
====build order visualizer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=26360
====unit movement, destruction, building placement====
http://springrts.com/phpbb/viewtopic.php?f=1&t=22571
====unit effectiveness by reading XP on destruction====
http://springrts.com/phpbb/viewtopic.php?f=44&t=26092
====unit movement, automatic visual replay in SVG ====
http://springrts.com/phpbb/viewtopic.php?f=55&t=28808
notAtv

===Ingame hitbox editor===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24882
dynamic hitboxes, reading button presses from keyboard

===Teleport areas (for units entering them), wrap around map===
http://springrts.com/phpbb/viewtopic.php?f=43&t=24611
working map with gadget

===Posing units ingame by moving/rotating pieces to create keyframes or w/e===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25104
hackish but working widget,gadget,unitscript brew

===non clumping aircraft===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24811
tags that make aircraft not clump

===Multiple parts units, targeting parts of units (ie head or turret)===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24590
discussion

===different resource names (ie "wood" instead of "metal")===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24771&p=462461&hilit=wood+metal#p462461
an ugly widget

===Units that die after a specified life time===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25461
different ways to do it, working example

===3D drawing library, weapon ranges in 3D, animated water===
http://springrts.com/phpbb/viewtopic.php?f=23&t=17935
zip file with various stuff

===finite/limited metal===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26026

===maps with lava===
http://springrts.com/phpbb/viewtopic.php?f=13&t=25517
nicer lava with shaders:
http://springrts.com/phpbb/viewtopic.php?f=13&t=26698 ,
http://springrts.com/phpbb/viewtopic.php?f=23&t=31159

===multi touch interaction===
http://springrts.com/phpbb/viewtopic.php?f=12&t=25865

===game mode: score points by dealing damage to a neutral unit===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26241

===neat animations===
http://springrts.com/phpbb/viewtopic.php?f=9&t=8864&start=7962

===tech tree===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20680

===seperate players by a wall & timer===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
map with working gadget

===colored text===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26341
some info about colors

===How to make a ballistic weapon arc just a little===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26660
different ways to do it

===melee combat===
http://springrts.com/phpbb/viewtopic.php?f=14&t=14373
ideas, some pictures, script pieces

===peace time to seperate teams before they can attack each other===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
a map that does that

===CEGs and unitDefs===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26612
some other way to do it

===noobs coming to mod spring===
collection of "hi iam new" threads
http://springrts.com/phpbb/viewtopic.php?f=14&t=26642
http://springrts.com/phpbb/viewtopic.php?f=14&t=26604
http://springrts.com/phpbb/viewtopic.php?f=14&t=26519
http://springrts.com/phpbb/viewtopic.php?f=14&t=26216
http://springrts.com/phpbb/viewtopic.php?f=1&t=27739

===creating new units in unitdefs_post.lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26078

===Turret rotating independant from unit chassis===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26727&p=499627
example script pieces

===units avoiding enemy units===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26811
widget based on a paper

===nicer map edges===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26732
discussion, "endless texture"-widget on page 2<br>
several versions from different people now in various games

===Spring with 3D glasses===
http://springrts.com/phpbb/viewtopic.php?f=1&t=19995
widget

===AI Ladder "SpringGrid"===
http://springrts.com/phpbb/viewtopic.php?f=15&t=20830
now dead project, source files available

===Moving Metal Extractors (Mobile Mex)===
http://springrts.com/phpbb/viewtopic.php?f=23&t=11335 http://springrts.com/phpbb/viewtopic.php?f=14&t=26877
working scripts

===fun with factories===
====mobile factory====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27503
script
====Multiple build pads possible?====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27615
====building multiple units at once====
http://springrts.com/phpbb/viewtopic.php?f=14&t=28092

===web lobby in browser===
http://springrts.com/phpbb/viewtopic.php?f=64&t=26414

===chat about engine trees===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27189

===BA with "Red Alert" eco===
http://springrts.com/phpbb/viewtopic.php?f=44&t=27173
working game with ore based economy

===can I force a unit to shoot allies?===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27114
ideas, talk

===forest fires with Lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27015
experiments

=== sharing variables across widgets (and making sure they all get them) ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27408

=== pixel shaders with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20932 simple shader example

http://springrts.com/phpbb/viewtopic.php?f=23&t=27269 even more primitive

=== railroad / train units ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=17137
very old but cool techdemo (probally needs fixing for current spring)

=== benchmarking spring ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27411 something about some tool and similiar threads (Phoronix Test Suite)

=== Lua Lobby ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27329 blabla about how to (not) implent it

http://springrts.com/phpbb/viewtopic.php?f=12&t=27526
Lua Sockets implented in engine

=== "Mini Games" with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=19300
http://springrts.com/phpbb/viewtopic.php?f=23&t=19030
Tetris, Pacman, Snake, Pong

=== Camera at fixed height ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20818
widget code

=== Lua IDE ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27608
my text editor is better than yours

=== common Lua mistakes ===
a widget ''so bad'' we can all learn from it \o/
http://springrts.com/phpbb/viewtopic.php?f=23&t=28113

=== (mapping) Good way to generate detail texture distribution ===
http://springrts.com/phpbb/viewtopic.php?f=13&t=28026

=== visible LOS / fog of war ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=28062
lua, engine

=== third person controlling a unit ===
http://springrts.com/phpbb/viewtopic.php?f=54&t=27013&start=10
gadget, mutator

=== Lua weapondefs with inheritance ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=28123

=== Multiple unit/feature/weapon defs per file ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26888

=== texture size and atlases ===
http://springrts.com/phpbb/viewtopic.php?f=9&t=29938&p=538020

=== scale a unit bigger in gadget:DrawWorld ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=29934

=== projectiles, SetProjectileTarget ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=31799
example gadget

[[Category:Game Dev]]

CollectionOfStuff

2014-05-17T17:55:42Z

Pepeampere: /* Tower Defense */

At least a million widgets and gadgets have been done in Spring. But alot of cool things are lost because the game vanished or the idea never made it into a public release. Many items from [[Monthly_Topic_Rotation]] are actually done or could be done.

It also annoyed me that there are often forum threads where somebody explains in detail how to do something but its just lost in spam.
So here is a collection of random things.

Some of the stuff might be outdated or rough "proves of concept":

===Linked Units: if parent units dies, child units die too===
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435
pseudo code + working gadget

===Widget+Gadget - CEG Spawner===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24499
working widget+gadget with chili ui

===picture in picture screen===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24485
working widget

===Tower Defense===
http://springrts.com/phpbb/viewtopic.php?f=14&t=22816
ideas how it could be done

http://springrts.com/phpbb/viewtopic.php?f=55&t=28696
TTD = Transportable Tower Defence mission - working example

===cover system / units taking cover behind features etc===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24820
ideas, code to check if unit is in cover.
is now in spring tanks and evoRTS

===collecting data from spring games===
====Unit path tracer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=23584
====build order visualizer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=26360
====unit movement, destruction, building placement====
http://springrts.com/phpbb/viewtopic.php?f=1&t=22571
====unit effectiveness by reading XP on destruction====
http://springrts.com/phpbb/viewtopic.php?f=44&t=26092

===Ingame hitbox editor===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24882
dynamic hitboxes, reading button presses from keyboard

===Teleport areas (for units entering them), wrap around map===
http://springrts.com/phpbb/viewtopic.php?f=43&t=24611
working map with gadget

===Posing units ingame by moving/rotating pieces to create keyframes or w/e===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25104
hackish but working widget,gadget,unitscript brew

===non clumping aircraft===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24811
tags that make aircraft not clump

===Multiple parts units, targeting parts of units (ie head or turret)===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24590
discussion

===different resource names (ie "wood" instead of "metal")===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24771&p=462461&hilit=wood+metal#p462461
an ugly widget

===Units that die after a specified life time===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25461
different ways to do it, working example

===3D drawing library, weapon ranges in 3D, animated water===
http://springrts.com/phpbb/viewtopic.php?f=23&t=17935
zip file with various stuff

===finite/limited metal===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26026

===maps with lava===
http://springrts.com/phpbb/viewtopic.php?f=13&t=25517
nicer lava with shaders:
http://springrts.com/phpbb/viewtopic.php?f=13&t=26698 ,
http://springrts.com/phpbb/viewtopic.php?f=23&t=31159

===multi touch interaction===
http://springrts.com/phpbb/viewtopic.php?f=12&t=25865

===game mode: score points by dealing damage to a neutral unit===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26241

===neat animations===
http://springrts.com/phpbb/viewtopic.php?f=9&t=8864&start=7962

===tech tree===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20680

===seperate players by a wall & timer===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
map with working gadget

===colored text===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26341
some info about colors

===How to make a ballistic weapon arc just a little===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26660
different ways to do it

===melee combat===
http://springrts.com/phpbb/viewtopic.php?f=14&t=14373
ideas, some pictures, script pieces

===peace time to seperate teams before they can attack each other===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
a map that does that

===CEGs and unitDefs===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26612
some other way to do it

===noobs coming to mod spring===
collection of "hi iam new" threads
http://springrts.com/phpbb/viewtopic.php?f=14&t=26642
http://springrts.com/phpbb/viewtopic.php?f=14&t=26604
http://springrts.com/phpbb/viewtopic.php?f=14&t=26519
http://springrts.com/phpbb/viewtopic.php?f=14&t=26216
http://springrts.com/phpbb/viewtopic.php?f=1&t=27739

===creating new units in unitdefs_post.lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26078

===Turret rotating independant from unit chassis===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26727&p=499627
example script pieces

===units avoiding enemy units===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26811
widget based on a paper

===nicer map edges===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26732
discussion, "endless texture"-widget on page 2<br>
several versions from different people now in various games

===Spring with 3D glasses===
http://springrts.com/phpbb/viewtopic.php?f=1&t=19995
widget

===AI Ladder "SpringGrid"===
http://springrts.com/phpbb/viewtopic.php?f=15&t=20830
now dead project, source files available

===Moving Metal Extractors (Mobile Mex)===
http://springrts.com/phpbb/viewtopic.php?f=23&t=11335 http://springrts.com/phpbb/viewtopic.php?f=14&t=26877
working scripts

===fun with factories===
====mobile factory====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27503
script
====Multiple build pads possible?====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27615
====building multiple units at once====
http://springrts.com/phpbb/viewtopic.php?f=14&t=28092

===web lobby in browser===
http://springrts.com/phpbb/viewtopic.php?f=64&t=26414

===chat about engine trees===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27189

===BA with "Red Alert" eco===
http://springrts.com/phpbb/viewtopic.php?f=44&t=27173
working game with ore based economy

===can I force a unit to shoot allies?===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27114
ideas, talk

===forest fires with Lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27015
experiments

=== sharing variables across widgets (and making sure they all get them) ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27408

=== pixel shaders with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20932 simple shader example

http://springrts.com/phpbb/viewtopic.php?f=23&t=27269 even more primitive

=== railroad / train units ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=17137
very old but cool techdemo (probally needs fixing for current spring)

=== benchmarking spring ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27411 something about some tool and similiar threads (Phoronix Test Suite)

=== Lua Lobby ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27329 blabla about how to (not) implent it

http://springrts.com/phpbb/viewtopic.php?f=12&t=27526
Lua Sockets implented in engine

=== "Mini Games" with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=19300
http://springrts.com/phpbb/viewtopic.php?f=23&t=19030
Tetris, Pacman, Snake, Pong

=== Camera at fixed height ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20818
widget code

=== Lua IDE ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27608
my text editor is better than yours

=== common Lua mistakes ===
a widget ''so bad'' we can all learn from it \o/
http://springrts.com/phpbb/viewtopic.php?f=23&t=28113

=== (mapping) Good way to generate detail texture distribution ===
http://springrts.com/phpbb/viewtopic.php?f=13&t=28026

=== visible LOS / fog of war ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=28062
lua, engine

=== third person controlling a unit ===
http://springrts.com/phpbb/viewtopic.php?f=54&t=27013&start=10
gadget, mutator

=== Lua weapondefs with inheritance ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=28123

=== Multiple unit/feature/weapon defs per file ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26888

=== texture size and atlases ===
http://springrts.com/phpbb/viewtopic.php?f=9&t=29938&p=538020

=== scale a unit bigger in gadget:DrawWorld ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=29934

=== projectiles, SetProjectileTarget ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=31799
example gadget

[[Category:Game Dev]]

CollectionOfStuff

2014-05-17T17:55:30Z

Pepeampere: /* Tower Defense */

At least a million widgets and gadgets have been done in Spring. But alot of cool things are lost because the game vanished or the idea never made it into a public release. Many items from [[Monthly_Topic_Rotation]] are actually done or could be done.

It also annoyed me that there are often forum threads where somebody explains in detail how to do something but its just lost in spam.
So here is a collection of random things.

Some of the stuff might be outdated or rough "proves of concept":

===Linked Units: if parent units dies, child units die too===
http://springrts.com/phpbb/viewtopic.php?f=23&t=25435
pseudo code + working gadget

===Widget+Gadget - CEG Spawner===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24499
working widget+gadget with chili ui

===picture in picture screen===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24485
working widget

===Tower Defense===
http://springrts.com/phpbb/viewtopic.php?f=14&t=22816
ideas how it could be done
http://springrts.com/phpbb/viewtopic.php?f=55&t=28696
TTD = Transportable Tower Defence mission - working example

===cover system / units taking cover behind features etc===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24820
ideas, code to check if unit is in cover.
is now in spring tanks and evoRTS

===collecting data from spring games===
====Unit path tracer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=23584
====build order visualizer====
http://springrts.com/phpbb/viewtopic.php?f=23&t=26360
====unit movement, destruction, building placement====
http://springrts.com/phpbb/viewtopic.php?f=1&t=22571
====unit effectiveness by reading XP on destruction====
http://springrts.com/phpbb/viewtopic.php?f=44&t=26092

===Ingame hitbox editor===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24882
dynamic hitboxes, reading button presses from keyboard

===Teleport areas (for units entering them), wrap around map===
http://springrts.com/phpbb/viewtopic.php?f=43&t=24611
working map with gadget

===Posing units ingame by moving/rotating pieces to create keyframes or w/e===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25104
hackish but working widget,gadget,unitscript brew

===non clumping aircraft===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24811
tags that make aircraft not clump

===Multiple parts units, targeting parts of units (ie head or turret)===
http://springrts.com/phpbb/viewtopic.php?f=14&t=24590
discussion

===different resource names (ie "wood" instead of "metal")===
http://springrts.com/phpbb/viewtopic.php?f=23&t=24771&p=462461&hilit=wood+metal#p462461
an ugly widget

===Units that die after a specified life time===
http://springrts.com/phpbb/viewtopic.php?f=14&t=25461
different ways to do it, working example

===3D drawing library, weapon ranges in 3D, animated water===
http://springrts.com/phpbb/viewtopic.php?f=23&t=17935
zip file with various stuff

===finite/limited metal===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26026

===maps with lava===
http://springrts.com/phpbb/viewtopic.php?f=13&t=25517
nicer lava with shaders:
http://springrts.com/phpbb/viewtopic.php?f=13&t=26698 ,
http://springrts.com/phpbb/viewtopic.php?f=23&t=31159

===multi touch interaction===
http://springrts.com/phpbb/viewtopic.php?f=12&t=25865

===game mode: score points by dealing damage to a neutral unit===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26241

===neat animations===
http://springrts.com/phpbb/viewtopic.php?f=9&t=8864&start=7962

===tech tree===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20680

===seperate players by a wall & timer===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
map with working gadget

===colored text===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26341
some info about colors

===How to make a ballistic weapon arc just a little===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26660
different ways to do it

===melee combat===
http://springrts.com/phpbb/viewtopic.php?f=14&t=14373
ideas, some pictures, script pieces

===peace time to seperate teams before they can attack each other===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26570
a map that does that

===CEGs and unitDefs===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26612
some other way to do it

===noobs coming to mod spring===
collection of "hi iam new" threads
http://springrts.com/phpbb/viewtopic.php?f=14&t=26642
http://springrts.com/phpbb/viewtopic.php?f=14&t=26604
http://springrts.com/phpbb/viewtopic.php?f=14&t=26519
http://springrts.com/phpbb/viewtopic.php?f=14&t=26216
http://springrts.com/phpbb/viewtopic.php?f=1&t=27739

===creating new units in unitdefs_post.lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26078

===Turret rotating independant from unit chassis===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26727&p=499627
example script pieces

===units avoiding enemy units===
http://springrts.com/phpbb/viewtopic.php?f=23&t=26811
widget based on a paper

===nicer map edges===
http://springrts.com/phpbb/viewtopic.php?f=13&t=26732
discussion, "endless texture"-widget on page 2<br>
several versions from different people now in various games

===Spring with 3D glasses===
http://springrts.com/phpbb/viewtopic.php?f=1&t=19995
widget

===AI Ladder "SpringGrid"===
http://springrts.com/phpbb/viewtopic.php?f=15&t=20830
now dead project, source files available

===Moving Metal Extractors (Mobile Mex)===
http://springrts.com/phpbb/viewtopic.php?f=23&t=11335 http://springrts.com/phpbb/viewtopic.php?f=14&t=26877
working scripts

===fun with factories===
====mobile factory====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27503
script
====Multiple build pads possible?====
http://springrts.com/phpbb/viewtopic.php?f=14&t=27615
====building multiple units at once====
http://springrts.com/phpbb/viewtopic.php?f=14&t=28092

===web lobby in browser===
http://springrts.com/phpbb/viewtopic.php?f=64&t=26414

===chat about engine trees===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27189

===BA with "Red Alert" eco===
http://springrts.com/phpbb/viewtopic.php?f=44&t=27173
working game with ore based economy

===can I force a unit to shoot allies?===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27114
ideas, talk

===forest fires with Lua===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27015
experiments

=== sharing variables across widgets (and making sure they all get them) ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27408

=== pixel shaders with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20932 simple shader example

http://springrts.com/phpbb/viewtopic.php?f=23&t=27269 even more primitive

=== railroad / train units ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=17137
very old but cool techdemo (probally needs fixing for current spring)

=== benchmarking spring ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27411 something about some tool and similiar threads (Phoronix Test Suite)

=== Lua Lobby ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=27329 blabla about how to (not) implent it

http://springrts.com/phpbb/viewtopic.php?f=12&t=27526
Lua Sockets implented in engine

=== "Mini Games" with Lua ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=19300
http://springrts.com/phpbb/viewtopic.php?f=23&t=19030
Tetris, Pacman, Snake, Pong

=== Camera at fixed height ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=20818
widget code

=== Lua IDE ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=27608
my text editor is better than yours

=== common Lua mistakes ===
a widget ''so bad'' we can all learn from it \o/
http://springrts.com/phpbb/viewtopic.php?f=23&t=28113

=== (mapping) Good way to generate detail texture distribution ===
http://springrts.com/phpbb/viewtopic.php?f=13&t=28026

=== visible LOS / fog of war ===
http://springrts.com/phpbb/viewtopic.php?f=12&t=28062
lua, engine

=== third person controlling a unit ===
http://springrts.com/phpbb/viewtopic.php?f=54&t=27013&start=10
gadget, mutator

=== Lua weapondefs with inheritance ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=28123

=== Multiple unit/feature/weapon defs per file ===
http://springrts.com/phpbb/viewtopic.php?f=14&t=26888

=== texture size and atlases ===
http://springrts.com/phpbb/viewtopic.php?f=9&t=29938&p=538020

=== scale a unit bigger in gadget:DrawWorld ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=29934

=== projectiles, SetProjectileTarget ===
http://springrts.com/phpbb/viewtopic.php?f=23&t=31799
example gadget

[[Category:Game Dev]]

File:Start3.jpg

2014-01-20T05:38:43Z

Pepeampere: Pepeampere uploaded a new version of "File:Start3.jpg"

game screen OTE

Games

2014-01-19T03:22:18Z

Pepeampere: /* Open Source */

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| align="center" width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| align="center" width="300px" | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| align="center" | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| align="center" | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| align="center" valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| align="center" | <h2>'''[http://notadota.com/ On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| align="center" | <h2>[[Spring Tanks]]</h2>([http://pastebin.com/Wpub9wWw undecided, some obscure free license])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://notadota.com}}
|
| align="center" | {{navimg|xsize=300|ysize=221|image=Springtanks_wikipreview.jpg|link=Spring Tanks}}
|-
| align="justify" valign="top" | First Spring MOBA with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | Some guys decided to attack each other with tanks and you can be one of them.
Build-in Single Player!
|
|-
| align="center" | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games (P.U.R.E.) include large GPL-friendly content collections.''

{|
|-
| align="center" width="300px" | <h2>[http://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter]</h2>
| width=40 |
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=http://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| align="center" width="300px" | <h2>[http://balancedannihilation.org Balanced Annihilation]</h2>
| width=40 |
| align="center" width="300px" | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://balancedannihilation.org}}
|
| align="center" |{{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|}

{|
|-
| align="center" width="300px" | <h2>[http://springfiles.com/spring/games/nota-37 NOTA]</h2>
| width=40 |
| align="center" width="300px" | <h2>[[XTA]]</h2>
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://springfiles.com/spring/games/nota-37}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| align="justify" valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
|
| align="justify" valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Games

2014-01-19T03:21:43Z

Pepeampere: OTE game added

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| align="center" width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| align="center" width="300px" | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| align="center" | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| align="center" | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| align="center" valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| align="center" | <h2>'''[http://notadota.com/ On The Edge]'''</h2> (GPL, [http://creativecommons.org/licenses/by-nc-sa/3.0/us/ CC-BY-NC-SA])
|
| align="center" | <h2>[[Spring Tanks]]</h2>([http://pastebin.com/Wpub9wWw undecided, some obscure free license])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=start3.jpg||link=http://notadota.com}}
|
| align="center" | {{navimg|xsize=300|ysize=221|image=Springtanks_wikipreview.jpg|link=Spring Tanks}}
|-
| align="justify" valign="top" | First Spring MOBA and with unique pre-game hero setup. Under heavy development. How to setup working the game read on [http://springrts.com/phpbb/viewtopic.php?f=55&t=31476 On The Edge forum thread]
|
| align="justify" valign="top" | Some guys decided to attack each other with tanks and you can be one of them.
Build-in Single Player!
|
|-
| align="center" | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|-
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games (P.U.R.E.) include large GPL-friendly content collections.''

{|
|-
| align="center" width="300px" | <h2>[http://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter]</h2>
| width=40 |
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=http://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| align="center" width="300px" | <h2>[http://balancedannihilation.org Balanced Annihilation]</h2>
| width=40 |
| align="center" width="300px" | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://balancedannihilation.org}}
|
| align="center" |{{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|}

{|
|-
| align="center" width="300px" | <h2>[http://springfiles.com/spring/games/nota-37 NOTA]</h2>
| width=40 |
| align="center" width="300px" | <h2>[[XTA]]</h2>
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://springfiles.com/spring/games/nota-37}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| align="justify" valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
|
| align="justify" valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

File:Start3.jpg

2014-01-19T02:55:09Z

Pepeampere: game screen OTE

game screen OTE

Gamedev:WeaponDefs

2013-12-12T23:00:00Z

Pepeampere: /* shield */ REPULSeR!!!! net repulsOr

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

==Location==
WeaponDef files are .lua files stored in the <code>Weapons/</code> directory of a Spring Game. Alternatively they can be integrated into [[Gamedev:UnitDefs|UnitDefs]].

==Purpose==
WeaponDef files have one purpose; to define the properties of weapons. They are the main description file for what attributes your weapon 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/Weapons/WeaponDef.cpp}}

==Data Types==
Tags may be one of the following data types:
* <code>int</code> - An integer number
* <code>float</code> - A number with decimals.
* <code>bool</code> - A value which can be <code>true</code> or <code>false</code>.
* <code>string</code> - Text, or more precisely a string of alphanumeric characters.
* <code>float[3]</code> - A vector, with three <code>float</code> components, representing x, y and z axes (y is 'up').

==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 WeaponDef table the internal <code>weaponName</code> desired for the weapon.

===Common===
The following tags are common to all or at least a majority of '''WeaponTypes''', depending on the tag.

====General====
{{tag
|name = weaponType
|type = string
|default = "Cannon"
|description = Spring has 14 '''WeaponTypes''' which provide game developers with basic behaviours which they can customise to an extent with the '''WeaponDef''' tags. Some tags are specific to certain '''WeaponTypes''' and not implemented for others, [https://docs.google.com/spreadsheet/ccc?key=0Am5BbZxm93S9dEZXc1Q4dXR4TFRYTFM4NlR4OFJFdWc#gid=0 this two-way table] indicates which tags work for which types.}} The possible values are:
* [[#AircraftBomb|AircraftBomb]]
* [[#BeamLaser|BeamLaser]]
* [[#Cannon|Cannon]]
* [[#DGun|Dgun]]
* [[#EmgCannon|EmgCannon]]
* [[#Flame|Flame]]
* [[#LaserCannon|LaserCannon]]
* [[#LightningCannon|LightningCanon]]
* [[#Melee|Melee]]
* [[#MissileLauncher|MissileLauncher]]
* [[#Rifle|Rifle]]
* [[#Shield (WeaponType)|Shield]]
* [[#StarburstLauncher|StarburstLauncher]]
* [[#TorpedoLauncher|TorpedoLauncher]]

{{tag
|name = name
|type = string
|default = "Weapon"
|description = The descriptive name of the weapon as listed in FPS mode.}}

{{tag
|name = turret
|type = bool
|default = false
|description = Does the unit aim within an arc (up-to and including full 360Â° turret traverse) or always aim along the owner's heading?}}

{{tag
|name = noSelfDamage
|type = bool
|default = false
|description = Can the weapon's explosion damage the unit which fires it? Useful for preventing bombers with high-yield weapons destroying themselves.}}

{{tag
|name = impactOnly
|type = bool
|default = false
|description = Does the weapon only deal damage through direct hits and not 'splash' damage through {{taglink|areaOfEffect}}?}}

{{tag
|name = noExplode
|type = bool
|default = false
|description = Does the weapon explode on impact with a target or continue through? Note that these weapons will do damage every single frame they are inside the [[Gamedev:CollisionVolumes|collision volume]] of an object, underground or under water, massively multiplying their damage.}}

{{tag
|name = burnblow
|type = bool
|default = false
|description = Does the weapon explode when it reaches its maximum range or continue on its path? The name is an [[OTAism]].}}

{{tag
|name = range
|type = float
|default = 10.0
|description = The maximum range in [[elmo]]s that the weapon can fire at.}}

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile.}}

{{tag
|name = reloadTime
|type = float
|default = 1.0
|description = The time in seconds between shots fired.}}

{{tag
|name = metalPerShot
|type = float
|default = 0.0
|description = Metal used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = energyPerShot
|type = float
|default = 0.0
|description = Energy used per shot. If the specified amount is not available, the weapon cannot be fired. Can also be used to specify how much a {{taglink|stockpile}} weapon will cost to build.}}

{{tag
|name = myGravity
|type = float
|default = 0.0
|description = Overrides the map gravity for ballistic weapons. The default of <code>0.0</code> disables the tag in favour of map gravity.}}

{{tag
|name = fireStarter
|type = float
|default = 0.0
|description = The percentage chance (<code>0.0</code> to <code>100.0</code>) of the weapon setting fire to static map features on impact.}}

{{tag
|name = cameraShake
|type = float
|default = damage (0.0 for paralyzers)
|description = Passed to the [[LuaCallinReturn#Game_Events:|ShockFront() callin]] as the first argument. Intended as a means to make the camera shake if in range of detonation.}}

{{tag
|name = stockpile
|type = bool
|default = false
|description = Does each round of the weapon have to be built and stockpiled by the player? Will only correctly function for the first of each stockpiled weapons a unit has.}}

{{tag
|name = stockpileTime
|type = float
|default = reloadTime
|description = The time in seconds taken to stockpile one round of the weapon.}}

{{tag
|name = interceptedByShieldType
|type = int
|default = 0 (See description)
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of shields that can intercept this weapon. Each digit of binary that is set to one means that a shield with the corresponding digit in its {{taglink|interceptType}} will intercept this weapon. The defaults are as follows:
* <code>1</code> - [[#Cannon]] and [[#EmgCannon]]
* <code>2</code> - [[#LaserCannon]] and [[#BeamLaser]]
* <code>4</code> - [[#MissileLauncher]] and [[#StarburstLauncher]]
* <code>8</code> - [[#AircraftBomb]]
* <code>16</code> - [[#Flame]]
* <code>32</code> - [[#TorpedoLauncher]]
* <code>64</code> - [[#LightningCannon]]
* <code>128</code> - [[#Rifle]]
* <code>256</code> - [[#Melee]]
(See [[Shield Interception Tag Use]]).}}

====Collision & Avoidance====

{{tag
|name = avoidGround
|type = bool
|default = true
|description = Should the weapon avoid firing if terrain blocks the line of fire?}}

{{tag
|name = avoidFriendly
|type = bool
|default = true
|description = Should the weapon avoid firing if a friendly unit is in the line of fire?}}

{{tag
|name = avoidFeature
|type = bool
|default = true
|description = Should the weapon avoid firing if a static map feature is in the line of fire?}}

{{tag
|name = avoidNeutral
|type = bool
|default = false
|description = Should the weapon avoid firing if a neutral unit is in the line of fire?}}

{{tag
|name = collideEnemy
|type = bool
|default = true
|description = Does the weapon projectile collide with enemy units or pass through?}}

{{tag
|name = collideFriendly
|type = bool
|default = true
|description = Does the weapon projectile collide with friendly units or pass through?}}

{{tag
|name = collideFeature
|type = bool
|default = true
|description = Does the weapon projectile collide with static map features or pass through?}}

{{tag
|name = collideNeutral
|type = bool
|default = true
|description = Does the weapon projectile collide with neutral units or pass through?}}

{{tag
|name = collideGround
|type = bool
|default = true
|description = Does the weapon projectile collide with terrain or pass through?}}

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = The radius used in collision calculations. For non-instant-hit weapons which do not use a 3D {{taglink|model}}.}}

====Targeting & Accuracy====
{{tag
|name = commandFire
|type = bool
|default = false
|description = Determines if the weapon will automatically fire on enemy units in range or only when manually ordered to attack.}}

{{tag
|name = canAttackGround
|type = bool
|default = true
|description = Determines if the weapon can be force-fired on ground positions or only fire on targeted units.}}

{{tag
|name = waterWeapon
|type = bool
|default = false
|description = Determines if the weapon can pass through water and target underwater units.}}

{{tag
|name = fireSubmersed
|type = bool
|default = waterWeapon
|description = Determines if the weapon can fire whilst underwater.}}

{{tag
|name = targetBorder
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon aims for the centre or the edge of its target's [[Gamedev:CollisionVolumes|collision volume]]. Clamped between <code>-1.0</code> - target the far border, and <code>1.0</code> - target the near border.}}

{{tag
|name = cylinderTargeting
|type = float
|default = 0.0 (1.0 for [[#Melee]])
|description = Controls whether the weapon range is calculated in a sphere or a cylinder. The height of the cylinder is determined by the value of this tag multiplied by the {{taglink|range}}. Clamped between <code>0.0</code> and <code>128.0</code>.}}

{{tag
|name = tolerance
|type = float
|default = 3000.0
|description = The amount to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For {{taglink|turret|false}} or {{taglink|fixedlauncher|true}} weapons this determines in what arc the unit will fire.}}

{{tag
|name = targetMoveError
|type = float
|default = 0.0
|description = The degree to which a weapon's aiming will fail to keep up with its target's movement. If set very low or not set at all, a weapon will lead its target and almost always hit.}}

{{tag
|name = leadLimit
|type = float
|default = -1.0
|description = Limits the maximum distance a unit will lead a target. The default of <code>-1</code> allows an infinite distance.}}

{{tag
|name = leadBonus
|type = float
|default = 0.0
|description = Controls how experience boosts the weapon's target leading. Is multiplied with the unit's experience and added to the {{taglink|leadLimit}}.}}

{{tag
|name = predictBoost
|type = float
|default = 0.0 (0.5 for {{taglink|burnblow|true}} weapons)
|description = Controls how well the weapon predicts unit speeds. Works in a similar way to {{taglink|targetMoveError}} except that it is 1-dimensional. This tag spreads the shots in a line based on the direction of the target whereas {{taglink|targetMoveError}} spreads the shots all around based on the movement.}}

{{tag
|name = heightMod
|type = float
|default = 0.2 (0.8 for [[#Cannon]], 1.0 for [[#BeamLaser]] and [[#LightningCannon]])
|description = Changes the spherical weapon range into an ellipsoid. Values above <code>1.0</code> mean the weapon cannot target as high as it can far, values below <code>1.0</code> mean it can target higher than it can far. For example <code>0.5</code> would allow the weapon to target twice as high as far.}}

{{tag
|name = proximityPriority
|type = float
|default = 1.0
|description = Acts as a multiplier for the distance to the target in the priority calculation. Note that negative values make weapons prefer distant targets.}}

{{tag
|name = accuracy
|type = float
|default = 0.0
|description = How accurate the weapon is. Lower values are more accurate. Accuracy is relative to the distance to the target; for instance, if the target is very close, even a very high value will probably still hit. If a target is very far away, even a very low value will likely cause the weapon to miss.}}

{{tag
|name = movingAccuracy
|type = float
|default = accuracy
|description = A weapon's {{taglink|accuracy}} whilst the owning unit is moving.}}

{{tag
|name = sprayAngle
|type = float
|default = 0.0
|description = How wide the the angle of a burst from a [[#Bursts|burst weapon]] can be. Very similar to {{taglink|accuracy}}, except that this tag affects each projectile in a burst, whilst the former does not.}}

{{tag
|name = ownerExpAccWeight
|type = float
|default = 0.0 (See description)
|description = A multiplier to {{taglink|accuracy}} and {{taglink|sprayAngle}} that reduces inaccuracy as a units experience increases. Defaults are as follows:
* <code>0.9</code> - [[#Cannon]], [[#Rifle]]
* <code>0.7</code> - [[#LaserCannon]], [[#BeamLaser]], [[#StarburstLauncher]]
* <code>0.5</code> - [[#MissileLauncher]], [[#LightningCannon]], [[#EmgCannon]], [[#DGun]]
* <code>0.2</code> - [[#Flame]]
}}

{{tag
|name = targetable
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapon that can intercept this weapon. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptor}} tag will intercept this weapon. Instant-hitting weapons such as [[#BeamLaser]], [[#LightningCannon]] and [[#Rifle]] cannot be targeted.
}}

{{tag
|name = interceptor
|type = int
|default = 0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this weapon can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|targetable}} tag will be intercepted by this weapon.
}}

{{tag
|name = interceptSolo
|type = bool
|default = true
|special = {{new|92.0}}
|description = If <code>true</code> no other interceptors may target the same projectile.
}}

{{tag
|name = coverage
|type = float
|default = 0.0
|special = {{new|92.0}} Previously only for [[#StarburstLauncher]]
|description = The radius in [[elmo]]s within which an {{taglink|interceptor}} weapon will fire on {{taglink|targetable}} weapons.
}}

====Bouncing====

{{tag
|name = waterBounce
|type = bool
|default = false
|description = Does the weapon bounce on water impacts?}}

{{tag
|name = groundBounce
|type = bool
|default = false
|description = Does the weapon bounce on ground impacts?}}

{{tag
|name = bounceSlip
|type = float
|default = 1.0
|description = The decimal-percentage amount of horizontal velocity a projectile keeps when it bounces.}}

{{tag
|name = bounceRebound
|type = float
|default = 1.0
|description = The decimal-percentage amount of vertical velocity a projectile keeps when it bounces.}}

{{tag
|name = numBounce
|type = int
|default = -1
|description = The number of times the weapon will bounce on impact before exploding. The default value of <code>-1</code> allows infinite bounces (at least until velocity reaches 0).}}

====Area Of Effect, Impulse & Cratering====

{{tag
|name = areaOfEffect
|type = float
|default = 8.0 * 0.5
|description = The ''diameter'' in [[elmo]]s in which the weapons explosion will cause damage.}}

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering.}}

{{tag
|name = edgeEffectiveness
|type = float
|default = 0.0
|description = Determines what percent of a weapon's maximum damage value will be applied to units within the weapon's {{taglink|areaOfEffect}}. Falls off from the epicentre according to the formula <code>damageApplied = damage * [(areaOfEffect - distToUnit) / (areaOfEffect - (distToUnit * edgeEffectiveness))]</code>, a graph of the function for various values is available [[Media:EdgeEffectiveness.png|here]].}}

{{tag
|name = explosionSpeed
|type = float
|default = See description
|description = The speed at which the weapon's explosion propagates from the epicentre. The default is calculated by this complex formula: <code>defExpSpeed = {8.0 + [max(30.0, default_damage / 20.0) * 2.5]} / {9.0f + [sqrt(max(30.0, default_damage / 20.0f)) * 0.7]} * 0.5</code>.}}

{{tag
|name = impulseFactor
|type = float
|default = 1.0
|description = A multiplier to the impulse given to units within the explosion {{taglink|areaOfEffect}}, which is otherwise equal to the damage dealt after {{taglink|edgeEffectiveness}} is taken into account. For [[#Melee]] weapons this is instead multiplied by the owning unit's mass (See [[Gamedev:UnitDefs#Tag:mass|Gamedev:UnitDefs]]).}}

{{tag
|name = impulseBoost
|type = float
|default = 0.0
|description = A constant amount added to the weapon's impulse, regardless of distance from the epicentre or the damage potential of the explosion, prior to the application of {{taglink|impulseFactor}}}}

{{tag
|name = craterMult
|type = float
|default = impulseFactor
|description = A multiplier to depth of terrain crater the weapon's explosion will create, which is otherwise based on the damage potential.}}

{{tag
|name = craterBoost
|type = float
|default = 0.0
|description = A constant amount, added to the weapon's cratering depth before the application of {{taglink|craterMult}}.}}

====Bursts====

{{tag
|name = burst
|type = int
|default = 1
|description = How many shots to fire per burst.
}}

{{tag
|name = burstRate
|type = float
|default = 0.1
|description = The time in seconds between shots in a burst. Note that {{taglink|reloadTime}} starts to count down from the ''first'' round fired, not the last so if <code>reloadTime < burst * burstRate</code> the weapon will fire continuously.
}}

{{tag
|name = projectiles
|type = int
|default = 1
|description = How many projectiles released per shot (shotgun style). e.g. a weapon with {{taglink|burst|5}}, {{taglink|burstRate|0.5}} and {{taglink|projectiles|2}} will shoot 5 lots of 2 for 10 projectiles total, with gaps of 0.5 seconds, before waiting for {{taglink|reloadTime}}. Best used in conjunction with {{taglink|sprayAngle}} or changing the firing piece using [[Animation-LuaCallins#Weapons|ShotX]] as otherwise they'll all be clumped in one shot.
}}

====Paralyzing====
{{tag
|name = paralyzer
|type = bool
|default = false
|description = Is the weapon a paralyzer? If <code>true</code> the weapon only stuns enemy units and does not cause damage in the form of lost hit-points.
}}

{{tag
|name = paralyzeTime
|type = int
|default = 10
|description = Determines the maximum length of time in seconds that the target will be paralyzed. The timer is restarted every time the target is hit by the weapon. Cannot be less than <code>0</code>.
}}

====Dynamic Damage====
The following set of tags allow for a weapon's damage potential to vary with the distance to its target.

{{tag
|name = dynDamageExp
|type = float
|default = 0.0
|description = Exponent of the range-dependent damage formula, the default of <code>0.0</code> disables dynamic damage, <code>1.0</code> means linear scaling, <code>2.0</code> quadratic and so on.
}}

{{tag
|name = dynDamageMin
|type = float
|default = 0.0
|description = The minimum floor value that range-dependent damage can drop to.
}}

{{tag
|name = dynDamageRange
|type = float
|default = 0.0
|description = If set to non-zero values the weapon will use this value in the range-dependant damage formula instead of the actual {{taglink|range}}.
}}

{{tag
|name = dynDamageInverted
|type = bool
|default = false
|description = If <code>true</code> the damage curve is inverted i.e. the weapon does more damage at greater ranges as opposed to less.
}}

====Sounds====
{{tag
|name = soundTrigger
|type = bool
|default = false (true for [[#Melee]], [[#Rifle]] and non-beamBurst [[#BeamLaser]])
|description = Does the weapon play {{taglink|soundStart}} for every round in a burst or only once for each salvo?}}

{{tag
|name = soundStart
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon fires.}}

{{tag
|name = soundHitDry
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with solid ground. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

{{tag
|name = soundHitWet
|type = string
|default = ""
|description = The name of a '''SoundItem''' (See [[Sounds.lua]]) or filename of a sound to play when the weapon collides with water. Note that a [[#BeamLaser]] will play this sound every frame of its lifetime.}}

====Visuals====

{{tag
|name = cegTag
|type = string
|default = ""
|description = The name, without prefixes, of a [[CEG]] to be emitted by the projectile each frame.
}}

{{tag
|name = intensity
|type = float
|default = 0.9 (0.2 for [[#Cannon]])
|description = Alpha transparency for non-3D model projectiles. Lower values are more opaque, but <code>0.0</code> will cause the projectile to disappear entirely.
}}

{{tag
|name = model
|type = string
|default = ""
|description = The filename of a 3D model to use when rendering the projectile. Note that only the root piece of a projectile model is rendered. Currently only for [[#Cannon]], [[#LaserCannon]], [[#MissileLauncher]], [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = explosionScar
|type = bool
|default = false
|description = Does the weapon's explosion leave a scar decal on the ground? For all types except [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If <code>true</code> the weapon is always rendered regardless of whether or not it is in LOS range of a player's units.
}}

{{tag
|name = rgbColor
|type = float[3]
|default = {1.0, 0.0, 0.0} (See Description)
|description = The primary colour for sprite rendering weapons. Additional defaults are as follows:
* [[#Cannon]] - <code>{1.0, 0.5, 0.0}</code>
* [[#EmgCannon]] - <code>{0.9, 0.9, 0.2}</code>
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of a [[CEG]], with <code>custom:</code> prefix, to spawn as the weapon's explosion. Does not currently work for [[#Melee]] and [[#Rifle]].
}}

{{tag
|name = bounceExplosionGenerator
|type = string
|default = ""
|description = For weapons which can use {{taglink|groundBounce|true}}, the name of a [[CEG]], with <code>custom:</code> prefix, to spawn when weapon the bounces.
}}

{{tag
|name = texture1
|type = string
|default = ""
|description = The projectile texture for [[#AircraftBomb]], [[#Cannon]], [[#EmgCannon]], [[#Flame]]; beam texture for [[#LaserCannon]], [[#BeamLaser]], [[#LightningCannon]]; flare texture for [[#MissileLauncher]], [[#StarburstLauncher]] and dome texture for the [[#Shield]].
}}

{{tag
|name = texture2
|type = string
|default = ""
|description = The end-of-beam texture for [[#LaserCannon]], [[#BeamLaser]] and {{taglink|smoketrail}} texture for [[#MissileLauncher]], [[#StarburstLauncher]].
}}

{{tag
|name = texture3
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]], or muzzle texture if {{taglink|largeBeamLaser|true}}. Also used as the flame texture for [[#StarburstLauncher]].
}}

{{tag
|name = texture4
|type = string
|default = ""
|description = Flare texture for [[#BeamLaser]] with {{taglink|largeBeamLaser|true}}.
}}

===AircraftBomb===
Drops a ballistic projectile at the same movement vector as the unit itself. Intended only for aircraft. Visually drawn as a billboarded sprite as used by the [[#Cannon]], but more commonly used with a 3D model.

There are no tags specific to this '''WeaponType'''

====AircraftBomb Visuals====

When not using a {{taglink|model}}, the AircraftBomb is the same as [[#Cannon Visuals]].

===BeamLaser===
An instant-hit weapon which spawns a beam and does a portion of its total damage each frame. Cannot be [[Animation-LuaCallouts#Effects|script emitted]] if it has a {{taglink|beamTime}} longer than one frame. Visually drawn as a [http://en.wikipedia.org/wiki/Star_Trek Star Trek] Phaser-style laser weapon. The {{taglink|largeBeamLaser}} tag allows changing the visual effect of the laser, such as using a tileable, scrolling texture without changing the behaviour.

{{tag
|name = minIntensity
|type = float
|default = 0.0
|description = The minimum percentage the weapon's damage can fall-off to over its range. Setting to <code>1.0</code> will disable fall off entirely. Unrelated to the visual-only {{taglink|intensity}} tag.
}}

{{tag
|name = beamTime
|type = float
|default = 1.0
|description = How long in seconds to fire the laser before waiting for {{taglink|reloadTime}} to start. Damage is distributed over the duration of the {{taglink|beamTime}}, and the weapon will aim to hit the target when the beam is in the middle of its {{taglink|beamTime}} (i.e. using prediction).
}}

{{tag
|name = beamBurst
|type = bool
|default = false
|description = Makes the laser fire a burst of beams that are all aimed towards the target (instead of aimed with the piece). A [[#BeamLaser]] can do its full damage with every shot if {{taglink|beamBurst}} is enabled. Disables {{taglink|beamTime}} in favour of the [[#Bursts|burst tags]].
}}

{{tag
|name = sweepFire
|type = bool
|default = false
|description = Makes the laser continue firing while it aims for a new target, 'sweeping' across the terrain. Reimplemented in 95.0, still has no script interaction so use with care. Respects {{taglink|reloadTime}} constraint but not much else.
}}

====BeamLaser Visuals====

See also {{taglink|thickness}} and {{taglink|coreThickness}}.

{{tag
|name = beamTTL
|type = int
|default = 0
|description = The time in frames for which the laser beam remains visible.
}}

{{tag
|name = beamDecay
|type = float
|default = 1.0
|description = How fast the beam fades out. Each frame the {{taglink|intensity}} is multiplied by this value.
}}

{{tag
|name = laserFlareSize
|type = float
|default = 15.0
|description = Determines the size of the firing flare.
}}

{{tag
|name = largeBeamLaser
|type = bool
|default = false
|description = Changes the visual effect allowing tiling and scrolling of the texture and a pulsating firing flare.
}}

{{tag
|name = tileLength
|type = float
|default = 200.0
|description = Defines the length before the texture used is repeated (tiled). Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = scrollSpeed
|type = float
|default = 5.0
|description = Controls how fast the texture scrolls. Only if {{taglink|largeBeamLaser|true}}.
}}

{{tag
|name = pulseSpeed
|type = float
|default = 1.0
|description = Controls how fast the pulsating effect at the start of the beam is. Only if {{taglink|largeBeamLaser|true}}.
}}

===Cannon===
The default '''WeaponType'''. Fires a ballistic projectile, for the best result (without under/overshooting) the {{taglink|weaponVelocity}} should be set so as to give an elevation of 45Â° when firing at the maximum {{taglink|range}}. Substituting the angle into the [http://en.wikipedia.org/wiki/Trajectory#Range_and_height trajectory equation] and rearranging, we get:
<code><pre>weaponVelocity = âˆš(range * g)</pre></code>
where <code>g</code> is the map gravity, usually around <code>120</code> for most Spring maps (You can use the {{taglink|myGravity}} tag if you want to be exact). Visually drawn as a billboarded sprite or 3D model.

{{tag
|name = highTrajectory
|type = int
|default = 2
|description = Can this weapon be fired in a high trajectory (>45Â° angle). Can be <code>0</code> - low trajectory only, <code>1</code> - high trajectory only or <code>2</code> - enables a high/low toggle button on the unit.
}}

{{tag
|name = heightBoostFactor
|type = float
|default = -1.0
|description = Controls the boost given to {{taglink|range}} by high terrain. Values > <code>1.0</code> result in increased range, <code>0.0</code> means the cannon has fixed range regardless of height difference to target. Any value < <code>0.0</code> (i.e. the default value) result in an automatically calculated value based on {{taglink|range}} and theoretical maximum range.
}}

====Cannon Visuals====

{{tag
|name = size
|type = float
|default = 2.0 + min(default_damage * 0.0025, {{taglink|areaOfEffect}} * 0.1)
|description = The drawing radius of the billboarded sprite. Also for [[#AircraftBomb Visuals]], [[#EmgCannon Visuals]] (default: <code>3.0</code>) and [[#Flame Visuals]].
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = A set of RGB colours to transition between over the projectile's lifetime. Can be given as a string of RGB digits or an image filename (See [[CColorMap]]). Also for [[#Flame Visuals]].
}}

{{tag
|name = sizeDecay
|type = float
|default = 0.0
|description = How quickly each particle of the Cannon shot decays in size.
}}

{{tag
|name = alphaDecay
|type = float
|default = 1.0
|description = How quickly each particle of the Cannon shot fades out.
}}

{{tag
|name = separation
|type = float
|default = 0.0
|description = The distance between each particle of the Cannon shot.
}}

{{tag
|name = noGap
|type = bool
|default = true
|description = Switch between the distance between particles being proportional to the size of the two particles (<code>true</code>) or proportional to the size of the first particle (<code>false</code>).
}}

{{tag
|name = stages
|type = int
|default = 5
|description = The number of particles in each Cannon shot.
}}

===DGun===
Fires a line-of-sight or ballistic projectile (selected via the {{taglink|gravityAffected}} tag). Visually represented by a fireball effect that cannot be customised, however it can be replaced by a 3D model. The name and visual effect are [[OTAism]]s.

{{tag
|name = gravityAffected
|type = bool
|default = false
|description = Does the fireball projectile lose height due to map gravity?
}}

===EmgCannon===
A line-of-sight weapon. Visually drawn as a billboarded sprite very similar to that of the [[#Cannon]], however not as customisable, or a 3D model. The name is another [[OTAism]].

There are no tags specific to this '''WeaponType'''.

===Flame===
A line-of-sight weapon intended for use as a flamethrower or similar. Visually drawn as a stream of textured particles, the colour of which can be controlled very precisely using the {{taglink|colorMap}} tag (see [[CColorMap]]).

====Flame Visuals====
See also {{taglink|colorMap}}.

{{tag
|name = sizeGrowth
|type = float
|default = 0.5
|description = How much the draw radius of the flame projectile increases each frame.
}}

{{tag
|name = flameGFXTime
|type = float
|default = 1.2
|description = Makes the flamethrower projectile stay alive as a visual-only effect (i.e. does not deal any damage) after it has reached maximum {{taglink|range}}. It is a percentage multiplier, e.g. <code>1.2</code> makes the projectile stay alive until it reaches 20% beyond {{taglink|range}}.
}}

===LaserCannon===
A particularly versatile line-of-sight weapon. Visually drawn like a [http://en.wikipedia.org/wiki/Star_Wars Star Wars] Blaster-style laser weapon, or a 3D model.

====LaserCannon Visuals====

{{tag
|name = duration
|type = float
|default = 0.05
|description = Multiplied against {{taglink|weaponVelocity}} to determine the visual length of the beam projectile.
}}

{{tag
|name = hardStop
|type = bool
|default = false
|description = Does the laser projectile stop dead or fade out?
}}

{{tag
|name = fallOffRate
|type = float
|default = 0.5
|description = Rate at which the beam fades out after it goes past its maximum {{taglink|range}} if {{taglink|hardStop|false}}. A value of <code>0.0</code> is never fade out, <code>1.0</code> is finish fading out exactly at maximum {{taglink|range}}.
}}

{{tag
|name = lodDistance
|type = int
|default = 1000
|description = Minimum camera distance at which the default LaserCannon projectile is simplified to a single rectangle.
}}

{{tag
|name = thickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = coreThickness
|type = float
|default = 2.0
|description = The thickness (width) of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

{{tag
|name = rgbColor2
|type = float
|default = {1.0, 1.0, 1.0}
|description = The colour of the LaserCannon projectile's core. Also for [[#BeamLaser Visuals]].
}}

===LightningCannon===
An instant-hit weapon similar to the [[#BeamLaser]], but which does all its damage at once. Visually drawn like [http://en.wikipedia.org/wiki/Star_Wars Star Wars] 'Force Lightning' or [http://en.wikipedia.org/wiki/Command_%26_Conquer:_Red_Alert CnC: Red Alert] [http://en.wikipedia.org/wiki/Tesla_coil Tesla Coil] weapons, the effect is not very customisable.

There are no tags specific to this '''WeaponType'''.

===Melee===
A weapon that always damages the target, no ifs or buts; unsurprisingly intended for use as a close quarters [http://en.wikipedia.org/wiki/Melee#Use_in_gaming 'melee'] weapon. It does not fire a projectile and does not care about the line of fire.

There are no tags specific to this '''WeaponType'''.

===MissileLauncher===
A versatile weapon which can optionally track targets and accelerate from a low initial velocity. It can also use {{taglink|trajectoryHeight}} to have the shot arc similar to a ballistic projectile. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = startVelocity
|type = float
|default = 0.0
|description = The initial velocity of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].
}}

{{tag
|name = acceleration
|type = float
|default = 0.0
|description = The initial acceleration of the weapon projectile. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Note that if it is <code>0.0</code> the weapon can never increase from its {{taglink|startVelocity}} and will not reach its maximum {{taglink|weaponVelocity}}.
}}

{{tag
|name = tracks
|type = bool
|default = false
|description = Can the weapon projectile track a moving target? Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]].}}

{{tag
|name = turnRate
|type = float
|default = 0.0
|description = The rate (in [[Elmo#Angular|cau]]) at which {{taglink|tracks|true}} weapons turn towards their target. This is relative to a projectile's current velocity; a weapon with a higher velocity will need a higher value in order to be able to hit targets that turn suddenly.}}

{{tag
|name = flightTime
|type = float
|default = 0.0
|description = The time in seconds before a missile projectile's fuel runs out; it ceases to obey {{taglink|tracks}}, loses velocity and falls to the ground. Also for [[#StarburstLauncher]]. Large values may cause over/undershoot problems.
}}

{{tag
|name = fixedLauncher
|type = bool
|default = false
|description = Makes the projectile spawn with the orientation of the shooting piece instead of their normal orientation. Also for [[#StarburstLauncher]] and [[#TorpedoLauncher]]. Weapons may not correctly obey [[#Collision & Avoidance|avoidance settings]] when using this tag.
}}

{{tag
|name = wobble
|type = float
|default = 0.0
|description = Adds a random vector to the direction of travel every 16 frames, multiplied by the value of the tag. The effect is reduced as the firing unit gains experience. As this missiles direction is changed, wobbling swarm of missiles will diverge.
}}

{{tag
|name = dance
|type = float
|default = 0.0
|description = Adds a random vector to the position of a missile projectile every 8 frames, multiplied by the value of the tag. As the projectile is not rotated, a dancing swarm of missiles will remain relatively coherent.
}}

{{tag
|name = trajectoryHeight
|type = float
|default = 0.0
|description = Determines the height of the arc the missile will reach as it moves towards its target. A value of <code>0.0</code> will result in a flat trajectory, <code>1.0</code> will launch at 45°. Can be any value >= <code>0.0</code>; extreme values may require the {{taglink|tracks}} tag to be able to hit a target.
}}

====MissileLauncher Visuals====
A note about the missile exhaust flare: the size of the flare is determined by the model radius. The emit position of the flare is at (0,0,-radius) so the model may need careful adjustment to get the flare looking right.

{{tag
|name = smokeTrail
|type = bool
|default = false
|description = Does the missile projectile emit a smoke trail as it travels? Also for [[#StarburstLauncher]].
}}

===Rifle===
An instant hit weapon which does all its damage at once. Visually represented by a hardcoded tracer, firing and hitting effects. Rarely used.

There are no tags specific to this '''WeaponType'''.

===Shield (WeaponType)===
As the name suggests, not a weapon but a defensive shield. Can absorb or deflect ({{taglink|repulsor|true}}) projectiles. Individual weapons can be set to be intercepted or not by the shield using a [http://en.wikipedia.org/wiki/Mask_(computing) bitmask] (see [[Shield Interception Tag Use]]). Visually represented as a translucent sphere, with control over colour and texture; by default the shield is invisible ({{taglink|visible|false}}).

See the [[#shield]] sub-table section for other tags specific to this type.

===StarburstLauncher===
Fires a projectile that rises vertically for {{taglink|weaponTimer}} seconds, then turns towards its target. It can optionally track targets and accelerate from a low initial velocity. This is the only weapon that can be {{taglink|targetable}} and act as an {{taglink|interceptor}}. Visually represented by a 3D model, with an optional {{taglink|smokeTrail}}.

{{tag
|name = weaponTimer
|type = float
|default = 0.0
|description = The time in seconds during which the missile ascends vertically before turning towards its target.
}}

===TorpedoLauncher===
Fires a projectile that will behave ballistically out of water and like a missile in water. Usually used with {{taglink|waterWeapon|true}} so they can fire underwater and target underwater units. An aircraft carrying a [[#TorpedoLauncher]] is a special case, the weapon turns into an [[#AircraftBomb]] projectile that will spawn a torpedo projectile on impact with water. Visually represented by a pointed black cuboid, usually the default object is replaced by a 3D model.

{{tag
|name = subMissile
|type = bool
|default = false
|description = Can the torpedo leave the water and target units and positions on land?
}}

===NoWeapon===
Not actually a '''WeaponType''', but an individual weapon requested by Spring to 'fill in the gaps' if a unit claims to have a weapon which isn't actually defined. There needs to be only one of these weapons and it is created by setting {{taglink|weaponName|"NOWEAPON"}} rather than by the {{taglink|weaponType}} tag.

==Sub Tables==

===damage===
The damage subtable lists how many hit points the weapon depletes against each armor class (See [[Armordefs.lua]]). It is a key-value map of armor class names and damage values. The special <code>default</code> entry is as the name suggests the default damage applied to any unit which does not belong to a listed armor class, or to shields.

For example a weapon which deals 100 damage by default but only 50 to units in the 'tank' armor class:

<code><pre>damage = {
default = 100,
tank = 50,
}</pre></code>

===shield===
The preferred way to create a shield or repulser is to use the shield subtable rather than the old shield tags.

The following tags are repulser specific:

{{tag
|name = repulser
|type = bool
|default = false
|description = Does the shield [http://dictionary.reference.com/browse/repulse?s=t repulse] (deflect) projectiles or absorb them? Btw its [http://springrts.com/mantis/view.php?id=4206 not repulsOr, but repulsEr]!}}

{{tag
|name = force
|type = float
|default = 0.0
|description = The force applied by the repulser to the weapon - higher values will deflect weapons away at higher velocities.}}

{{tag
|name = maxSpeed
|type = float
|default = 0.0
|description = The maximum speed the repulser will impart to deflected projectiles.}}

{{tag
|name = visibleRepulse
|type = bool
|default = false
|description = Is the (hard-coded) repulse effect rendered or not?}}

The following tags are general behaviour for all shields:

{{tag
|name = interceptType
|type = int
|default = 0
|description = [http://en.wikipedia.org/wiki/Mask_(computing) Bitmask] representing the types of weapons that this shield can intercept. Each digit of binary that is set to one means that a weapon with the corresponding digit in its {{taglink|interceptedByShieldType}} will be intercepted by this shield (See [[Shield Interception Tag Use]]).}}

{{tag
|name = smart
|type = bool
|default = false
|description = Determines whether or not projectiles fired by allied units can pass through the shield (<code>true</code>) or are intercepted as enemy weapons are (<code>false</code>).}}

{{tag
|name = exterior
|type = bool
|default = false
|description = Determines whether or not projectiles fired within the shield's radius can pass through the shield (<code>true</code>) or are intercepted (<code>false</code>).}}

{{tag
|name = energyUse
|type = float
|default = 0.0
|description = The amount of the energy resource consumed by the shield to absorb or repulse weapons, continually drained by a repulser as long as the projectile is in range.}}

{{tag
|name = radius
|type = float
|default = 0.0
|description = The radius of the circular area the shield covers.}}

{{tag
|name = power
|type = float
|default = 0.0
|description = Essentially the maximum allowed hit-points of the shield - reduced by the <code>damage</code> of a weapon upon impact.}}

{{tag
|name = startingPower
|type = float
|default = 0.0
|description = How many hit-points the shield starts with - otherwise the shield must regenerate from <code>0</code> until it reaches maximum {{taglink|power}}.}}

{{tag
|name = powerRegen
|type = float
|default = 0.0
|description = How many hit-points the shield regenerates each second.}}

{{tag
|name = powerRegenEnergy
|type = float
|default = 0.0
|description = How much energy resource is consumed to regenerate each hit-point.}}

{{tag
|name = rechargeDelay
|type = float
|default = 0.0
|description = The delay in seconds before a shield begins to regenerate after it is hit.}}

The following tags control the visual aspects of the shield:

{{tag
|name = visible
|type = bool
|default = false
|description = Is the shield visible or not?}}

{{tag
|name = visibleHitFrames
|type = int
|default = 0
|description = The number of frames a shield becomes visible for when hit.}}

{{tag
|name = badColor
|type = float[3]
|default = {1.0, 0.5, 0.5} (Red)
|description = The RGB colour the shield transitions to as its hit-points are reduced towards <code>0</code>.}}

{{tag
|name = goodColor
|type = float[3]
|default = {0.5, 0.5, 1.0} (Blue)
|description = The RGB colour the shield transitions to as its hit-points are regenerated towards its maximum {{taglink|power}}.}}

{{tag
|name = alpha
|type = float
|default = 0.2
|description = The alpha transparency of the shield whilst it is visible.}}

===customParams===
The <code>customParams</code> subtable of a WeaponDef allows the game designer to give their weapons 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==
[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/weapons 'Balanced Annihilation' WeaponDefs]

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Fweapons 'Conflict Terra' WeaponDefs] (Most are integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]])

[https://code.google.com/p/evolutionrts/source/browse/#svn%2Ftrunk%2Fevolutiondev.sdd%2FWeapons 'Evolution RTS' WeaponDefs] (Most are integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]])

[http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/weapons/ 'Spring: 1944' WeaponDefs] (Implements an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance])

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FWeapons 'Spring Tutorial Game' WeaponDefs]

[[Category: Game Dev]]

Games

2013-12-04T04:24:17Z

Pepeampere: /* TA-derived */ fix

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| align="center" width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| align="center" width="300px" | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| align="center" | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| align="center" | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| align="center" valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| align="center" | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|
| align="center" | <h2>[[Spring Tanks]]</h2>([http://pastebin.com/Wpub9wWw undecided, some obscure free license])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|
| align="center" | {{navimg|xsize=300|ysize=221|image=Springtanks_wikipreview.jpg|link=Spring Tanks}}
|-
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|
| align="justify" valign="top" | Some guys decided to attack each other with tanks and you can be one of them.
Build-in Single Player!
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games (P.U.R.E.) include large GPL-friendly content collections.''

{|
|-
| align="center" width="300px" | <h2>[http://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter]</h2>
| width=40 |
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=http://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| align="center" width="300px" | <h2>[http://balancedannihilation.org Balanced Annihilation]</h2>
| width=40 |
| align="center" width="300px" | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://balancedannihilation.org}}
|
| align="center" |{{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|}

{|
|-
| align="center" width="300px" | <h2>[http://springfiles.com/spring/games/nota-37 NOTA]</h2>
| width=40 |
| align="center" width="300px" | <h2>[[XTA]]</h2>
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://springfiles.com/spring/games/nota-37}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| align="justify" valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
|
| align="justify" valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Games

2013-12-04T04:19:46Z

Pepeampere: /* TA-derived */

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| align="center" width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| align="center" width="300px" | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| align="center" | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| align="center" | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| align="center" valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| align="center" | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|
| align="center" | <h2>[[Spring Tanks]]</h2>([http://pastebin.com/Wpub9wWw undecided, some obscure free license])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|
| align="center" | {{navimg|xsize=300|ysize=221|image=Springtanks_wikipreview.jpg|link=Spring Tanks}}
|-
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|
| align="justify" valign="top" | Some guys decided to attack each other with tanks and you can be one of them.
Build-in Single Player!
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games (P.U.R.E.) include large GPL-friendly content collections.''

{|
|-
| align="center" width="300px" | <h2>[http://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter]</h2>
| width=40 |
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=http://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| align="center" width="300px" | <h2>[http://balancedannihilation.org Balanced Annihilation]</h2>
| width=40 |
| align="center" width="300px" | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://balancedannihilation.org}}
|
| align="center" |{{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|}

{|
|-
| align="center" width="300px" | <h2>[http://springfiles.com/spring/games/nota-37 NOTA]</h2>
| width=40 |
| align="center" width="300px" | <h2>[[XTA]]</h2>
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|http://springfiles.com/spring/games/nota-37}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| align="justify" valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
|
| align="justify" valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Games

2013-12-04T04:19:09Z

Pepeampere: /* TA-derived */

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| align="center" width="300px" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| align="center" width="300px" | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| align="center" | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| align="center" | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| align="center" valign="top"| {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| align="center" | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|
| align="center" | <h2>[[Spring Tanks]]</h2>([http://pastebin.com/Wpub9wWw undecided, some obscure free license])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|
| align="center" | {{navimg|xsize=300|ysize=221|image=Springtanks_wikipreview.jpg|link=Spring Tanks}}
|-
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|
| align="justify" valign="top" | Some guys decided to attack each other with tanks and you can be one of them.
Build-in Single Player!
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games (P.U.R.E.) include large GPL-friendly content collections.''

{|
|-
| align="center" width="300px" | <h2>[http://springrts.com/phpbb/viewforum.php?f=46 Star Wars: Imperial Winter]</h2>
| width=40 |
| align="center" width="300px" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=http://springrts.com/phpbb/viewforum.php?f=46}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era.
|
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| align="center" width="300px" | <h2>[http://balancedannihilation.org Balanced Annihilation]</h2>
| width=40 |
| align="center" width="300px" | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://balancedannihilation.org}}
|
| align="center" |{{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|}

{|
|-
| align="center" width="300px" | <h2>[http://springfiles.com/spring/games/nota-37 NOTA]</h2>
| width=40 |
| align="center" width="300px" | <h2>[[XTA]]</h2>
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://springfiles.com/spring/games/nota-36}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| align="justify" valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
|
| align="justify" valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

LuaCallinReturn

2013-11-20T22:30:26Z

Pepeampere: /* Projectiles: */

[[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 <br>
{{sourcelink|file=cont/base/springcontent/LuaGadgets/gadgets.lua}} <br>
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''.<br>
For example ''AllowUnitTransfer()''<br>
<code>return true</code> = allow transfer <br>
<code>return false</code> = deny transfer

==Commands, general-purpose:==

<font color=#55ee99>Initialize()</font> --> none.<br>
called when widget/gadget gets (re-)loaded.

<font color=#55ee99>Shutdown()</font> --> none.

<font color=#55ee99>PlayerChanged</font> --> (playerID).
gadget/widget: Use this to check whether a player has become spectator for instance.

<font color=#55ee99>LayoutButtons()</font> --> unknown, please document.

<font color=#55ee99>ConfigureLayout()</font> --> "command".

<font color=#55ee99>CommandNotify()</font> --> "id, params, options", where id = the CommandID

<font color=#55ee99>KeyPress()</font> --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

<font color=#55ee99>KeyRelease()</font> --> "key"

<font color=#55ee99>MouseMove()</font> --> "x, y, dx, dy, button"

<font color=#55ee99>MousePress()</font> --> "x, y, button"<br/>
<font color=#dd9944>button parameter values: left - 1, middle - 2, right - 3</font>

<font color=#55ee99>MouseRelease()</font> --> "x, y, button"<br/>
<font color=#dd9944>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.</font>

<font color=#55ee99>MouseWheel()</font> --> "up, value"

<font color=#55ee99>IsAbove()</font> --> "x, y" where x,y = screen coordinates.

<font color=#55ee99>GetTooltip()</font> --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

<font color=#55ee99>AddConsoleLine()</font> --> "msg, priority"

<font color=#55ee99>MapDrawCmd()</font> --> "playerID, cmdType, px, py, pz, labeltext"

<font color=#55ee99>AllowCommand()</font> --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

<font color=#55ee99>CommandFallback()</font> --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

<font color=#55ee99>CommandsChanged()</font> --> unknown (none?)

<font color=#55ee99>AllowUnitCreation()</font> --> "unitDefID, builderID, builderTeam, x, y, z, facing"

<font color=#55ee99>AllowUnitTransfer()</font> --> "unitID, unitDefID, oldTeam, newTeam, capture"

<font color=#55ee99>AllowUnitBuildStep()</font> --> "builderID, builderTeam, unitID, unitDefID, part"

<font color=#55ee99>AllowFeatureCreation()</font> --> "featureDefID, teamID, x, y, z"

<font color=#55ee99>AllowFeatureBuildStep()</font> --> unknown, please document.

<font color=#55ee99>AllowResourceLevel()</font> --> "teamID, res, level"

<font color=#55ee99>AllowResourceTransfer()</font> --> "teamID, res, level"</font>

<font color=#55ee99>Update()</font> --> "dt"<br>
<font color=#dd9944>called every screenframe. dt is the time since the last screenframe</font>

<font color=#55ee99>DefaultCommand()</font> --> "type,id"<br>
<font color=#dd9944>can return an [[Lua_CMDs|CMD]] to change cursor and command. {{forumlink|topic=26438|title=example usage}}</font>

<font color=#55ee99>AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID) </font> -> allowFpsControl<br>
''return true'' allows fps mode, ''return false'' blocks it.

==Unit-Specific:==

<font color=#55ee99>UnitPreDamaged()</font> --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, attackerID, attackerDefID, attackerTeam" <span class="warning">(prior to 94.0)</span>

<font color=#55ee99>UnitPreDamaged()</font> --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" <span class="warning">(as of 94.0)</span>

<font color=#55ee99>UnitDamaged()</font> --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" <span class="warning">(as of 95.0)</span> <br>
<font color=#dd9944>Can overwrite the taken damage by returning a new number value.<br>

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</font>

<font color=#55ee99>UnitExperience()</font> --> "unitID, unitDefID, unitTeam, experience, oldExperience"

<font color=#dd9944>Spring.SetExperienceGrade must be called first to determine how often it is called</font>

<font color=#55ee99>UnitCreated()</font> --> "unitID, unitDefID, teamID, builderID"

<font color=#55ee99>UnitFinished()</font> --> "unitID, unitDefID, teamID"

<font color=#55ee99>UnitFromFactory()</font> --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

<font color=#55ee99>UnitDestroyed()</font> --> "unitID, unitDefID, teamID, attackerID, attackerDefID, attackerTeamID"

<font color=#55ee99>UnitTaken()</font> --> "unitID, unitDefID, unitTeam, newTeam"

<font color=#55ee99>UnitGiven()</font> --> "unitID, unitDefID, unitTeam, oldTeam"

<font color=#55ee99>UnitIdle()</font> --> "unitID, unitDefID, teamID"

<font color=#55ee99>UnitCommand()</font> --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams, cmdTag" <span class="warning">cmdTag only available from version 95.0</span>

<font color=#55ee99>UnitSeismicPing()</font> --> "x, y, z, strength"

<font color=#55ee99>UnitEnteredRadar()</font> --> "unitID, unitTeam"

<font color=#55ee99>UnitEnteredLos()</font> --> "unitID, teamID"

<font color=#55ee99>UnitLeftRadar()</font> --> "unitID, unitTeam"

<font color=#55ee99>UnitLeftLos()</font> --> "unitID, unitDefID, teamID"

<font color=#55ee99>UnitLoaded()</font> --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

<font color=#55ee99>UnitUnloaded()</font> --> "unitID, unitDefID, teamID, transportID"

<font color=#55ee99>UnitCloaked()</font> --> "unitID, unitDefID, teamID"

<font color=#55ee99>UnitDecloaked)</font>--> "unitID, unitDefID, teamID"

<font color=#55ee99>UnitMoveFailed()</font> --> "unitID, unitDefID, unitTeam"

<font color=#dd9944>Only called for unitDefIDs registered via [[Lua_System#Synced|Script.SetWatchUnit]] since 85.0</font>

<font color=#55ee99>StockpileChanged()</font> --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

<font color=#55ee99>UnitEnteredWater()</font> --> "unitID, unitDefID, teamID"
<span class="warning">(as of 95.0)</span>

<font color=#55ee99>UnitEnteredAir()</font> --> "unitID, unitDefID, teamID"
<span class="warning">(as of 95.0)</span>

<font color=#55ee99>UnitLeftWater()</font> --> "unitID, unitDefID, teamID"
<span class="warning">(as of 95.0)</span>

<font color=#55ee99>UnitLeftAir()</font> --> "unitID, unitDefID, teamID"
<span class="warning">(as of 95.0)</span>

<font color=#55ee99>ShieldPreDamaged()</font> --> "proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile"

<font color=#55ee99>UnitUnitCollision(colliderID, collideeID)</font> -- needs SetWatchUnit enabled for both parties

<font color=#55ee99>AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID)</font>

<font color=#dd9944>Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0</font>

<font color=#55ee99>AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defaultPriority)</font>
--> <code>return "targetAllowed, targetPriority"</code>
<span class="warning">, defaultPriority new in 89.0</span><br>

<font color=#dd9944>Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0</font>

<font color=#55ee99>DrawShield(number unitID, number weaponID)</font> --> 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:==

<font color=#55ee99>FeatureCreated()</font> --> "featureID, allyTeam"

<font color=#55ee99>FeatureDestroyed()</font> --> "featureID, allyTeam"

<font color=#55ee99>TerraformComplete()</font> --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

<font color=#55ee99>UnitCmdDone()</font> --> "unitID, unitDefID, unitTeam, cmdID, cmdTag, cmdParams, cmdOptions" <span class="warning">cmdParams and cmdOptions are only available from version 95.0</span>

<font color=#55ee99>UnitFeatureCollision(colliderID, collideeID, crushKilled)</font> -- needs SetWatchUnit for first and SetWatchFeature for second party

<span class="warning">95+</span><font color=#55ee99>FeatureDamaged()</font> --> "featureID, featureDefID, featureTeam, damage [, weaponDefID, projectileID [, attackerID, attackerDefID, attackerTeam ]]"

<span class="warning">95+</span><font color=#55ee99>FeaturePreDamaged()</font> --> "featureID, featureDefID, featureTeam, damage [, weaponDefID, projectileID [, attackerID, attackerDefID, attackerTeam ]]"

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

* <font color=#55ee99>DrawGenesis()</font> --> none. Don't render here.

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

* <font color=#55ee99>DrawWorldPreUnit()</font> --> none.

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

* <font color=#55ee99>DrawWorld()</font> --> none.

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

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

<font color=#55ee99>DrawUnit(unitID,DrawMode)</font><br>
With enum DrawMode {<br>
notDrawing = 0,<br>
normalDraw = 1,<br>
shadowDraw = 2,<br>
reflectionDraw = 3,<br>
refractionDraw = 4<br>
};

<font color=#55ee99>DrawFeature(featureID, DrawMode)</font><br>

<font color=#55ee99>DrawShield(unitID, weaponID, DrawMode)</font><br>

<font color=#55ee99>DrawProjectile(projectileID, DrawMode)</font><br>

<font color=#55ee99>DrawScreenEffects()</font> --> "vsx, vsy" where vsx, vsy are screen coords.

<font color=#55ee99>DrawScreen()</font> --> none.

<font color=#55ee99>DrawInMiniMap()</font> --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

<font color=#55ee99>DrawWorldShadow()</font> --> none.

<font color=#55ee99>DrawWorldReflection()</font> --> none.

<font color=#55ee99>DrawWorldRefraction()</font> --> none.

==Game Events:==

<font color=#55ee99>GameID()</font> --> "gameID" {{new|89.0}}

<font color=#55ee99>Explosion()</font> --> "weaponID, px, py, pz, ownerID"
<br><font color=#dd9944>Only called for weaponDefIDs registered via Script.SetWatchWeapon</font>
<br>return true to hide the weapon's CEG

<font color=#55ee99>ShockFront()</font> --> "power, dx, dy, dz" <span class="warning">Not yet implemented!</span>

<font color=#55ee99>GameFrame()</font> --> "frameNum"

<font color=#55ee99>CobCallback()</font> --> unknown, marked FIXME.

<font color=#55ee99>GroupChanged()</font> --> "groupID" where groupID is the value of Group whose table value changed.

<font color=#55ee99>WorldTooltip()</font> --> "ttType, data1, data2, data3" special, should be documented in detail. <span class="warning">Not yet implemented!</span>

<font color=#55ee99>GamePreload()</font> --> none.

<font color=#55ee99>GameStart()</font> --> none.

<font color=#55ee99>GameProgress()</font> --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation )<span class="warning"> Not yet implemented!</span>

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

<font color=#55ee99>TeamDied()</font> --> "TeamID" where TeamID = the team that has been eliminated.

<font color=#55ee99>AllowStartPosition()</font> --> "cx, cy, cz, playerID, readyState, rx, ry, rz", where rx,ry,rz are the position the player picked and cx,cy,cz are that position clamped to the startbox. readyState can be any one of <br> 0 -- player picked a position, <br> 1 -- player clicked ready, <br> 2 -- game was force-started (player did not click ready)
<br>return true/false to allow/deny placing startposition marker

<font color=#55ee99>GameSetup()</font> --> string "state", boolean "ready", table "playerStates"
<br>return success, newReady

<font color=#55ee99>GamePaused()</font> --> "playerID, paused"

<font color=#55ee99>PlayerAdded()</font> --> "playerID"

<font color=#55ee99>PlayerRemoved()</font> --> "playerID, reason"

==Projectiles:==

<font color=#55ee99>ProjectileCreated()</font> --> "proID, proOwnerID, weaponDefID"
<br><font color=#dd9944>Only called for weaponDefIDs registered via Script.SetWatchWeapon</font>

<font color=#55ee99>ProjectileDestroyed()</font> --> "proID"
<br><font color=#dd9944>Only called for weaponDefIDs registered via Script.SetWatchWeapon</font>

<font color=#55ee99>AllowWeaponInterceptTarget</font> --> "number interceptorUnitID, number interceptorWeaponID, number targetProjectileID"
returns boolean
<br><font color=#dd9944>Only called for weaponDefIDs registered via Script.SetWatchWeapon</font>

[[Category:Lua]]

Modrules.lua

2013-10-16T22:34:29Z

Pepeampere: /* los */ link for jk lesson

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

==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|Units-UnitDefs|buildtime}} i.e. a building with a larger {{xtaglink|Units-UnitDefs|buildtime}} will decay more slowly for a given value of this tag than a building with a shorter {{xtaglink|Units-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|Units-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|Units-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|Units-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|Units-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===
For a deeper explanation of the flanking system, see [[Units:FlankingBonus]].

{{tag
|name = defaultMode
|type = int
|default = 1
|description = The default {{xtaglink|Units-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
|description = Multiplies all unit's {{xtaglink|Units-UnitDefs|sightDistance}} by this value. Generally speaking you should always use the default.
}}

{{tag
|name = airMipLevel
|type = int
|default = 2
|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
|description = Multiplies all unit's {{xtaglink|Units-UnitDefs|airSightDistance}} by this value. Generally speaking you should always use the default.
}}

===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}}
|description = A ticket back to unit movement circa 2009: no reversing, no {{xtaglink|Units-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|Units-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|Units-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|Units-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.
}}

===system===
{{tag
|name = luaThreadingModel
|type = int
|default = 2
|description = Controls if and how the game supports Asynchronous Simulation, a more detailed explanation can be found [[Asynchronous_Simulation#Lua_Threading_Models|here]].
3 and greater is experimental/unstable!

Can be:
::<code>0</code> - No MT, single threaded;
::<code>1</code> - Single state;
::<code>2</code> - Single state, batching of unsynced events;
::<code>3</code> - Dual states for synced, batching of unsynced events, synced/unsynced communication via EXPORT table and SendToUnsynced;
::<code>4</code> - Dual states for synced, batching of unsynced events, synced/unsynced communication via SendToUnsynced only;
::<code>5</code> - Dual states for all, all synced/unsynced communication (widgets included) via SendToUnsynced only;
::<code>6</code> - Dual states for all, all synced/unsynced communication (widgets included) is unmanaged and via SendToUnsynced only.}}

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

===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:
<code><pre>
return {}
</pre></code>
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:
<code>
system = {
pathFinderSystem = (Spring.GetModOptions() and (Spring.GetModOptions().qtpfs == "1") and 1) or 0,
},
</code>

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

AI:Skirmish:List

2013-09-23T15:52:57Z

Pepeampere: added NOE + description

[[Main_Page|Main Page]] < AIs

Basics about [[AI:Skirmish|Skirmish AIs]] in Spring.

==== Under Active Development ====
Listed in alphabetical order.

; '''[[AI:AAI|AAI]]''' : <font color="orange">config-based</font>, <font color="#000000">C++</font>, uses learning techniques, by [[User:Submarine|Submarine]]

; '''[[AI:BAI|BAI]]''' : <font color="#00AAFF">config-less</font>, <font color="#00DDFF">Java</font>, BA only, by Petah

; '''[[AI:BKPAI|BKPAI]]''' : <font color="#00AAFF">config-less</font>, <font color="#000000">C++</font>, Kernel Panic only, by Baczek

; '''[[Spring_Tanks]]' Borked Advancer''' : <font color="#00AAFF">config-less</font>, <font color="#000000">Lua</font>, Spring Tanks only, by knorke
(Spring Tanks included AI is hardly an "intelligence" but might be usefull if you want to look at an example of a very bare-bones Lua AI. The file is Gadgets\tpAIbork.lua)

; '''[[AI:C.R.A.I.G.|C.R.A.I.G.]]''' : <font color="orange">config-based</font>, <font color="yellow">Lua</font>, currently [http://spring1944.net/ Spring 1944] and [http://www.imperialwinter.com/ SWIW] only, by Tobi

; '''[http://code.google.com/p/crans-java-ai/ CransJavaAI]''' : <font color="#00AAFF">config-less</font>, <font color="#00DDFF">Java</font>, port of KAIK, by cranphin

; '''[http://code.google.com/p/spring-djai/ DJAI]''' : <font color="orange">config-based</font>, <font color="#00DDFF">Java</font>, by DJ

; '''[http://springrts.com/phpbb/viewtopic.php?f=15&t=19450 E323AI]''' : <font color="orange">config-based</font>, <font color="#000000">C++</font>, plays XTA, BA & BOTA by [http://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=4131 Error323] & [http://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=6441 Simon Logic]

; '''[[AI:HughAI|HughAI]]''' : <font color="orange">config-based</font>, <font color="#00DDFF">Java</font>, port of CSAI, by Hugh Perkins

; '''[[AI:KAIK|KAIK]]''' : <font color="#00AAFF">config-less</font>, <font color="#000000">C++</font>, best suited for *A mods, based on [[AI:KAI|KAI]] by Krogothe, now developed by [http://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=3405 Kloot]

; '''[http://springrts.com/phpbb/viewtopic.php?f=55&t=28259 NOE]''' : <font color="orange">config-based</font>, <font color="yellow">Lua</font>, AI for NOTA, gadget AI ready to use, developed by [http://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=9850 PepeAmpere]. Widget version planned. Small [http://code.google.com/p/nota/wiki/NOE_introduction manual on project Wiki].

; '''[[AI:NTAI|NTai]]''' : <font color="orange">config-based</font>, <font color="#000000">C++</font>, the longest running AI, currently non-functional, by [[User:AF|AF]]

; '''[[AI:RAI|RAI]]''' : <font color="#00AAFF">config-less</font>, <font color="#000000">C++</font>, supports many mods due to its universality, by [http://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=2771 Reth]

; '''[[AI:Shard|Shard]]''' : <font color="orange">config-based</font>, <font color="#000000">C++</font> & <font color="yellow">Lua</font>, highly configurable/adjustable, by [[User:AF|AF]]

==== Special ====

; '''[[AI:NullAI|NullAI]]''' : C Test AI, does nothing<br><br>
; '''[[AI:NullJavaAI|NullJavaAI]]''' : basic Java Test AI, does nothing<br><br>
; '''[[AI:NullLegacyCppAI|NullLegacyCppAI]]''' : Legacy C++ Test AI, does nothing<br><br>
; '''[[AI:NullOOJavaAI|NullOOJavaAI]]''' : Java Test AI using the OO wrapper, does nothing<br><br>

==== No Longer Under Development ====
None of these AIs will work with the current spring release version.
They are listed here, in case someone wants to take up development again,
and for code reference.

; '''[[AI:AGAI|AGAI]]''' : <font color="#00AAFF">config-less</font>, <font color="#00DDFF">Java</font>, by [[User:abma|abma]]<br><br>
; '''[[AI:CSAI|CSAI]]''' : C# AI, by Hugh Perkins<br><br>
; '''[[AI:JAI|JAI]]''' : first try at writing an AI in Java, by [[User:hoijui|hoijui]]<br><br>
; '''[[AI:JCAI|JCAI]]''' : by Zaphod<br><br>
; '''[[AI:KAI|KAI]]''' : by Krogothe<br><br>
; '''[[AI:MyAI|MyAI]]''' : An earlier AI, by Berion<br><br>
; '''[[AI:OTAI|OTAI]]''' : V1.13, An AI aimed at emulating the AI in OTA, by Veylon<br><br>
; '''[[AI:QAI|QAI]]''' : V2.42, A half finished AI, by Qman<br><br>
; '''[[AI:SAI|SAI]]''' : V0.15, by Spectre<br><br>
; '''[[AI:TSI|TSI]]''' : A Polish project, originally based on [[AI:SAI|SAI]]<br><br>
; '''[[AI:TAI|TAI]]''' : replaced by [[AI:NTAI|NTai]], by [[User:AF|AF]]<br><br>
; '''[[AI:ZcAIn|ZcAIn]]''' : by Cain<br><br>

==== Planned For Development ====
; '''[[AI:Epic|Epic]]''' : Next Gen AI, planned by [[User:AF|AF]]<br><br>
; '''[[AI:GAI|GAI]]''' : Groovy AI, planned by [[User:hoijui|hoijui]]<br><br>
; '''[http://github.com/ato/clojai/tree/master ClojAI]''' : Clojure AI, planned by ato
[[Category: AI]]<br><br>

NOTA

2013-09-15T23:14:39Z

Pepeampere: PepeAmpere - deleted all stuff to avoid missunderstandings

{{deprecated|This page is deprecated, please look at the [https://springfiles.com/spring/games/nota-36 NOTA Homepage]}}

Back to [[Games]]
[[Category:NOTA]]
[[Category:Games]]

AI:Development:Lang:Lua

2013-09-15T21:36:05Z

Pepeampere: /* References */ added link for NOE

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Lua AI Development

There are currently two possibilities, either write a Lua AI (see below) or use the [[ AI:Shard|Shard AI]] and write your lua-code for it. Using Shard has the benefit, that it is game-independant and the code is only executed on one machine, while a Gadget AI has to run on every computer.

<h1>Writing a Lua AI</h1>

== Introduction ==

=== Lua AIs are different ===
Lua for AIs is quite different from all the other AI languages supported by spring. Lua AIs use a completely different interface, and they can not be shipped separately, but only bundled with a mod.

=== Things to know ===
* They have to be bundled with a mod. Therefore, you should consider contacting the mod developer(s) in question early, to see if they are at all interested in an AI.
* A Lua AI is actually a regular gadget. The difference is just that it is listed in the mods LuaAI.lua file. See [[Lua_Scripting|Lua Scripting]] for details.
* This brings up the problem that AIs can "accidently" cheat or even move units of the enemy! It is up to the AI writer to avoid that. All AI players of the same type also share the same variables and tables. One way to avoid that is to put everything into a teamdata[teamID] table. Or the use of classes.

== How to start ==
For a start, choose a sinlge mod you want your AI to work with.
You will also want to contact the mods developpwer(s) before you start to code,
or soon thereafter.

Things you need to get comfortable with:
* the Lua scripting language
* Lua scripting for spring (gadgets)

You may combine learning Lua for spring with writing simplistic gadgets or widgets for spring, and publishing them [http://springrts.com/phpbb/viewforum.php?f=23 in the forum],
as this way you get practical training and feedback about your code from the pros, plus the community eventually gets a usefull addon.
When you start feeling comfortable, you should inspect the code of Lua AIs that are already available.
Source code of these AIs can be found in the mod archives, which you may open with 7zip, or it may be available separately (see [[#References|References]]).

=== Integrating the AI Gadget ===
This section explains everything you have to do to integrate your Lua AI into a mod. Which at the same time is everything that separates a Lua AI form a gadget.

In the root of the mods archive, you need the file ''LuaAI.lua'',
which should look about like this:
<code>
-- file: LuaAI.lua
local listOfLuaAIs = {
{
name = "MyFirstAI",
desc = "Beats even the best players with Core, most others with Arm too",
},
}
return listOfLuaAIs
</code>

Besides all the other stuff you need for a gadget (you should know this by now),
you will need something like this in your code (eg under ''{mod_root}/LuaRules/Gadgets/MyFirstAI_v01.lua''):
<code>
function gadget:GetInfo()
return {
name = "MyFirstAI",
desc = "An AI that knows how to play Mod X",
author = "John Doe",
date = "2020-12-31",
license = "Public Domain",
layer = 82,
enabled = true
}
end

function gadget:GameStart()
-- Initialise AI for all teams that are set to use it
for _,t in ipairs(Spring.GetTeamList()) do
local _,_,_,isAI,side = Spring.GetTeamInfo(t)
if Spring.GetTeamLuaAI(t) == gadget:GetInfo().name then
Spring.Echo("Team "..t.." assigned to "..gadget:GetInfo().name)
local pos = {}
local home_x,home_y,home_z = Spring.GetTeamStartPosition(t)
end
end
end
</code>
'''Note:'''
The above example will not work if your AI controls multiple teams because ''home_x,home_y,home_z'' are not stored ''per team.''

That's it, the rest of the game is using regular gadget functions, and in particular [http://springrts.com/wiki/Lua_SyncedCtrl#Give_Order Spring.GiveOrderToUnit()]. Now you should be able to use this AI when starting the modified mod in the lobby, when you click on the ''Add Bot'' button.

Enjoy!

== References ==
* NOE AI: http://springrts.com/phpbb/viewtopic.php?f=55&t=28259
* KP AI source: http://pastebin.com/f771164a0
* CRAIG source:
** to browse: http://github.com/tvo/craig/tree/master
** for git: git://github.com/tvo/craig.git
* C.R.A.I.G. is inside S44 and SWIW
* forum thread: [http://springrts.com/phpbb/viewtopic.php?f=15&t=25639 LuaAI information]
* forum threads about an AI for the game Conflict Terra: [http://springrts.com/phpbb/viewtopic.php?f=63&t=26148] [http://springrts.com/phpbb/viewtopic.php?f=63&t=26214] [http://springrts.com/phpbb/viewtopic.php?f=15&t=26207] (among the OT, some more or less common LuaAI problems are discussed)

[[Category: AI Dev]]

GamesDownloads

2013-05-23T11:12:13Z

Pepeampere: /* Game installers (for players) */

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Zero K + Lobby (windows only)|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
{{Template:GamesDownload|name=NOTA + lobby (+ maps + best replays + taunts) - WINDOWS/MAC-OSX/LINUX|image=NOTA.png|url=http://springfiles.com/spring/game-installers/nota-installer}}
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}}
</div>

<span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=http://www.springlobby.info/windows/latest.zip}}
(Multiplatform)

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows only, multi-engine support, uncheck 'official games' to see all)

{{Template:GamesDownload|name=TASClient|url=http://springrts.com/wiki/Lobby_Development#TASClient}}
(Windows only)

{{Template:GamesDownload|name=pr-downloader (command-line)|url=http://springrts.com/wiki/Pr-downloader}}
</div>

<span class=note>Notes: The above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]]. </span>

Others:
{{Template:GamesDownload|name=NOTA :: Lobby|image=NOTA.png|url=http://springrts.com/phpbb/viewtopic.php?f=64&t=30120}}
(Cross-Platform, multi-engine support)

{{Template:GamesDownload|name=rapid (command-line)|url=http://github.com/tvo/rapid}}
(currently only downloads games, no longer supported)

[[Category:Spring]]

GamesDownloads

2013-05-22T02:47:07Z

Pepeampere: /* Game installers (for players) */ added NOTA installer

{{#css:
table.glossy {
width: 200px;
margin: 9px; padding:3px;
border: 1px solid rgba(0,0,0,0.5);
border-radius: 10px 10px 10px 10px;
box-shadow: 0 2px 6px rgba(0,0,0,0.5), inset 0 1px rgba(255,255,255,0.3), inset 0 10px rgba(255,255,255,0.2), inset 0 10px 20px rgba(255,255,255,0.25), inset 0 -15px 30px rgba(0,0,0,0.3);
text-align: center;
}

/*#installers img {
border: 1px solid rgba(0,0,0,0.5);
box-shadow: 0px -1px 3px rgba(0,0,0,0.8), 0px 1px 3px rgba(255,255,255,0.5);
}*/

/*table.glossy:hover {
background: rgba(160,160,220,0.4);
}*/
}}
[[Download]] < {{FULLPAGENAME}}

= Game installers (for players) =
Below are three Spring games that comes with complete installer (containing all the files you need to play those games):
<div id="installers" style="padding-left:7px">
{{Template:GamesDownload|name=Zero K + Lobby (windows only)|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
{{Template:GamesDownload|name=NOTA + lobby (+ maps + best replays + taunts) - WINDOWS/MAC-OSX/LINUX|image=NOTA.png|url=http://springfiles.com/spring/lobby-clients/nota-installer-game-lobby-engine}}
{{Template:GamesDownload|name=Kernel Panic|image=Kernel_Panic_3.4.jpg|url=http://springfiles.com/spring/game-installers/kernel-panic-installer}}
</div>

<span class="warning">(!)</span> Old engine version included. Experience of online play might be hampered.

For more Spring games, check out the [[Games]] page. Please note that some of them will require you to have the engine installed in order to work, as well as some maps, as they don't come with their own installer.

= Universal Downloaders =
As Spring itself is just an engine and does not contain game content.<br/>
There are several options for getting games/maps though, one is using the internal downloaders of the lobbies:

<div style="padding-left:7px">
{{Template:GamesDownload|name=SpringLobby|image=Springlobby_64.png|url=http://www.springlobby.info/windows/latest.zip}}
(Multiplatform)

{{Template:GamesDownload|name=Zero-K lobby|image=eclipse.jpg|url=http://zero-k.info/Wiki/Download}}
(Windows only, multi-engine support, uncheck 'official games' to see all)

{{Template:GamesDownload|name=NOTA :: Lobby|image=NOTA.png|url=http://springrts.com/phpbb/viewtopic.php?f=64&t=30120}}
(Cross-Platform, multi-engine support)

{{Template:GamesDownload|name=TASClient|url=http://springrts.com/wiki/Lobby_Development#TASClient}}
(Windows only)

{{Template:GamesDownload|name=rapid (command-line)|url=http://github.com/tvo/rapid}}
(currently only downloads games)
</div>

<span class=note>Notes: All above mentioned tools are included in the [[Download#Spring_Engine_Updates|Spring installer]].</span>

[[Category:Spring]]

NOTA players guide

2013-05-12T03:33:30Z

Pepeampere: /* Factors to consider when choosing units to be produced */

This is an NOTA players guide, made by 123v and HeavyLancer.

This is by no means a definitive strategical guide to NOTA, because there are so many units and strategies that it would take forever to think them all up and list them. This Guide gives you the knowledge and understanding to develop your own strategies and tactics.

== Overview ==

This guide is about unit selection for various situations, some general tactics and strategies for all 3 fields of battle; land, sea and air. All of these fields of battle in NOTA are equally important, and it is advised not to concentrate solely on one at the expense of others.

At the end are sections on economy, defenses and a section on general strategies, tactics and some notes.

----

== Land ==

=== Tier 1 ===

* The Kbot is a very valuable unit. It is cheap and dishes out the best fire power at cost. However, Kbots lack armor, health and speed but you get the most fire power for the cost.

* Vehicles are best used as tier 1 Kbot support as vehicle artillery and AA has better range than their Kbot equivalents. Vehicles also have greater speed and better armour (making them better base assault units not unlike Calvary). They are also less cost effective than Kbots in terms of damage dealing capacity.

* If you need a mobile army for a big map you may want a a vehicle army because of the extra mobility and aforementioned armour. However, for that cost you could build 2 Kbot armies, which can push for more ground, still hold their own, and have more firepower.

*You will also find that kbots maneuver better in battle while vehicles have speed. The differences come out on large maps, as small maps one may even wonder why they would even build vehicles.
=== Tier 2 ===

* As tier 2 units hit the battle field tier 1 units will play a smaller role in the bigger battles, but one of the neat things about NOTA is that tier 1 units have important uses even into the late game where as in many other mods they are a waste of resources.

* Tier 2 units are really neat. You can see for your self in-game. The Arm Raptor IV Kbot is a work of art. Even if you will not play NOTA, you should still see this unit. As it takes hits in battle it will also lose weapons as different parts are blown off.

=== Some notes on specific units ===

* The peewee is a very useful unit in NOTA. It is cheap, moves at a high speed, for a Kbot, has a spray attack, decent health, and does not take out all it's mates when it is killed! (Unlike in some other mods) The Core AK is the same but the lazers it has are just not as cool.

* Another ground unit you should know about are the speedy raider bots. They are fast, have a decent attack range, and do decent damage. An opponent that micromanages these early on in the game can be a nightmare if you are not prepared. These raider bots are good for raiding, killing arty, snipers, and when micromanaged, small groups of Kbots. '''Do not''' try to kill them with Arm Flash tanks. The Zeus, Core Instigator, and units whose projectiles move fast enough to hit fast moving targets are good for dealing with these.

* T1 artillery for both Arm and Core are great for fire power on low trajectory, but is not very mobile. T2 Kbot artillery is costly, but a giant gun on legs.

----

== Air ==

=== Air vs Sea ===

*Ships are rather costly and as a result come with some AA. It is a good idea not to fly near ships. Torpedo bombers should be used against ships, but not in closely clumped packs, as ship AA will deal splash damage to those poor planes of yours, and kill them off very quickly. If you do not use them in packs pilots will not be coming home, and they will not be able to tell stories of the great ships they sunk.

* Toads and Vashps can also be used against ships, but not subs. Bombers and such will not be very effective for dealing damage to ships as you will see for yourself.

* There are sea based planes but land based air is really where it's at.

=== Tier 2 ===

Tier 2 air is a world apart from tier 1, just in sheer terms of variety.

* A pack of tier 2 bombers can give some tier 1 fighters a bad time and an early death as the tier 2 bombers have better AA thanks to their tail guns. Still, a large pack of tier 1 fighters will drop even tier 2 bombers. Tier 2 fighters are better.

* Stealth bombers use 200 E for stealth. They are fragile and won't last long if detected. Ground radar can detect them if they fly directly overhead. Otherwise, radar planes are the best way of detecting them.

* Wings are deadly low flying laser beaming monsters flaunting a laser of death and two bombs, but every AA unit can hit them, so they can fall out of the sky fairly quickly. They fly slow, so a retreat must be premeditated if the wing is to live. It does not have a large fuel tank so it is not a great deep strike unit, unless you have mobile airpads with you.

* The Core Flying Fortress is a very costly unit but a pain to kill as it has AA and a lot of armor and health. Interceptors are the best way to kill them. If you have less than 20 Tier 1 aircraft after a flying fortress comes your not going to have much of a fighter force left afterwards. 20 Tier 1 fighters have a decent survival chance if they attack as a group. The Tier 2 interceptors are the best way to kill a flying fortress though. Flak is not bad but a flying fortress is flak resistant (flak will still kill it, however).

=== Notes on Air ===

* The Tier 1 ground attack planes (Toad and Vashp), are excellent. They are not cheap or easily built but are wonderful for cleaning up problems in your base or behind your front lines. A toad can pick off raiders in your wind mill farm without causing much collateral damage at all.

* Planes have fuel, and it makes for great game play. Airpads are cheap but needed. A tier 1 air factory comes with a pad as part of the kit (W00t!)

* 4-5 accurately placed bomb drops from a tier 1 or tier 2 strategic bomber can destroy most factories. About 32 (since NOTAv1.59 40+ bombers) bombers can kill a Command Center and 9 stealth bombers will do the same job.

* Napalm bombers are great. They are fast and fly low to avoid a lot of AA. Rocket towers or tier 2 rocket units put a stop to them best.
Napalm. Beautiful. Hit massed units with it. Hit econ farms with it. Love it when you use it. Hate it when it is used against you.

* Air is a huge part of establishing regional control. Getting a fighter within response range to discourage air to ground attacks and ground based AA discourage air to air attacks. This can be done with 1-2 fighters and 2-3 ground AA.

* the cheap static chaingun AA turrets costing 34 metal are a good panic response option for to low altitude air (the are build-able in the field by construction bots/vehicles)
----

== Sea ==

* Firstly, a word on hovers. Hovers are cheaper than ships so it is nice to use them as they do not cost as much. Hover arty is the best hover unit for fighting small ships, but understand that ships are the kings of the sea, not hovers. 6 hover arty will pwn a Destroyer and you could pull it of with 4 of them if you're really good, but don't count on it. A hover transport will CARRY a MOHO builder(T2 metal extractor constructor). This is important as Moho builders are very important units in NOTA and they are very slow.

=== Ships ===

* Ships are huge investments and as a result have a huge impact on the field of battle. Losing sea, followed by the enemie's use of naval bombardment is not fun and will end the game. If there is sea on the map '''you will want it'''.

* As a ship is valuable you do not want to lose your first ship, so watch it closely, but do not be afraid to use it because you just may catch your opponent with his pants down. If an AA ship can park in your harbor you can say good bye to your air supremacy, and then you've got a problem.

* The Destroyer is really the runt of the ship family but it's radar and sonar ranges are huge. It has the most torpedoes of any ship(4, with 2 on each side), yet it's low health is a bit of a drawback.

* The Cruiser is a great all purpose ship. 123v envies the Core version, it's the best ship you could dream up. Cruisers effectively have 2 torpedoes, a nice set of guns, decent range, and a small sonar radius.

* Subs carry a lot of fire power. They have 1 guided and 3 unguided torpedo launchers, but have little health and can be beaten with ease. Subs can cause a lot of hurt before torpedoes reach them and if they are lucky they may even live. 2 lucky subs can kill a destroyer, but the same destroyer on a lucky day could also kill both subs in the same exchange.

=== Factional Navy Differences ===

* Arm ships are more single purposed and thus cost a lot less as they typically have less AA, and are just not as much. Core ships typically lack the range of the arm ships but do have more hp and are packing a more all-purpose bite.

For instance, a Core missile ship packs a cruiser gun battery and other weapons to boot. An Arm missile ship is much smaller but costs half the price, and has effectively no additional weapons. A player who keeps his resource spending in mind would prefer the arm missile ship as he can get more missile bang for the buck, but he will need to defend his ships with additional units where as the Core ship can dish out some damage to all units, except subs.

* The Core battle cruiser is a floating pile of health where as the Arm battle cruiser has half the health, but has much longer-ranged guns.

----

== Economy ==

* Economy is costly in NOTA which means that using MMs (energy to Metal Makers) is not a way to get a heavy economy rolling. If you have a good supply of Energy then use MMs, but producing units to gaining or defend metal spots will get you a lot further than throwing your resources into a bunch of fusions.

* Heavy economy building cost a lot of Metal and takes time to build. Getting Moho metal extractors (Mohos) is a huge deal, and it costs you nearly 5000 M to get your first Moho up and running. Mohos have more health as they do cost a lot.

* In NOTA wind does not have a huge explosion so u do not have to be as afraid to use it.

== Defense ==

* NOTA defensive units are costly but very effective. Spending the M can be a real setback, but if it was well chosen it will serve you well. You will find that NOTA does not have indestructible weapons. Super weapons built prematurely are very easy to lose. Mobile units should be mixed with static defense for the best results. Static AA can remove large airborne problems quite nicely too. After you have about 12 flack they start to become very effective. Transportable flack has a faster turn rare and is thus better for shooting low-flying targets then static flack.

*Use a transport unit to carry transportable defenses to new locations.

=== Air Defense ===

* The best way and most cost effective way to establish air supremacy is to build fighters. You should make use of ground Anti-Air to make sure that your fighters win, but it is not cost effective to use ground AA to hold your airspace. Ground based AA will also be a deterrent for enemy aircraft, but this does not equal safety as ground attack air craft can remove small groups of AA without much trouble.

* As fighters can be lost easily over enemy airspace is is normally better not to lose them in a conflict over enemy airspace. Instead, more costly ground-based AA could be a safer option for your air force.

* '''Warning!''' Only flak and ship based high altitude missiles will hit high flying planes such as bombers. All other surface AA is for low altitude air defense.

* Flak has splash damage but is also inaccurate, however, it can case premature deaths by causing an engine fire. Once you have 8-10 flak it will become effective and enemy bomber losses will be heavy.

* Transportable (yes, transportable!) flak turrets do the same damage as non-transportable versions and have a faster turret turn rate, so it is not so bad against fighters (but still inaccurate). Use a transport unit to carry transportable defenses to new locations.

=== Sea Defense ===

* An anti ship gun is a powerful weapon, but air can knock it out with ease, so keep air supremacy or invest in some heavy AA.

* Heavy, long range weapons (such as strategic cannons) are a great way to back your sea effort, and a good way to hold it. Big Berthas (Arm strategic cannons) have a good range for controlling sea, and do good damage to boot.

----

== General Strategies, Tactics and Notes ==

=== Tactics ===

* Keeping your army alive, micro'ing your lines during confrontation is part of the game. A well lead army can achieve wonders.

* Raiding and attacking your enemies' economy is good, as NOTA's econ is a serious investment. Captured ground and mexes are more valuable in NOTA than other mods. Doing raids and not just one all out attack will help you gain the upper hand so you can make that heavy attack and succeed.

* Picking apart your enemy:
Because diversity is so powerful in NOTA breaking up your enemy's diversity exposes his vulnerabilities. Most units all do a specific extremely very well.

*Due to the tides of battle, it may be best to let the battle rage back and forth over your/their mex spots(metal extraction spot) rather then trying to hold at the mex spot, just be sure to cap it when available.

=== Strategies ===

'''Teching'''

* Once you have 3 or more factories you might think of going to Tier 2 depending on how the game is going. As you get a feel for the game you will know when and even if you want to tech. The Tier 2 units are much more useful than Tier 1 units but also cost a good deal more so there will be many more Tier 1 units than Tier 2 units.

* Building an air factory before going to Tier 2 in any other area is also often a wise idea if you haven't already.

=== Notes ===

* Factories cannot be assisted in NOTA. Most NOTA factory production is faster than it is in other mods. If you want larger unit production you can build another factory. In NOTA diversity is very important. As a result you should have a number of factories early on, perhaps even before you can keep them all running at full production. NOTA factories can increase and decrease their production speed so as not to consume resources or build as quickly, depending on your needs.

* There are three armor classes: light, medium and heavy. Units do different damage to the different armor classes, as you would expect. Most Kbots have no armor. Armor is weaker at the sides and weakest at the rear, often the thicker the armor the greater the weak points.

=== Factors to consider when choosing units to be produced ===

* Weapon characteristics such as rate of fire, accuracy, area of effect, damage, turret turn rate, and how the damage and projectiles reach the target
* Armour class and health
* Speed and turn rate
* Build time(which decides what is practical to produce), energy and metal required to manufacture the unit
* Cost-effectiveness with regards to firepower
* Stealth characteristics such as cloaking, stealth and decloaking radius

You can find detailed unit stats here: http://nota.machys.net/nota-units
----
Content created and edited by HeavyLancer and 1-23v[NOTA]
----
<-- Back to the [http://spring.clan-sy.com/wiki/NOTA NOTA wiki]
[[Category:NOTA]]

Games

2013-05-10T17:00:54Z

Pepeampere: /* TA-derived */ - https -> http

__NOTOC__There are a number of games made for the Spring Engine. Some of the more popular ones are listed below, sorted by their terms of use. 

=Open Source=
''These games are all free to download and play and may be open to modifications, however, be sure to read the licenses before doing so.''
{|
|-
| align="center" | <h2>[http://zero-k.info/ Zero-K]</h2>
([http://code.google.com/p/zero-k/source/browse/trunk/mods/zk/legal.txt GPL, PD])
| width=40 |
| align="center" | <h2>'''[http://spring1944.org/ Spring: 1944]'''</h2>([http://spring1944.svn.sourceforge.net/viewvc/spring1944/trunk/S44Main.sdd/docs/License.txt CC-BY-NC])
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Zero-k_image.jpg|link=http://zero-k.info/}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=S44_tigers.jpg|link=http://spring1944.org}}
|-
| align="justify" valign="top" | Zero-K is a fast, competitive game with a focus on a streamlined economy and advanced interface that takes the focus off tedious tasks and back on the action. A huge roster of interesting, unique units and a variety of unit abilities provides tremendous tactical and strategic depth to the game. [http://zero-k.info Download link]
|
| align="justify" valign="top" | Spring:1944 is a WWII themed game with four fully functional sides (US, Germany, USSR, Britain), period-accurate units and strengths. Realism comes second only to creating a game that is fun and accessible to play.
|-
| align="center" | <h2>[http://www.evolutionrts.info Evolution RTS]</h2>([http://creativecommons.org/licenses/by-nc-nd/3.0/us/ CC-BY-NC-ND])
| width=40 |
| align="center" | <h2>[[Kernel Panic]]</h2>([[Kernel_Panic#License:|FOSS, with only 2 FOSS maps]])
|-
| align="center" | {{navimgx|xsize=300|ysize=188|image=Evoimg.jpg|link=http://www.evolutionrts.info}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Kernel_Panic_3.4.jpg|link=Kernel Panic}}
|-
| align="justify" valign="top" | A new war is brewing. A violent conflict, between the Six Colonies, each one convinced that it was in the right, each one sure of its own ability to defeat its enemies. But they need Generals. They need soldiers. They need you.
|
| align="justify" valign="top" | A game based around combat '''inside''' a computer, with 3 unique sides: the System, the Hacker and the Network waging war in a matrix of DOOM! No resource economy exists in KP, with the only constraints being time and space.
|-
| align="center" | <h2>'''[http://www.moddb.com/games/conflict-terra Conflict Terra]'''</h2>([http://code.google.com/p/conflictterra/source/browse/games/CT/License.txt FOSS])
|
| align="center" | <h2>[[Spring Tanks]]</h2>([http://pastebin.com/Wpub9wWw undecided, some obscure free license])
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=CT_Hojos.png|link=http://www.moddb.com/games/conflict-terra}}
|
| align="center" | {{navimg|xsize=300|ysize=221|image=Springtanks_wikipreview.jpg|link=Spring Tanks}}
|-
| align="justify" valign="top" | A unique game with heavy emphasis on mobility and featuring Spring's first major "collect and drop-off" economy, Conflict Terra boasts a distinctive art style. Play as one of two factions in an ever-changing battlefield as you struggle to come out on top.
|
| align="justify" valign="top" | Some guys decided to attack each other with tanks and you can be one of them.
Build-in Single Player!
|}

=Proprietary=
''These games may or may not be free to play. Modifying their content (i.e. the art assets) is not allowed without the game authors explicit permission, although the code is GPL and some games (P.U.R.E.) include large GPL-friendly content collections.''

{|
|-
| align="center" | <h2>[http://www.imperialwinter.com Star Wars: Imperial Winter]</h2>
| width=40 |
| align="center" | <h2>[http://www.indiedb.com/games/the-cursed The Cursed]</h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=Imperial Winter assault.jpg|link=http://www.imperialwinter.com}}
|
| align="center" |{{navimgx|xsize=300|ysize=225|image=cursed_logo.jpg|link=http://www.indiedb.com/games/the-cursed}}
|-
| align="justify" valign="top" | A Star Wars themed game set in the troubled post-Return of the Jedi era. SW:IW is currently [http://springrts.com/phpbb/viewtopic.php?f=46&t=25108|in closed development and not playable for the public.]
|
| align="justify" valign="top" | The game is about bones, undead, demons, space marines and magic settled in a futuristic environment. It is a fresh mixture of gameplay elements from many popular RTS games like Starcraft and C&C.
|}

=TA-derived=
''At least parts of these games are derived from data of the Total Annihilation game (copyright Atari). As such, their distribution is potentially in breach of copyright laws and therefore not officially endorsed by the Spring RTS team.''

{|
|-
| align="center" | <h2>[http://balancedannihilation.org Balanced Annihilation]</h2>
| width=40 |
| align="center" | <h2> [http://springfiles.com/spring/games/tech-annihilation-8 Tech Annihilation] </h2>
|-
| align="center" | {{navimgx|xsize=300|ysize=225|image=BAScreenShot.jpg|link=http://balancedannihilation.org}}
|
| align="center" |{{navimgx|xsize=300|ysize=200|image=Tech_Annihilation.png|link=http://springfiles.com/spring/games/tech-annihilation-8}}
|-
| align="justify" valign="top" |
Balanced Annihilation (BA) is a mature game and new versions feature only minor balance tweaks.

BA gameplay develops in stages of progressively heavier units with a growing economy. Many strategies are viable in BA, including focusing on map control, aggression, defense, air power, sea power, or mobility.

|
| align="justify" valign="top" | This Game is bigger, greater and more epic! Tech your Commander from a tiny Commander to a Galactic Commander! (by ''[BoS]Senna'', currently no homepage)
|}

{|
|-
| align="center" | <h2>[http://springfiles.com/spring/games/nota-36 NOTA]</h2>
| width=40 |
| align="center" | <h2>[[XTA]]</h2>
|-
| align="center" |{{navimgx|xsize=300|ysize=225|image=Nota2nukes.jpg|link=http://springfiles.com/spring/games/nota-36}}
|
| align="center" | {{navimg|xsize=300|ysize=225|image=Screen508_s.jpg|link=XTA}}
|-
| align="justify" valign="top" | Not Original Total Annihilation is a rethink of the Total Annihilation universe with a focus on strategic, base oriented gameplay. With its revised unit scale, huge battles erupt engaging hundreds of units and scores of unit types. NOTA's completely rethought air and sea gameplay forces participation in all elements and places the tide of conflict in your hands.
|
| align="justify" valign="top" | Originally developed as a Total Annihilation game by the Swedish Yankspankers, XTA is the Original Public Game released with first versions of Spring. Development of this game by the SYs has stopped a while ago, but it is still played and actively developed by the community.
|
|}

=Installing Games in Spring=
Quite a few of the games listed above come with standalone installers, which makes things easy. Check their website to find out!

In some cases however, the game will only distribute a game-file, for example ''BA750'''''.sd7''' or ''XTA'''''.sdz'''. For these games, you have to [[Download|install the stand-alone Spring-Engine]] first, and then place the game-file in the ''...\My Documents\My Games\Spring\Games\'' or ''...\Spring\games\'' folder (''~/.spring/games/'' on Linux/Unix/Mac).
You may install multiple games in the same engine installation.

To play a game, you also need a [[Maps|map]].

Still not enough Games? There are [[Getting_Spring_Content_and_Links|some more]], not listed here or make your [[Game_and_Unit_development|own Game]]!

[[Category: Games]]

Gamedev:UnitDefs

2013-04-26T03:03:58Z

Pepeampere: /* Movement & Placement */

==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==
Tags may be one of the following data types:
* <code>int</code> - An integer number
* <code>float</code> - A number with decimals.
* <code>bool</code> - A value which can be <code>true</code> or <code>false</code>.
* <code>string</code> - Text, or more precisely a string of alphanumeric characters.
* <code>float[3]</code> - A vector, with three <code>float</code> components, representing x, y and z axes (y is 'up').

==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 = ""
|description = This is simply the name of the unit as it appears to the player.}}

{{tag
|name = description
|type = string
|default = name
|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 = ""
|description = The filename of the image to be used as the build picture, assumes <code>Unitpics/</code> directory (see [[Units:Buildpics]]).}}

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

{{tag
|name = script
|type = string
|default = unitName + ".cob"
|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
|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
|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
|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. Effectively, <code>Time to build = buildTime / workerTime</code>. Defaults to <code>0.0</code> but cannot actually be below <code>1.0</code>.}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{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
|description = The radius of the units sight (LOS is circular in Spring)}}

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

{{tag
|name = losEmitHeight
|type = float
|default = 20.0
|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
|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
|description = The radius of the units radar.}}

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

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

{{tag
|name = sonarDistance
|type = int
|default = 0
|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
|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
|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
|description = Can the unit be issued a self destruct order?
}}

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

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

{{tag
|name = noAutoFire
|type = bool
|default = false
|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|Units-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
|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
|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
|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|Units-FeatureDefs|geoThermal}} feature, does not actually count as a square,
:: <code>h</code> - 'High Resolution' - Indicates that the yardmap will use double resolution with four times as many characters. Must be the '''first''' character, and does not count as a square itself ({{new|93.0}}),
::<code>o</code> - 'Obstacle' - Always closed, blocking, all other chars are treated the same way.
: Tip: 'Draw' out the yardmap over multiple lines. As of <span class=warning>89.0</span> all whitespace characters are ignored, including newlines.
}}

{{tag
|name = 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 = ""
|description = The name of the movement type a mobile, non aircraft, unit should use. See [[Movedefs.lua]]. Other tag usage should be consistent with this i.e. {{taglink|canHover|true}} IFF using a <code>HOVER</code> based movetype.
}}

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

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

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

{{tag
|name = maxSlope
|type = float
|default = 0.0
|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.
}}

{{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
|special = lua: ud.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
|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. (<span class=warning>dont work in 94.1</span>)
}}

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

{{tag
|name = brakeRate
|type = float
|default = 3.0 * acceleration
|description = The deceleration of the unit, in [[elmo]]s per frame<sup>2</sup>. If the value is -ve, the absolute value is used. For units with {{taglink|canFly|true}} this is multiplied by <code>0.1</code>.
}}

{{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===
For a deeper explanation of these tags, see [[Units:FlankingBonus]].

{{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
|description = The altitude in [[elmo]]s which the unit attempts to fly at while cruising.
}}

{{tag
|name = airHoverFactor
|type = float
|default = -1.0
|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
|description = The maximum flight time in seconds before aircraft must return to an airbase to refuel.
}}

{{tag
|name = refuelTime
|type = float
|default = 5.0
|description = The time in seconds required to refuel the aircraft at an airbase.
}}

{{tag
|name = minAirbasePower
|type = float
|default = 0.0
|description = The minimum {{taglink|workerTime}} an airbase must have to repair / refuel this aircraft.
}}

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

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

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

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

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

{{tag
|name = 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.
}}

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

====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
|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. If this tag is not present, then any AttachUnit and DropUnit call in the animation script will be ignored (See [[Animation-LuaCallouts#Other]])}}

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

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

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

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

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

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

{{tag
|name = releaseHeld[[elmo]]s 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===
For a deeper explanation of these tags, see [[Unit_Categories]].
{{tag
|name = category
|type = string
|default = ""
|description = The category tag is a string of separate words, each representing a category of units. There is a maximum of 32 categories. The primary purpose of categories is weapon targeting (See [[#weapons]]).}}

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

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

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

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

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

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

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

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

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

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

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

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

===Collision Volumes===
For a deeper explanation of these tags, see [[Unit_collision_volumes | Unit Collision Volumes]].
{{tag
|name = modelCenterOffset
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = <span class="warning">Removed in 89.0 (Now set via lua)</span>
|description = How far from the model's defined centre should the centre of the unit be?}}

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

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

{{tag
|name = collisionVolumeScales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|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}
|description = The offset from the unit centre to the hit volume centre in each axis.}}

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

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

===Attack Behaviours===
{{tag
|name = highTrajectory
|type = int
|default = 0
|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
|description = Does the unit attack its target by blowing itself up?}}

{{tag
|name = kamikazeDistance
|type = float
|default = 0.0
|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
|description = The length in seconds taken between issuing self destruct order and the unit exploding.}}

{{tag
|name = damageModifier
|type = float
|default = 1.0
|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
|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
|description = How many of this unit type may a player control at once? Defaults to being the maximum amount of units controllable. Is overridden by lobby unit restrictions.}}

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

==Sub Tables==

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

The following additional tags are associated with this subtable:

{{tag
|name = name
|type = string
|default = ""
|description = The <code>weaponName</code> of the weapon (See [[Units-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 [[Units:WeaponMainDir]]).}}

{{tag
|name = maxAngleDif
|type = float
|default = 180.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 [[Units: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==
[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/units 'Balanced Annihilation' UnitDefs]

[http://trac.caspring.org/browser/trunk/mods/ca/units 'Complete Annihilation' UnitDefs]

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Funits 'Conflict Terra' UnitDefs]

[https://code.google.com/p/evolutionrts/source/browse/#svn%2Ftrunk%2Fevolutiondev.sdd%2FUnits 'Evolution RTS' UnitDefs]

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FUnits 'Spring Tutorial Game' UnitDefs]

[http://code.google.com/p/zero-k/source/browse/trunk#trunk%2Fmods%2Fzk%2Funits 'ZeroK' UnitDefs]

[[Category: Units]]

Lua SyncedRead

2012-08-02T17:33:22Z

Pepeampere: /* Player,Team,Ally Lists/Info */ enhancing enhanced description

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''Spring.ENEMY_UNITS'''

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

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

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

=== Rules ===
<span class=note>Those functions allow to save data per Game,Team and Unit.<br>The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)</span><br><br>
'''Spring.GetRulesInfoMap''' <span class=warning>REMOVED in 0.82!</span>
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

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

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

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

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

! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition:<br><br>
<font color="#55ee99">"if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end"</font><br>
not only:<br>
<span class="warning">"if (Spring.GetModOptions.exampleOption) then...end"</span>

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

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

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

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

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }
<font color="#55ee99">
plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0
</font>

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

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

'''Spring.GetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitMetalExtraction''' <span class="note">0.82+ and later</span>
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' {{new|85.0}}
( number unitID ) -> nil | boolean blocking, boolean crushable
'''Spring.GetUnitPosition'''
( number unitID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
<span class="note">since 89.0, returns the base (default), middle or aim position of the unit.</span>

'''Spring.GetUnitBasePosition''' <span class="warning">Deprecated in 89.0, use GetUnitPosition</span>
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
<span class="note">returns the direction vector</span>

'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
<span class="note">returns heading directions used in COB scripts</span>

'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' <font color="#55ee99">returns what unit a constructor/factory is currently building</font>
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
<font color="#55ee99">possible types are:<br>airLos, radar, sonar, seismic, radarJammer & sonarJammer</font>
'''Spring.GetUnitLosState''' <font color="red">raw is only available in gadgets</font>
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' <font color="#55ee99">(returns the distance of 2 units)</font>
( number unitID1, number unitID2 [, 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.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
<span class=note>`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"</span>
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' <span class="note">new in version 0.80+</span>
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
<font color="#55ee99">Returns piece position in unit space</font>

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
<font color="red">Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)</font>

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

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

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
<font color="#55ee99">Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.</font>

=== CommandQueues ===

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

'''Spring.GetCommandQueue''' <font color="#55ee99">(same as Spring.GetUnitCommands)</font>
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' <font color="#55ee99">(cleans the buildqueue of things the unit can't build itself)</font>
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | 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 )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
<span class="note">since 89.0, returns the base (default), middle or aim position of the feature.</span>

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

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

== Ground ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>

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

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

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

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove

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

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

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

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' <font color="red">//NOT FINISHED YET</font>
( 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2012-08-02T17:22:46Z

Pepeampere: /* Player,Team,Ally Lists/Info */ enhanced description

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''Spring.ENEMY_UNITS'''

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

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

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

=== Rules ===
<span class=note>Those functions allow to save data per Game,Team and Unit.<br>The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)</span><br><br>
'''Spring.GetRulesInfoMap''' <span class=warning>REMOVED in 0.82!</span>
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

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

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

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

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

! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition:<br><br>
<font color="#55ee99">"if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end"</font><br>
not only:<br>
<span class="warning">"if (Spring.GetModOptions.exampleOption) then...end"</span>

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>",

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

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

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }
<font color="#55ee99">
plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0
</font>

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

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

'''Spring.GetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitMetalExtraction''' <span class="note">0.82+ and later</span>
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' {{new|85.0}}
( number unitID ) -> nil | boolean blocking, boolean crushable
'''Spring.GetUnitPosition'''
( number unitID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
<span class="note">since 89.0, returns the base (default), middle or aim position of the unit.</span>

'''Spring.GetUnitBasePosition''' <span class="warning">Deprecated in 89.0, use GetUnitPosition</span>
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
<span class="note">returns the direction vector</span>

'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
<span class="note">returns heading directions used in COB scripts</span>

'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' <font color="#55ee99">returns what unit a constructor/factory is currently building</font>
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
<font color="#55ee99">possible types are:<br>airLos, radar, sonar, seismic, radarJammer & sonarJammer</font>
'''Spring.GetUnitLosState''' <font color="red">raw is only available in gadgets</font>
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' <font color="#55ee99">(returns the distance of 2 units)</font>
( number unitID1, number unitID2 [, 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.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
<span class=note>`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"</span>
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' <span class="note">new in version 0.80+</span>
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
<font color="#55ee99">Returns piece position in unit space</font>

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
<font color="red">Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)</font>

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

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

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
<font color="#55ee99">Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.</font>

=== CommandQueues ===

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

'''Spring.GetCommandQueue''' <font color="#55ee99">(same as Spring.GetUnitCommands)</font>
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' <font color="#55ee99">(cleans the buildqueue of things the unit can't build itself)</font>
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | 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 )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID, [, boolean midPos [, boolean aimPos ] ] ) ->
nil |
number bpx, number bpy, number bpz [,
number mpx, number mpy, number mpz [,
number apx, number apy, number apz ]]
<span class="note">since 89.0, returns the base (default), middle or aim position of the feature.</span>

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

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

== Ground ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>

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

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

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

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove

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

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

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

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' <font color="red">//NOT FINISHED YET</font>
( 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2012-06-24T19:34:42Z

Pepeampere: /* Mod-/Map-Options */

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''Spring.ENEMY_UNITS'''

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

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

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

=== Rules ===
<span class=note>Those functions allow to save data per Game,Team and Unit.<br>The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)</span><br><br>
'''Spring.GetRulesInfoMap''' <span class=warning>REMOVED in 0.82!</span>
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

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

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

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

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

! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition:<br><br>
<font color="#55ee99">"if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end"</font><br>
not only:<br>
<span class="warning">"if (Spring.GetModOptions.exampleOption) then...end"</span>

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

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

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

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }
<font color="#55ee99">
plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0
</font>

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

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

'''Spring.GetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitMetalExtraction''' <span class="note">0.82+ and later</span>
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' <span class="warning">new in version 85.0</span>
( number unitID ) -> nil | boolean blocking, boolean crushable
'''Spring.GetUnitPosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the center position of the unit (midpos).</font>

'''Spring.GetUnitBasePosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' <font color="#55ee99">returns what unit a constructor/factory is currently building</font>
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
<font color="#55ee99">possible types are:<br>airLos, radar, sonar, seismic, radarJammer & sonarJammer</font>
'''Spring.GetUnitLosState''' <font color="red">raw is only available in gadgets</font>
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' <font color="#55ee99">(returns the distance of 2 units)</font>
( number unitID1, number unitID2 [, 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.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
<span class=note>`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"</span>
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' <span class="note">new in version 0.80+</span>
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
<font color="#55ee99">Returns piece position in unit space</font>

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
<font color="red">Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)</font>

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

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

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
<font color="#55ee99">Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.</font>

=== CommandQueues ===

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

'''Spring.GetCommandQueue''' <font color="#55ee99">(same as Spring.GetUnitCommands)</font>
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' <font color="#55ee99">(cleans the buildqueue of things the unit can't build itself)</font>
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | 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 )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID ) -> nil | number x, number y, number z
'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

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

== Ground ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>

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

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

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

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove

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

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

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

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' <font color="red">//NOT FINISHED YET</font>
( 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2012-06-24T19:09:51Z

Pepeampere: Undo revision 24742 by Pepeampere (talk)

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''Spring.ENEMY_UNITS'''

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

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

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

=== Rules ===
<span class=note>Those functions allow to save data per Game,Team and Unit.<br>The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)</span><br><br>
'''Spring.GetRulesInfoMap''' <span class=warning>REMOVED in 0.82!</span>
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

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

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

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

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

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

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

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

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }
<font color="#55ee99">
plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0
</font>

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

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

'''Spring.GetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitMetalExtraction''' <span class="note">0.82+ and later</span>
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' <span class="warning">new in version 85.0</span>
( number unitID ) -> nil | boolean blocking, boolean crushable
'''Spring.GetUnitPosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the center position of the unit (midpos).</font>

'''Spring.GetUnitBasePosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' <font color="#55ee99">returns what unit a constructor/factory is currently building</font>
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
<font color="#55ee99">possible types are:<br>airLos, radar, sonar, seismic, radarJammer & sonarJammer</font>
'''Spring.GetUnitLosState''' <font color="red">raw is only available in gadgets</font>
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' <font color="#55ee99">(returns the distance of 2 units)</font>
( number unitID1, number unitID2 [, 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.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
<span class=note>`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"</span>
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' <span class="note">new in version 0.80+</span>
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
<font color="#55ee99">Returns piece position in unit space</font>

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
<font color="red">Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)</font>

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

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

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
<font color="#55ee99">Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.</font>

=== CommandQueues ===

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

'''Spring.GetCommandQueue''' <font color="#55ee99">(same as Spring.GetUnitCommands)</font>
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' <font color="#55ee99">(cleans the buildqueue of things the unit can't build itself)</font>
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | 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 )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID ) -> nil | number x, number y, number z
'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

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

== Ground ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>

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

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

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

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove

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

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

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

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' <font color="red">//NOT FINISHED YET</font>
( 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2012-06-24T19:02:59Z

Pepeampere: /* Mod-/Map-Options */

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''Spring.ENEMY_UNITS'''

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

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

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

=== Rules ===
<span class=note>Those functions allow to save data per Game,Team and Unit.<br>The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)</span><br><br>
'''Spring.GetRulesInfoMap''' <span class=warning>REMOVED in 0.82!</span>
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

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

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

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

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

! bool values are not transfered from C to Lua correctly, so in IF theres needed to use this condition:<br><br>
<font color="#55ee99">"if (Spring.GetModOptions.exampleOption == true) then...end"</font><br>
not only:<br>
<span class="warning">"if (Spring.GetModOptions.exampleOption) then...end"</span>

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

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

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

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }
<font color="#55ee99">
plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0
</font>

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

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

'''Spring.GetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitMetalExtraction''' <span class="note">0.82+ and later</span>
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' <span class="warning">new in version 85.0</span>
( number unitID ) -> nil | boolean blocking, boolean crushable
'''Spring.GetUnitPosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the center position of the unit (midpos).</font>

'''Spring.GetUnitBasePosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' <font color="#55ee99">returns what unit a constructor/factory is currently building</font>
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
<font color="#55ee99">possible types are:<br>airLos, radar, sonar, seismic, radarJammer & sonarJammer</font>
'''Spring.GetUnitLosState''' <font color="red">raw is only available in gadgets</font>
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' <font color="#55ee99">(returns the distance of 2 units)</font>
( number unitID1, number unitID2 [, 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.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
<span class=note>`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"</span>
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' <span class="note">new in version 0.80+</span>
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
<font color="#55ee99">Returns piece position in unit space</font>

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
<font color="red">Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)</font>

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

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

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
<font color="#55ee99">Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.</font>

=== CommandQueues ===

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

'''Spring.GetCommandQueue''' <font color="#55ee99">(same as Spring.GetUnitCommands)</font>
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' <font color="#55ee99">(cleans the buildqueue of things the unit can't build itself)</font>
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | 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 )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID ) -> nil | number x, number y, number z
'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

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

== Ground ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>

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

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

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

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove

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

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

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

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' <font color="red">//NOT FINISHED YET</font>
( 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedRead

2012-06-04T13:09:43Z

Pepeampere: Spring.TestBuildOrder description repaired

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

== Game ==

=== Special TeamID Variables ===
<font color="red" style="font-weight:600">(those special TeamIDs are not supported by all functions)</font><br>
'''Spring.ALL_UNITS'''<br>
'''Spring.MY_UNITS'''<br>
'''Spring.ALLY_UNITS'''<br>
'''Spring.ENEMY_UNITS'''

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

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

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

=== Rules ===
<span class=note>Those functions allow to save data per Game,Team and Unit.<br>The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!)</span><br><br>
'''Spring.GetRulesInfoMap''' <span class=warning>REMOVED in 0.82!</span>
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

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

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

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

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

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

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

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

'''Spring.GetUnitsInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInBox'''
( number xmin, number ymin, number zmin,
number xmax, number ymax, number zmax [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInSphere'''
( number x, number y, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInCylinder'''
( number x, number z, number radius [,number teamID] )
-> nil | unitTable = { [1] = number unitID, etc... }
'''Spring.GetUnitsInPlanes'''
( planes = { [1] = { number nx, number ny, number nz, number d }, etc... } )
-> nil | unitTable = { [1] = number unitID, etc... }
<font color="#55ee99">
plane normals point towards accepted space,
so the acceptance criteria for each plane is:
radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0
</font>

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

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

'''Spring.GetUnitArmored''' <span class="warning">armorMultiple new in version 0.83.x</span>
( number unitID ) -> nil | boolean armored, number armorMultiple
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitMetalExtraction''' <span class="note">0.82+ and later</span>
( number unitID ) -> nil | number
'''Spring.GetUnitExperience'''
( number unitID ) -> nil | number experience
'''Spring.GetUnitStates'''
( number unitID ) -> nil | {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
}
'''Spring.GetUnitIsActive'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsCloaked'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitSelfDTime'''
( number unitID ) -> nil | number
'''Spring.GetUnitStockpile'''
( number unitID ) -> nil | number numStockpiled, number numStockpileQued,
number buildPercent
'''Spring.GetUnitHeight'''
( number unitID ) -> nil | number
'''Spring.GetUnitRadius'''
( number unitID ) -> nil | number
'''Spring.GetUnitBlocking''' <span class="warning">new in version 85.0</span>
( number unitID ) -> nil | boolean blocking, boolean crushable
'''Spring.GetUnitPosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the center position of the unit (midpos).</font>

'''Spring.GetUnitBasePosition'''
( number unitID ) -> nil | number x, number y, number z
<font color="#55ee99">returns the bottom of the unit.</font>

'''Spring.GetUnitDirection'''
( number unitID ) -> nil | number dx, number dy, number dz
'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' <font color="#55ee99">returns what unit a constructor/factory is currently building</font>
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
<font color="#55ee99">possible types are:<br>airLos, radar, sonar, seismic, radarJammer & sonarJammer</font>
'''Spring.GetUnitLosState''' <font color="red">raw is only available in gadgets</font>
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' <font color="#55ee99">(returns the distance of 2 units)</font>
( number unitID1, number unitID2 [, 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.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
<span class=note>`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"</span>
'''Spring.GetUnitLastAttacker'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitLastAttackedPiece''''
( number unitID ) -> nil | string pieceName, number gameframe
'''Spring.GetUnitMoveTypeData''' <span class="note">new in version 0.80+</span>
( number unitID ) -> nil | { movetype data }
'''Spring.GetUnitCollisionVolumeData'''
( number unitID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled
'''Spring.GetUnitPieceCollisionVolumeData'''
( number unitID, number pieceID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
<font color="#55ee99">Returns piece position in unit space</font>

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
<font color="red">Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)</font>

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

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

'''Spring.GetUnitScriptNames'''
( number unitID )
-> { "cobpiecename1" = ScriptPieceNum1, ... , "cobpiecenameN" = ScriptPieceNumN }
'''Spring.GetUnitPiecePosDir'''
( number unitID, number pieceNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirZ, number dirY
<font color="#55ee99">Returns piece position and direction in world space. The direction (dirX, dirY, dirZ) is not necessarily normalized. The position is defined as the position of the first vertex of the piece and it defines direction as the direction in which the line from the first vertex to the second vertex points.</font>

=== CommandQueues ===

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

'''Spring.GetCommandQueue''' <font color="#55ee99">(same as Spring.GetUnitCommands)</font>
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFullBuildQueue'''
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetRealBuildQueue''' <font color="#55ee99">(cleans the buildqueue of things the unit can't build itself)</font>
( number unitID ) ->
nil | buildOrders = {
[1] = { [number unitDefID] = number count }, etc...
}
'''Spring.GetFactoryCommands'''
( number unitID [, number count] ) -> nil | 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 )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInSphere'''
( number x, number y, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetFeaturesInCylinder'''
( number x, number z, number radius )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID ) -> nil | number x, number y, number z
'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing
'''Spring.GetFeatureCollisionVolumeData'''
( number featureID )
-> number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number volumeType, number testType, number primaryAxis, boolean disabled

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

== Ground ==
=== Ground Informations ===
<font color="#55ee99">Elevation is y. Water level is always at y=0. Ground height can be changed during play (terraform or deformation).</font>

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

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

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

'''Spring.GetMetalAmount'''
( number x, number z ) -> number metalAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

'''Spring.GetMetalExtraction'''
( number x, number z ) -> number extractionAmount
<span class="note">where x & z are in metal map coordinates (worldspace/16)</span>

=== Test Orders ===
'''Spring.TestMoveOrder'''
( number unitDefID, number x, number y, number z) -> boolean validMove

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

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

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

=== LOS ===
'''Spring.IsPosInLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInRadar'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.IsPosInAirLos'''
( number x, number y, number z, number allyID ) -> boolean
'''Spring.GetPositionLosState'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' <font color="red">//NOT FINISHED YET</font>
( 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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]