Spring - User contributions [en]

Lua:Callins

2022-10-12T14:10:04Z

Beherith: /* Drawing */ newline

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

'''Attention:''' some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace. This document will be continuously updated to properly alert about those situations.

== 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. A list of key codes can be seen at the [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{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 (including when the game is paused) and at least once per sim frame except when catching up. The parameter is the time since the last update.
}}

=== Draw* Functions ===
Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.
 
Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

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

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

{{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
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

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

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{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, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== 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. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== 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 = UnitHarvestStorageFull
|args = unitID, unitDefID, unitTeam
|info = Called when a unit's harvestStorage is full (according to its unitDef's entry).
}}

{{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]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{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. Its called after the unit is in LOS, so you can query that unit. The allyTeam is who's LOS the unit entered.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam. For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.
}}

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

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam. Also called when a unit leaves LOS without any radar coverage. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.
}}

{{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 changes its build percentage, the boolean return value determines whether or not the change is permitted. Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and ressurect they are positive. Part is the percentage the feature be built or reclaimed per frame. Eg. for a 30 workertime builder, that's a build power of 1 per frame. For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically.
}}

{{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 = playerID, teamID, readyState, clampedX, clampedY, clampedZ, 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.
NB: The order of the parameters changed with the addition of {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

{{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". {{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]] or [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaUIMsg]].
}}

{{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
|I recommend looking up the CallIns in Sourcecode, because the Lua-Documentation, generated from the lua handle of them is seriously flawed and not regenerated.
|Lua-Handler documented from version
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynced.h#L106
|Actual CallIn:
|args = proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|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. The start and hit position arguments are provided from 104.0 onwards.
}}

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

Lua SyncedCtrl

2022-09-17T14:15:58Z

Beherith: /* Unit Control */

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

= Game End =

{{LuaCallout
|prefix = Spring.
|name = KillTeam
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Will declare a team to be dead ( no further orders can be assigned to such teams's units ), Gaia team cannot be killed.
}}

{{LuaCallout
|prefix = Spring.
|name = GameOver
|arg1 = {{type|number}} allyTeamID1
|arg2 = {{type|number}} allyTeamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed.
}}

= RulesParams =
String values are new since 95.0. Attention: Numeric paramValues in quotes will be converted to number.

{{LuaCallout
|prefix = Spring.
|name = SetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible keys for the losAccess table are:
`private` : only readable by the ally (default)
`allied` : readable by ally + ingame allied
`inlos` : readable if the unit is in LOS
`inradar` : readable if the unit is in AirLOS
`public` : readable by all
note: if one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it can read params with `inradar=true` even if the param has `inlos=false`)
note2: all GameRulesParam are public, TeamRulesParams can just be `private`,`allied` and/or `public`
note3: You can read RulesParams from '''any''' Lua enviroments! With those losAccess policies you can limit their access.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = New since 102.0. See above for further documentation of losAccess.
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} paramName
|arg3 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg4 = {{type|table}} losAccess {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}

{{LuaCallout
|prefix = Spring.
|name = SetGameRulesParam
|arg1 = {{type|string}} paramName
|arg2 = {{type|number{{pipe}}string}} paramValue {{bracket}}
|arg3 = {{type|table}} losAccess {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for further documentation of losAccess.
}}

= Resources =

{{LuaCallout
|prefix = Spring.
|name = AddTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Adds metal or energy resources to the specified team.
}}

{{LuaCallout
|prefix = Spring.
|name = UseTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount {{pipe}} { metal = {{type|number}} amount, energy = {{type|number}} amount }
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} hadEnough
|info = Consumes metal and/or energy resources of the specified team.
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamResource
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible values for res are: "m" = metal "e" = energy "ms" = metal storage "es" = energy storage 
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamShareLevel
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible.
}}

{{LuaCallout
|prefix = Spring.
|name = ShareTeamResource
|arg1 = {{type|number}} teamID_src
|arg2 = {{type|number}} teamID_recv
|arg3 = {{type|string}} "metal" {{pipe}} "energy"
|arg4 = {{type|number}} amount
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Transfers resources between two teams.
}}

= Teams =

{{LuaCallout
|prefix = Spring.
|name = SetAlly
|arg1 = {{type|number}} firstAllyTeamID
|arg2 = {{type|number}} secondAllyTeamID
|arg3 = {{type|bool}} ally
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}} Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.
}}

{{LuaCallout
|prefix = Spring.
|name = AssignPlayerToTeam
|arg1 = {{type|number}} playerID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}} Assigns a player to a team.
}}

{{LuaCallout
|prefix = Spring.
|name = SetGlobalLos
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|bool}} globallos
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Changes access to global line of sight for a team and its allies.
}}

= Unit Handling =

{{LuaCallout
|prefix = Spring.
|name = CreateUnit
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number }} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|string}} "facing" {{pipe}} {{type|number }} facing
|arg6 = {{type|number}} teamID {{bracket}}
|arg7 = {{type|bool}} build = false {{bracket}}
|arg8 = {{type|bool}} flattenGround = true {{bracket}}
|arg9 = {{type|number}} builderID {{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|number}} unitID {{pipe}} {{type|nil}} (meaning unit was not created)
|info = Offmap positions are clamped! Use MoveCtrl to move to such positions. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 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.
}}

{{LuaCallout
|prefix = Spring.
|name = DestroyUnit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} selfd = false {{bracket}}
|arg3 = {{type|bool}} reclaimed = false {{bracket}}
|arg4 = {{type|number}} attackerID {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = selfd := Makes the unit act like it self-destructed. reclaimed := Don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
}}

{{LuaCallout
|prefix = Spring.
|name = TransferUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} newTeamID {{bracket}}
|arg3 = {{type|bool}} given = true {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If given=false, the unit is captured.
}}

== Unit Control ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitCosts
|arg1 = {{type|number}} unitID
|arg2 = { {{bracket}} buildTime = {{type|number}} amount {{rbracket}}
|arg3 = {{bracket}} metalCost = {{type|number}} amount {{rbracket}}
|arg4 = {{bracket}} energyCost = {{type|number}} amount {{rbracket}} }
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "tooltip"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} health {{pipe}} { {{bracket}} health = {{type|number}} health {{rbracket}}
|arg3 = {{bracket}} capture = {{type|number}} capture {{rbracket}}
|arg4 = {{bracket}} paralyze = {{type|number}} paralyze {{rbracket}}
|arg5 = {{bracket}} build = {{type|number}} build {{rbracket}} }
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxHealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxHealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitDamage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} damage {{bracket}}
|arg3 = {{type|number}} paralyze = 0 {{bracket}}
|arg4 = {{type|number}} attackerID = -1 {{bracket}}
|arg5 = {{type|number}} weaponID = -1 {{bracket}}
|arg6 = {{type|number}} impulse_x {{bracket}}
|arg7 = {{type|number}} impulse_y {{bracket}}
|arg8 = {{type|number}} impulse_z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = The number in the paralyze parameter equals to the paralyzetime in the WeaponDef.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitStockpile
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} stockpile {{bracket}}
|arg3 = {{type|number}} buildPercent {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} experience
|arg3 = {{type|number}} buildPercent
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} fuel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCrashing
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} crashing
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} teamID {{bracket}}
|arg3 = {{type|bool}} isRoot {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} neutral
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x {{pipe}} {{type|nil}}
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|bool}} dgun = false {{bracket}}
|arg6 = {{type|bool}} userTarget = false {{bracket}}
|arg7 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} enemyUnitID {{pipe}} {{type|nil}} {{bracket}}
|arg3 = {{type|bool}} dgun = false {{bracket}}
|arg4 = {{type|bool}} userTarget = false {{bracket}}
|arg5 = {{type|number}} weaponNum = -1 {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Defines a unit's target. Nil as 2nd argument drops the unit's current target. UserTarget & success new in version 95.0, setting nil target new in version 99.0, weaponNum new in version 102.0.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} maxRange
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMass
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} isblocking
|arg3 = {{type|bool}} isSolidObjectCollidable
|arg4 = {{type|bool}} isProjectileCollidable
|arg5 = {{type|bool}} isRaySegmentCollidable
|arg6 = {{type|bool}} crushable
|arg7 = {{type|bool}} blockEnemyPushing
|arg8 = {{type|bool}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}} Changed parameters.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} depth {{bracket}}
|arg3 = {{type|number}} range {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Parameter "depth" corresponds to metal extraction rate. Range value is similar to "extractsMetal" in unitDefs.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitBuildSpeed
|arg1 = {{type|number}} builderID
|arg2 = {{type|number}} buildSpeed {{bracket}}
|arg3 = {{type|number}} repairSpeed {{bracket}}
|arg4 = {{type|number}} reclaimSpeed{{bracket}}
|arg5 = {{type|number}} resurrectSpeed {{bracket}}
|arg6 = {{type|number}} captureSpeed {{bracket}}
|arg7 = {{type|number}} terraformSpeed {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNanoPieces
|arg1 = {{type|number}} builderID
|arg2 = {{type|table}} pieces
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|92.0}} This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end Use it!
}}

{{LuaCallout
|prefix = Spring.
|name = UnitAttach
|arg1 = {{type|number}} transporterID
|arg2 = {{type|number}} passengerID
|arg3 = {{type|number}} pieceNum
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitDetach
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitDetachFromAir
|arg1 = {{type|number}} passengerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLoadingTransport
|arg1 = {{type|number}} passengerID
|arg2 = {{type|number}} transportID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Disables collisions between the two units to allow colvol intersection during the approach.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceParent
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} AlteredPiece
|arg3 = {{type|number}} ParentPiece
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Changes the pieces hierarchy of a unit by attaching a piece to a new parent.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 = {{type|table }} matrix
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Sets the local (i.e. parent-relative) matrix of the given piece if any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed (matrix should be an array of 16 floats, but is not otherwise sanity-checked).
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} armored {{bracket}}
|arg3 = {{type|number}} armorMultiple {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = armorMultiple new in version 0.83.x
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{bracket}}
|arg3 = {{type|bool}} enabled {{bracket}}
|arg4 = {{type|number}} power {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode"
|arg3 = {{type|number }} mode
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "moveFactor"
|arg3 = {{type|number }} factor
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "minDamage"
|arg3 = {{type|number }} minDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "maxDamage"
|arg3 = {{type|number }} maxDamage
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 = {{type|number }} x
|arg4 = {{type|number }} y
|arg5 = {{type|number }} z
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table }} states
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string }} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
Format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,] (*)
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["salvoLeft" = number value,]
["nextSalvo" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}
(*) if you change the range of a weapon with dynamic damage
make sure you use SetUnitWeaponDamages to change dynDamageRange as well.


{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
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)
}


{{LuaCallout
|prefix = Spring.
|name = SetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
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
};


{{LuaCallout
|prefix = Spring.
|name = SetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ {{bracket}}
|arg6 = {{type|number}} volumeType {{bracket}}
|arg7 = {{type|number}} primaryAxis {{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} travel {{bracket}}
|arg3 = {{type|number}} travelPeriod {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMoveGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{bracket}}
|arg4 = {{type|number}} moveSpeed {{bracket}}
|arg5 = {{type|bool}} moveRaw {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used by default commands to get in build-, attackrange etc. {{new|98.0}} moveRaw: [http://springrts.com/mantis/view.php?id=4412 allow unit to dumbly move to a coordinate without calculating path.]
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLandGoal
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} goalX, {{type|number}} goalY, {{type|number}} goalZ {{bracket}}
|arg3 = {{type|number}} goalRadius {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Used in conjunction with {{name|Spring.UnitAttach}} et al. to re-implement old airbase & fuel system in Lua.
}}

{{LuaCallout
|prefix = Spring.
|name = ClearUnitGoal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|102.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Drag new in version 95.0
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|bool}} alwaysAboveSea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|90.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} velX
|arg3 = {{type|number}} velY
|arg4 = {{type|number}} velZ
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} yaw
|arg3 = {{type|number}} pitch
|arg4 = {{type|number}} roll
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitImpulse
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} decayRate {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitSeismicPing
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pingSize
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveBuildingDecal
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitMidAndAimPos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}} 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 (false) or unit (true) coordinates? Also, note that apy is inverted!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitRadiusAndHeight
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = UnitWeaponFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UnitWeaponHoldFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit LOS ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitCloak
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} cloaked {{pipe}} {{type|number}} scriptCloak {{bracket}}
|arg3 = {{type|bool}} decloakAbs {{pipe}} {{type|number}} decloakDistance {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSonarStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} sonarStealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitStealth
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} stealth
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitAlwaysVisible
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLosMask
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = The 3rd argument is either the bit-and combination of the following numbers: LOS_INLOS = 1 LOS_INRADAR = 2 LOS_PREVLOS = 4 LOS_CONTRADAR = 8 or a table of the following form: losTypes = { [los = boolean,] [radar = boolean,] [prevLos = boolean,] [contRadar = boolean] }
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitLosState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyTeam
|arg3 = {{type|number}} los {{pipe}} {{type|table }} losTypes
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = See above for more info on the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} type
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newRadius
|info = Type can be: "los", "airLos", "radar", "sonar", "seismic", "radarJammer", "sonarJammer"
}}

{{LuaCallout
|prefix = Spring.
|name = SetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 = {{type|number }} allyteamErrorSize {{bracket}}
|arg3 = {{type|number}} baseErrorSize {{bracket}}
|arg4 = {{type|number}} baseErrorMult {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z,
|arg3 = {{type|number}} posErrorDelta.x, {{type|number}} number posErrorDelta.y, {{type|number}} posErrorDelta.z {{bracket}}
|arg4 = {{type|number}} nextPosErrorUpdate {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

== Unit Resourcing ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} res
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetUnitResourcing
|arg1 = {{type|number}} unitID
|arg2 = { res = {{type|number}} amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Possible values for res are: "[u{{pipe}}c][u{{pipe}}m][m{{pipe}}e]" unconditional {{pipe}} conditional use {{pipe}} make metal {{pipe}} energy
}}

{{LuaCallout
|prefix = Spring.
|name = AddUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = {{type|string }} "m" {{pipe}} "e"
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = UseUnitResource
|arg1 = {{type|number}} unitID
|arg2 = { {{bracket}} "m" {{pipe}} "metal" {{pipe}} "e" {{pipe}} "energy" {{rbracket}} = amount, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} okay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} metal
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|97.0}} See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

= Feature Handling =

{{LuaCallout
|prefix = Spring.
|name = CreateFeature
|arg1 = {{type|string}} "defName" {{pipe}} {{type|number}} featureDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|number}} heading {{bracket}}
|arg4 = {{type|number}} AllyTeamID {{bracket}}
|arg5 = {{type|number}} featureID {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} featureID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = DestroyFeature
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TransferFeature
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Feature Control ==

{{LuaCallout
|prefix = Spring.
|name = SetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} health
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} metal
|arg3 = {{type|number}} energy {{bracket}}
|arg4 = {{type|number}} reclaimTime {{bracket}}
|arg5 = {{type|number}} reclaimLeft {{rbracket}}{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureReclaim
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} reclaimLeft
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} unitDefID {{pipe}} {{type|string}} unitDefName {{bracket}}
|arg3 = {{type|number}} facing {{pipe}} {{type|string}} "facing" {{bracket}}
|arg4 = {{type|number}} progress {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing {{value|-1}}. The level of progress can now be set via the additional 4th param. Possible values for facing are: "south" {{pipe}} "s" {{pipe}} 0 "east" {{pipe}} "e" {{pipe}} 1 "north" {{pipe}} "n" {{pipe}} 2 "west" {{pipe}} "w" {{pipe}} 3
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeaturePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} snapToGround {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureVelocity
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitPhysics
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg3 = {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|arg4 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ
|arg5 = {{type|number}} dragX, {{type|number}} dragY, {{type|number}} dragZ
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMoveCtrl
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} enable {{bracket}}
|arg3 = {{type|number*}} args {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this callout to control feature movement. The number* arguments are parsed as follows and all optional: If enable is true: {{bracket}}, velVector(x,y,z) -- initial velocity for feature {{bracket}}, accVector(x,y,z) -- acceleration added every frame{{rbracket}}{{rbracket}} If enable is false: {{bracket}}, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl {{bracket}}, impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl {{bracket}}, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl{{rbracket}}{{rbracket}}{{rbracket}} As of spring 103.0 it is necessary to unlock feature movement on x,z axis before changing feature physics. For example use "Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)" to unlock all movement prior to making SetFeatureVelocity calls.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureAlwaysVisible
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceIndex
|arg3 = {{type|bool}} enable
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg6 = {{type|number}} Axis
|arg7 = {{type|number}} volumeType {{bracket}}
|arg8 = {{type|number}} primaryAxis {{rbracket}}
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMidAndAimPos
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ
|arg3 = {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{bracket}}
|arg4 = {{type|bool}} relative
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}} Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureRadiusAndHeight
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} radius
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|89.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} mass
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 = {{type|boolean}} isBlocking
|arg3 = {{type|boolean}} isSolidObjectCollidable
|arg4 = {{type|boolean}} isProjectileCollidable
|arg5 = {{type|boolean}} isRaySegmentCollidable
|arg6 = {{type|boolean}} crushable
|arg7 = {{type|boolean}} blockEnemyPushing
|arg8 = {{type|boolean}} blockHeightChanges
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}} Changed parameters.
}}

= Lua to COB =

{{LuaCallout
|prefix = Spring.
|name = CallCOBScript
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} funcID {{pipe}} {{type|string}} funcName
|arg3 = {{type|number}} retArgs
|arg4 = COBArg1
|arg5 = COBArg2
|arg6 = ...
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} returnValue, {{type|number}} retArg1, {{type|number}} retArg2, ...
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBScriptID
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} funcName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} funcID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCOBValue
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} splitData=false {{rbracket}}
|arg3 = {{type|number}} COBValue {{bracket}}
|arg4 = {{type|number}} param1 {{bracket}}
|arg5 = {{type|number}} param2 {{bracket}}
|arg6 = {{type|number}} param3 {{bracket}}
|arg7 = {{type|number}} param4 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|number}} result {{pipe}} {{type|number}} result1, {{type|number}} result2
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead! You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitCOBValue
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} COBValue
|arg3 = {{type|number}} param1 {{bracket}}
|arg4 = {{type|number}} param2 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: Don't use Spring.{{bracket}}Get{{pipe}}Set{{rbracket}}UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead! You can find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]. Also see [[Animation-CobConstants#Custom_Variables|Custom_Variables]].
}}

= Give Order =

Options can also be a bitmask; e.g. 0 instead of an empty table (can avoid performance hit on table creation) 
See [[Lua CMDs]] for relevant constants.

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = unitMap = { {{bracket}}unitID{{rbracket}} = example, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = params = { number, etc...}
|arg4 = options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = unitMap = { {{bracket}}{{type|number}} unitID{{rbracket}} = example, etc... }
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = unitArray = { {{bracket}}1{{rbracket}} = {{type|number}} unitID, etc... }
|arg2 = orderArray = { { {{type|number}} cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

=Ground=
== Grass ==

{{LuaCallout
|prefix = Spring.
|name = AddGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = LevelHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AdjustHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = (heightmap[x][z] += height;)
}}

{{LuaCallout
|prefix = Spring.
|name = RevertHeightMap
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetHeightMapFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =
}}
Example 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>

{{LuaCallout
|prefix = Spring.
|name = AddHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetHeightMapFunc()
}}

{{LuaCallout
|prefix = Spring.
|name = SetHeightMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetHeightMapFunc(). The terraform argument is a scaling factor: 
If =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished.
}}

{{LuaCallout
|prefix = Spring.
|name = LevelSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AdjustSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} height
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RevertSmoothMesh
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1 {{bracket}}
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{rbracket}}
|arg5 = {{type|number}} origFactor
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSmoothMeshFunc
|arg1 = lua_function {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 {{bracket}}
|arg4 = ... {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absTotalHeightMapAmountChanged
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} newHeight
|info = Can only be called in SetSmoothMeshFunc().
}}

{{LuaCallout
|prefix = Spring.
|name = SetSmoothMesh
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} height {{bracket}}
|arg4 = {{type|number}} terraform = 1 {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} absHeightDiff
|info = Can only be called in SetSmoothMeshFunc().
}}

== TerrainTypes ==

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTerrainType
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} newType
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} oldType
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetTerrainTypeData
|arg1 = {{type|number}} typeIndex {{bracket}}
|arg2 = {{type|number}} speedTanks = nil {{bracket}}
|arg3 = {{type|number}} speedKBOts = nil {{bracket}}
|arg4 = {{type|number}} speedHovers = nil {{bracket}}
|arg5 = {{type|number}} speedShips = nil {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSquareBuildingMask
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|103.0}}
}}

See also {{xtaglink|Gamedev:UnitDefs|buildingMask}} unitdef tag.

== MetalAmount ==

{{LuaCallout
|prefix = Spring.
|name = SetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} metalAmount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} x & z coords are in worldspace/16. metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).
}}

= Command Descriptions =
Doesn't work in unsynced code! 

{{LuaCallout
|prefix = Spring.
|name = EditUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdDescID
|arg3 = {{type|table}} cmdArray
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ queueing = boolean ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}</pre>
{{var|queueing}} is {{new|101.0}} and allows custom commands to be non-queueing (handy for state toggles).

{{LuaCallout
|prefix = Spring.
|name = InsertUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 = {{type|table}} cmdArray
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = RemoveUnitCmdDesc
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} cmdDescID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Other =

{{LuaCallout
|prefix = Spring.
|name = SetNoPause
|arg1 = {{type|bool}} noPause
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitToFeature
|arg1 = {{type|bool}} tofeature
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = 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]
}}

{{LuaCallout
|prefix = Spring.
|name = SetExperienceGrade
|arg1 = {{type|number}} expGrade {{bracket}}
|arg2 = {{type|number}} ExpPowerScale {{bracket}}
|arg3 = {{type|number}} ExpHealthScale {{bracket}}
|arg4 = {{type|number}} ExpReloadScale {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = expGrade defines how often UnitExperience() will be called. Prior to 104.0 it is based on the following equation: (int) {{bracket}}exp/(exp+1){{rbracket}} / expGrade Post 104.0 it is the raw change.
}}

{{LuaCallout
|prefix = Spring.
|name = SpawnExplosion
|arg1 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg2 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg3 = {{type|table}} explosionParams
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}
<pre>Possible keys of explosionParams are:
weaponDef = number,
owner = number,
hitUnit = number,
hitFeature = number,
craterAreaOfEffect = number,
damageAreaOfEffect = number,
edgeEffectiveness = number,
explosionSpeed = number,
gfxMod = number,
impactOnly = boolean,
ignoreOwner = boolean,
damageGround = boolean

Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef.
The weapondefID is only used for visuals and for passing into callins like UnitDamaged.</pre>

{{LuaCallout
|prefix = Spring.
|name = SpawnCEG
|arg1 = {{type|string}} "cegname" | {{type|number}} cegID
|arg2 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg3 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg4 = {{type|number}} radius = 0
|arg5 = {{type|number}} damage = 0
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success, {{type|number}} cegID
|info = cegID new in 95.0.
}}

{{LuaCallout
|prefix = Spring.
|name = SpawnSFX
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} sfxID
|arg3 = {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0
|arg4 = {{type|number}} dirX = 0, {{type|number}} dirY = 0, {{type|number}} dirZ = 0
|arg5 = {{type|number}} radius = 0
|arg6 = {{type|number}} damage = 0 {{bracket}}
|arg7 = {{type|bool}} absolute {{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}}
}}

Equal to the [[Animation-LuaCallouts#Effects|UnitScript versions of EmitSFX]], but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.

= Projectiles =

{{LuaCallout
|prefix = Spring.
|name = SpawnProjectile
|arg1 = {{type|number}} weaponDefID
|arg2 = {{type|table}} projectileParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} projectileID
|info =
}}
<pre>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</pre>

{{LuaCallout
|prefix = Spring.
|name = DeleteProjectile
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Silently removes projectiles (no explosion).
}}

Pre 95.0:
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|string}} targetTypeStr {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}

Post 95.0:
{{LuaCallout
|prefix = Spring.
|name = SetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 = {{bracket}} {{type|number}} targetID, {{type|number}} targetType {{rbracket}} {{pipe}} {{bracket}} {{type|number}} posX = 0, {{type|number}} posY = 0, {{type|number}} posZ = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} validTarget
|info =
}}
<pre>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</pre>

{{LuaCallout
|prefix = Spring.
|name = SetProjectileIgnoreTrackingError
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} ignore
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileIsIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileMoveControl
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Disables engine movecontrol, so lua can fully control the physics.
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectilePosition
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} posX = 0 {{bracket}}
|arg3 = {{type|number}} posY = 0 {{bracket}}
|arg4 = {{type|number}} posZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileVelocity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} velX = 0 {{bracket}}
|arg3 = {{type|number}} velY = 0 {{bracket}}
|arg4 = {{type|number}} velZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileCollision
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileGravity
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} grav = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinAngle
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinAngle = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} speed = 0 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileSpinVec
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} spinX = 0 {{bracket}}
|arg3 = {{type|number}} spinY = 0 {{bracket}}
|arg4 = {{type|number}} spinZ = 0 {{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileCEG
|arg1 = {{type|number}} projectileID
|arg2 = {{type|string}} ceg_name
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetPieceProjectileParams
|arg1 = {{type|number}} projectileID {{bracket}}
|arg2 = {{type|number}} explosionFlags {{bracket}}
|arg3 = {{type|number}} spinAngle {{bracket}}
|arg4 = {{type|number}} spinSpeed {{bracket}}
|arg5 = {{type|number}} spinVector.x {{bracket}}
|arg6 = {{type|number}} spinVector.y {{bracket}}
|arg7 = {{type|number}} spinVector.z {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileAlwaysVisible
|arg1 = {{type|number}} projectileID
|arg2 = {{type|bool}} alwaysVisible
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|table}} damages
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} key
|arg4 = {{type|number}} value
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}
<pre>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)
}</pre>

[[category: Lua]]

Lua VFS

2022-08-08T09:53:38Z

Beherith: /* Files */

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

= Overview =

Although Spring can access the filesystem directly (via os module) it is more common that you
would want to access files included with your game or Spring. Trouble is, most of these files are
compressed into archives (.sdz/.sd7) so random access would generally be a difficult procedure.
Fortunately, the Spring Lua system automatically provides access to mod and base files via the VFS module.

The VFS module doesn't simply open archives though. What it does is map your game files, game
dependencies and Spring content onto a virtual file tree. All archives start from the 'roots' of the tree
and share the same virtual space, meaning that if two or more archives contain the same resource
file name the resources overlap and only one of the files will be retrieved. Overlapping directories
on the other hand are merged so the resulting virtual directory contains the contents of both. Here is
an example of how this works:

'''Archive 1 (games/mygame.sd7)'''

textures 
|__ texture1.png 
models 
|__ model1.mdl 

'''Archive 2 (base/springcontent.sdz'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 

'''VFS'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 
models 
|__ model1.mdl 

This raises the question: If both archives have a texture1.png then which texture1.png is retreived
via the VFS? The answer depends on the order the archives are loaded and the VFS mode (more on
modes below). Generally however, each archive loaded overrides any archives loaded
before it. The standard order of loading (from first to last) is:

# The main Spring/ game directory.
# The automatic dependencies springcontent.sdz and maphelper.sdz.
# Dependencies listed in your modinfo.lua (or modinfo.tdf), in the order listed.
# Your mod archive.

= Modes =

These modes are constants passed to VFS.Include() and friends to control the order that archives are
searched for a given file. They are case-sensitive.

'''VFS.RAW''' Only select uncompressed files.

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

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

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

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

'''VFS.ZIP''' Only select compressed files (.sdz,.sd7).

'''VFS.RAW_FIRST''' Try uncompressed files first, then compressed.

'''VFS.ZIP_FIRST''' Try compressed files first, then uncompressed.

'''VFS.RAW_ONLY''' (Deprecated. Same as VFS.RAW)

'''VFS.ZIP_ONLY''' (Deprecated. Same as VFS.ZIP.)

See also: https://github.com/spring/spring/blob/develop/rts/System/FileSystem/VFSModes.h

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

If nil then the env will be _G (global environment) If the optional env argument is provided any non-local variables and functions defined in
filename.lua are then accessable via env or _G. Vise-versa, any variables defined in env prior to
passing to VFS.Include are available to code in the included file. Code running in filename.lua will
see the contents of env in place of the normal _G environment. 

This loads and compiles the lua code from a file in the VFS. The path is relative to the main Spring directory, e.g. VFS.Include('LuaUI/includes/filename.lua', nil, [vfsmode]) 

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

'''VFS.LoadFile'''
( string "filename" [, number mode ] ) -> nil | string data

This is used for loading raw text data, as it will not execute the file, like VFS.Include does, just returns a string of the file contents.

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

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

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

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

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

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

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

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

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

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

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

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

= Archives =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''VFS.PackU8'''

'''VFS.PackU16'''

'''VFS.PackU32'''

'''VFS.PackS8'''

'''VFS.PackS16'''

'''VFS.PackS32'''

'''VFS.PackF32'''

arguments are:

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

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

'''VFS.UnpackU8'''

'''VFS.UnpackU16'''

'''VFS.UnpackU32'''

'''VFS.UnpackS8'''

'''VFS.UnpackS16'''

'''VFS.UnpackS32'''

'''VFS.UnpackF32'''

arguments are:

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

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

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

[[category: Lua]]

Lua:Callins

2022-08-02T20:49:02Z

Beherith: /* 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.

'''Attention:''' some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace. This document will be continuously updated to properly alert about those situations.

== 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. A list of key codes can be seen at the [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{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 (including when the game is paused) and at least once per sim frame except when catching up. The parameter is the time since the last update. }}

=== Draw* Functions ===
Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.
 
Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

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

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

{{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
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

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

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{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, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== 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. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== 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 = UnitHarvestStorageFull
|args = unitID, unitDefID, unitTeam
|info = Called when a unit's harvestStorage is full (according to its unitDef's entry).
}}

{{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]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{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. Its called after the unit is in LOS, so you can query that unit. The allyTeam is who's LOS the unit entered.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam. For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.
}}

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

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam. Also called when a unit leaves LOS without any radar coverage. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.
}}

{{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 changes its build percentage, the boolean return value determines whether or not the change is permitted. Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and ressurect they are positive. Part is the percentage the feature be built or reclaimed per frame. Eg. for a 30 workertime builder, that's a build power of 1 per frame. For a 50 buildtime feature reclaimed by this builder, part will be 100/-50(/1) = -2%, or -0.02 numerically.
}}

{{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 = playerID, teamID, readyState, clampedX, clampedY, clampedZ, 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.
NB: The order of the parameters changed with the addition of {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

{{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". {{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]] or [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaUIMsg]].
}}

{{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
|I recommend looking up the CallIns in Sourcecode, because the Lua-Documentation, generated from the lua handle of them is seriously flawed and not regenerated.
|Lua-Handler documented from version
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynced.h#L106
|Actual CallIn:
|args = proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|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. The start and hit position arguments are provided from 104.0 onwards.
}}

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

Lua MathExtra

2022-08-01T11:42:27Z

Beherith: /* Additional math functions */ move to luacallout format

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

= Additional math functions=

New in Engine Version 0.95 and up.

{{LuaCallout
|prefix = math.
|name = clamp
|arg1 = {{type|number}} x
|arg2 = {{type|number}} min
|arg3 = {{type|number}} max
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} clamped
|info = Returns x clamped to min and max boundaries.
}}

{{LuaCallout
|prefix = math.
|name = diag
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} x2
|arg3 = {{type|number}} x3, ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} diagonal
|info = Returns the length of the diagonal of an n-dimensional box (or the length of an n-component vector). Rather quick method that does not handle intermediate overflows/underflows nor is made for numerical stability.
}}

{{LuaCallout
|prefix = math.
|name = erf
|arg1 = {{type|number}} x
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} erf
|info = Returns [http://en.wikipedia.org/wiki/Error_function erf](x).
}}

{{LuaCallout
|prefix = math.
|name = hypot
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sqrt(x*x+y*y)
|info = Returns the length of hypotenuse of right angle triangle with sides x and y, equivalent to sqrt(x*x + y*y), but has better numerical stability and internally handles intermediate overflows/underflows, but is also slower.
}}

{{LuaCallout
|prefix = math.
|name = mix
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} a
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} (x+(y-x)*a)
|info = Returns linear interpolation between x and y with ratio a (x+(y-x)*a).
}}

{{LuaCallout
|prefix = math.
|name = round
|arg1 = {{type|number}} x
|arg2 = {{type|number}} decimals
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} rounded
|info = Returns x rounded to n decimals, if n is omitted or <=0, rounds to nearest integer. Note that Spring's Lua interpreter uses 32-bit floats for all numbers so max. precision is ~7 decimal digits.
}}

{{LuaCallout
|prefix = math.
|name = sgn
|arg1 = {{type|number}} x
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sign
|info = Returns 0 if x ==0, 1 if x > 0, -1 if x < 0 [http://en.wikipedia.org/wiki/Sign_function sgn](x).
}}

{{LuaCallout
|prefix = math.
|name = smoothstep
|arg1 = {{type|number}} edge0
|arg2 = {{type|number}} edge1
|arg3 = {{type|number}} x
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} smoothstep
|info = Returns [http://en.wikipedia.org/wiki/Smoothstep smoothstep](edge0, edge1, v).
}}

[[category: Lua]]

Lua BitOps

2022-08-01T11:28:59Z

Beherith: /* Bit Operators */ move to luacallout format

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

== Bit Operators ==

{{LuaCallout
|prefix = math.
|name = bit_and
|arg1 = {{type|number}} a1
|arg2 = {{type|number}} a2 , ...
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} i
|info = Returns the bitwise AND of all arguments. Only use up to 24 bit integers.
}}

{{LuaCallout
|prefix = math.
|name = bit_or
|arg1 = {{type|number}} a1
|arg2 = {{type|number}} a2 , ...
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} i
|info = Returns the bitwise OR of all arguments. Only use up to 24 bit integers.
}}

{{LuaCallout
|prefix = math.
|name = bit_xor
|arg1 = {{type|number}} a1
|arg2 = {{type|number}} a2 , ...
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} i
|info = Returns the bitwise XOR of all arguments. Only use up to 24 bit integers.
}}

{{LuaCallout
|prefix = math.
|name = bit_inv
|arg1 = {{type|number}} a1
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} i
|info = Returns the bitwise NOT of the 24 bit integer argument.
}}

{{LuaCallout
|prefix = math.
|name = bit_bits
|arg1 = {{type|number}} a1
|arg2 = {{type|number}} a2 , ...
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} i
|info = Set each of the bits of a 24 bit integer. Returns result = result OR (1 << a1) OR (1 << a2) OR ...;)
}}

-- Note: there are no bit shift. Use those Lua functions instead for 24 bits bitshift
-- 24 bits because only the 24 bits of the mantissa can be easily used in a 32 bit float
-- bitshift functions (<<, >> equivalent)

-- shift left
local function lsh(value,shift)
return (value*(2^shift)) % 2^24
end

-- shift right
local function rsh(value,shift)
return math.floor(value/2^shift) % 2^24
end
[[category: Lua]]

Lua GLSL Api

2022-06-03T11:15:24Z

Beherith:

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

These functions are ONLY available if the graphics adapter supports GLSL. Please test in your scripts if one of them exists before you use them. In headless mode, the gl. callouts are nil.

{{LuaCallout
|prefix = gl.
|name = CreateShader
|arg1 = {{type|table}} shaderParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shaderID
|info = Create a shader from shaderParams table:

({[ vertex = "glsl code" ,]
[ tcs = "glsl code" ,]
[ tes = "glsl code" ,]
[ geometry = "glsl code" ,]
[ fragment = "glsl code" ,]
[ uniform = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformInt = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformFloat = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformMatrix = { uniformName = number value, ...} ,]
[ geoInputType = number inType,]
[ geoOutputType = number outType,]
[ geoOutputVerts = number maxVerts,]
[ definitions = "string of shader #defines", ]
})

* The "Vertex" or vertex-shader is your GLSL-Code as string, its written in a C-Dialect. This shader is busy deforming the geometry of a unit but it can not create new polygons. Use it for waves, wobbling surfaces etc.

* The "Geometry" or Geometry-shader can create new vertices and vertice-stripes from points.

* The "TCS" or Tesselation Control Shader controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the Tessellation primitive generator stage, as well as to feed patch data (as its output values) to the Tessellation Evaluation Shader stage. TCS shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

* The "TES" or Tesselation Evaluation Shader takes the abstract patch generated by the tessellation primitive generation stage, as well as the actual vertex data for the entire patch, and generates a particular vertex from it. Each TES invocation generates a single vertex. It can also take per-patch data provided by the Tessellation Control Shader. TES shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

* The "Fragment" or Fragment-shader (sometimes called pixel-Shader) is post processing the allready rendered picture (for example drawing stars on the sky)- remember textures are not always 2 dimensional pictures. They can contain information about the depth, or the third value marks areas and the strength at which these are processed.

* The Uniforms are the values, you send along with the shader-program. To use them in the shader-program declare them like this:
<syntaxhighlight lang="c">uniform float frame;</syntaxhighlight>

* From 101.0 onwards, the engine will automatically fill in an appropriately named uniform for team colour if it is declared;
<syntaxhighlight lang="c">uniform vec4 teamColor;</syntaxhighlight>
}}

{{LuaCallout
|prefix = gl.
|name = DeleteShader
|arg1 = {{type|number}} shaderID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Deletes a shader identified by shaderID
}}

{{LuaCallout
|prefix = gl.
|name = ActiveShader
|arg1 = {{type|number}} shaderID
|arg2 = {{type|function}} func {{bracket}}
|arg3 = {{type|arg1}} {{bracket}}
|arg4 = {{type|arg2}} ... {{rbracket}} {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Binds a shader program identified by shaderID, and calls the Lua func with the specified arguments. Can be used in NON-drawing events (to update uniforms etc.)!
}}

{{LuaCallout
|prefix = gl.
|name = UseShader
|arg1 = {{type|number}} shaderID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} linked
|info = Binds a shader program identified by shaderID. Pass 0 to disable the shader. Returns wether the shader was successfully bound.
}}

{{LuaCallout
|prefix = gl.
|name = GetShaderLog
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} infoLog
|info = Returns the shader compilation error log. This is empty if the shader linking failed, in that case, check your in/out blocks and ensure they match.
}}

{{LuaCallout
|prefix = gl.
|name = SetGeometryShaderParameter
|arg1 = {{type|number}} shaderID
|arg2 = {{type|number}} param
|arg3 = {{type|number}} number
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Sets the Geometry shader parameters for shaderID. Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri) Was called SetShaderParameter before 104.0.1-596 (maintenance)
}}

{{LuaCallout
|prefix = gl.
|name = SetTesselationShaderParameter
|arg1 = {{type|number}} param
|arg2 = {{type|number}} number
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Sets the tesselation shader parameters for shaderID. Needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri) Introduced in 104.0.1-596 (maintenance)
}}

{{LuaCallout
|prefix = gl.
|name = GetActiveUniforms
|arg1 = {{type|number}} shaderID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} ActiveUniforms = { { name = "name", type = "type", length = number length, size = number size }, ...}
|info = Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, ...).
}}

{{LuaCallout
|prefix = gl.
|name = GetUniformLocation
|arg1 = {{type|number}} shaderID
|arg2 = {{type|string}} "name"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} locationID
|info = Returns the locationID of a shaders uniform. Needed for changing uniform values with gl.Uniform.
}}

{{LuaCallout
|prefix = gl.
|name = Uniform
|arg1 = {{type|number}} locationID
|arg2 = {{type|number }} f1 {{bracket}}
|arg3 = {{type|number }} f2 {{bracket}}
|arg4 = {{type|number }} f3 {{bracket}}
|arg5 = {{type|number }} f4 {{rbracket}} {{rbracket}} {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Sets the uniform float value at the locationID for the currently active shader. Shader must be activated before setting uniforms.
}}

{{LuaCallout
|prefix = gl.
|name = UniformInt
|arg1 = {{type|number}} locationID
|arg2 = {{type|number }} int1 {{bracket}}
|arg3 = {{type|number }} int2 {{bracket}}
|arg4 = {{type|number }} int3 {{bracket}}
|arg5 = {{type|number }} int4 {{rbracket}} {{rbracket}} {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Sets the uniform int value at the locationID for the currently active shader. Shader must be activated before setting uniforms.
}}

{{LuaCallout
|prefix = gl.
|name = UniformArray
|arg1 = {{type|number}} locationID
|arg2 = {{type|number }} type
|arg3 = {{type|table }} uniforms
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Sets the an array of uniform values at the locationID for the currently active shader. Shader must be activated before setting uniforms. Type can be one of {1 = int, 2 = float, 3 = float matrix}. In 104.0 the maximum length of the uniforms table increased from 32 entries to 1024.
}}

{{LuaCallout
|prefix = gl.
|name = UniformMatrix
|arg1 = {{type|number}} locationID
|arg2 = {{type|string}} "shadows" {{pipe}} "camera" {{pipe}} "caminv" {{pipe}} "camprj" {{pipe}} {{type|number}} m1
|arg3 = {{type|number}} m2
|arg4 = {{type|number}} m3
|arg5 = {{type|number}} m4
|arg6 = {{type|number}} m5
|arg7 = {{type|number}} m6
|arg8 = {{type|number}} m7
|arg9 = {{type|number}} m8 ... , m16
|return = {{type|nil}}
|info = Sets the a uniform mat4 locationID for the currently active shader. Shader must be activated before setting uniforms. Can set one one common matrix like shadow, or by passing 16 additional numbers for the matrix.
}}

[[category: Lua]]

Lua GLSL Api

2022-06-03T11:14:39Z

Beherith: finish luacallout

Lua GLSL Api

2022-06-03T09:05:40Z

Beherith: Move some bits to LuaCallout, clarify things

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

These functions are ONLY available if the graphic board supports GLSL. Please test in your scripts if one of them exists before you use them!

'''gl.CreateShader'''
({[ vertex = "glsl code" ,]
[ tcs = "glsl code" ,]
[ tes = "glsl code" ,]
[ geometry = "glsl code" ,]
[ fragment = "glsl code" ,]
[ uniform = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformInt = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformFloat = { uniformName = number value, ...} ,] (specify a Lua array as an argument to uniformName to initialize GLSL arrays)
[ uniformMatrix = { uniformName = number value, ...} ,]
[ geoInputType = number inType,]
[ geoOutputType = number outType,]
[ geoOutputVerts = number maxVerts,]
[ definitions = "string of shader #defines", ]
}) -> number shaderID

* The "Vertex" or vertex-shader is your GLSL-Code as string, its written in a C-Dialect. This shader is busy deforming the geometry of a unit but it can not create new polygons. Use it for waves, wobbling surfaces etc.

* The "Geometry" or Geometry-shader can create new vertices and vertice-stripes from points.

* The "TCS" or Tesselation Control Shader controls how much tessellation a particular patch gets; it also defines the size of a patch, thus allowing it to augment data. It can also filter vertex data taken from the vertex shader. The main purpose of the TCS is to feed the tessellation levels to the Tessellation primitive generator stage, as well as to feed patch data (as its output values) to the Tessellation Evaluation Shader stage. TCS shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

* The "TES" or Tesselation Evaluation Shader takes the abstract patch generated by the tessellation primitive generation stage, as well as the actual vertex data for the entire patch, and generates a particular vertex from it. Each TES invocation generates a single vertex. It can also take per-patch data provided by the Tessellation Control Shader. TES shader can be used with spring version >= 104.0.1-596 (maintenance), it's also available in develop branch of spring.

* The "Fragment" or Fragment-shader (sometimes called pixel-Shader) is post processing the allready rendered picture (for example drawing stars on the sky)- remember textures are not always 2 dimensional pictures. They can contain information about the depth, or the third value marks areas and the strength at which these are processed.

* The Uniforms are the values, you send along with the shader-program. To use them in the shader-program declare them like this:
<syntaxhighlight lang="c">uniform float frame;</syntaxhighlight>

* From 101.0 onwards, the engine will automatically fill in an appropriately named uniform for team colour if it is declared;
<syntaxhighlight lang="c">uniform vec4 teamColor;</syntaxhighlight>

{{LuaCallout
|prefix = gl.
|name = DeleteShader
|arg1 = {{type|number}} shaderID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Deletes a shader identified by shaderID
}}

{{LuaCallout
|prefix = gl.
|name = ActiveShader
|arg1 = {{type|number}} shaderID
|arg2 = {{type|function}} func {{bracket}}
|arg3 = {{type|arg1}} {{bracket}}
|arg4 = {{type|arg2}} ... {{rbracket}} {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Binds a shader program identified by shaderID, and calls the Lua func with the specified arguments. Can be used in NON-drawing events (to update uniforms etc.)!
}}

{{LuaCallout
|prefix = gl.
|name = UseShader
|arg1 = {{type|number}} shaderID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} linked
|info = Binds a shader program identified by shaderID. Pass 0 to disable the shader. Returns wether the shader was successfully bound.
}}

{{LuaCallout
|prefix = gl.
|name = GetShaderLog
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} infoLog
|info = Returns the shader compilation error log. This is empty if the shader linking failed, in that case, check your in/out blocks and ensure they match.
}}

{{LuaCallout
|prefix = gl.
|name = SetGeometryShaderParameter
|arg1 = {{type|number}} shaderID
|arg2 = {{type|number}} param
|arg3 = {{type|number}} number
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Sets the Geometry shader parameters for shaderID. Needed by geometry shader programs (check the opengl GL_ARB_geometry_shader4 extension for glProgramParameteri) Was called SetShaderParameter before 104.0.1-596 (maintenance)
}}

{{LuaCallout
|prefix = gl.
|name = SetTesselationShaderParameter
|arg1 = {{type|number}} param
|arg2 = {{type|number}} number
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Sets the tesselation shader parameters for shaderID. Needed by tesselation shader programs (check the opengl GL_ARB_tessellation_shader extension for glProgramParameteri) Introduced in 104.0.1-596 (maintenance)
}}

{{LuaCallout
|prefix = gl.
|name = GetActiveUniforms
|arg1 = {{type|number}} shaderID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} ActiveUniforms = { { name = "name", type = "type", length = number length, size = number size }, ...}
|info = Query the active (actually used) uniforms of a shader and identify their names, types (float, int, uint) and sizes (float, vec4, ...).
}}

{{LuaCallout
|prefix = gl.
|name = GetUniformLocation
|arg1 = {{type|number}} shaderID
|arg2 = {{type|string}} "name"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} locationID
|info = Returns the locationID of a shaders uniform. Needed for changing uniform values with gl.Uniform.
}}

'''gl.Uniform'''
( number locationID, number f1 [,number f2 [,number f3 [,number f4]]] ) -> nil

'''gl.UniformInt'''
( number locationID, number int1 [,number int2 [,number int3 [,number int4]]] ) -> nil

'''gl.UniformArray''' {{new|95.0}}
( number locationID, number type, table uniforms ) -> nil
type can be one of {1 = int, 2 = float, 3 = float matrix}. In 104.0 the maximum length of the uniforms table increased from 32 entries to 1024.

'''gl.UniformMatrix'''
( number locationID,
"shadow" |
"camera" |
"caminv" |
"camprj" |
number m1, number m2, number m3, number m4 |
number m1, ... , number m9 |
number m1, ... , number m16
) -> nil

[[category: Lua]]

Lua UnsyncedCtrl

2022-06-02T15:22:03Z

Beherith: /* Unit Selection */

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

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

= UI =

{{LuaCallout
|prefix = Spring.
|name = SetLastMessagePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Ingame Console =

{{LuaCallout
|prefix = Spring.
|name = Echo
|arg1 = {{type|arg1}} {{bracket}}
|arg2 = {{type|arg2}} {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Useful for debugging. Prints values in the spring chat console. Hint: the default print() writes to STDOUT.
}}

{{LuaCallout
|prefix = Spring.
|name = Log
|arg1 = {{type|string}} section
|arg2 = {{type|number}} logLevel {{pipe}} {{type|string}} logLevel
|arg3 = {{type|string}} LogMessage1 {{bracket}}
|arg4 = {{type|string}} LogMessage2{{bracket}}
|arg5 = ... {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre>Possible values for logLevel are:
"debug" | LOG.DEBUG
"info" | LOG.INFO
"notice" | LOG.NOTICE (engine default) (new in Version 97)
"warning" | LOG.WARNING
"error" | LOG.ERROR
"fatal" | LOG.FATAL</pre>

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = {{type|string}} command1 {{bracket}}
|arg2 = {{type|string}} command2 {{bracket}}
|arg3 = {{type|...}} {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SendCommands
|arg1 = { {{type|string}} command1, {{type|string}} command2, ... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== GUI ==

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|string}} action {{bracket}}
|arg2 = {{type|string}} actionExtra {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetActiveCommand
|arg1 = {{type|number}} cmdIndex {{bracket}}
|arg2 = {{type|number}} button = 1 {{bracket}}
|arg3 = {{type|bool}} leftClick {{bracket}}
|arg4 = {{type|bool}} rightClick {{bracket}}
|arg5 = {{type|bool}} alt {{bracket}}
|arg6 = {{type|bool}} ctrl {{bracket}}
|arg7 = {{type|bool}} meta {{bracket}}
|arg8 = {{type|bool}} shift {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} commandSet
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCmdColorsConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = LoadCtrlPanelConfig
|arg1 = {{type|string}} config
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = ForceLayoutUpdate
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Disables the "Selected Units x" box in the GUI.
}}

== Mouse ==

{{LuaCallout
|prefix = Spring.
|name = SetMouseCursor
|arg1 = {{type|string}} cursorName {{bracket}}
|arg2 = {{type|number}} scale {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = WarpMouse
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== LOS Colors ==

{{LuaCallout
|prefix = Spring.
|name = SetLosViewColors
|arg1 = {{type|table}} always = {r,g,b}
|arg2 = {{type|table}} LOS = {r,g,b}
|arg3 = {{type|table}} radar = {r,g,b}
|arg4 = {{type|table}} jam = {r,g,b}
|arg5 = {{type|table}} radar2 = {r,g,b}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. New arguments since 100.0 (radar2 is the inside of radar edge). Arguments for 99.0 and before: 
}}
<pre>( table reds = { number always, number LOS, number radar, number jam },
table greens = { number always, number LOS, number radar, number jam },
table blues = { number always, number LOS, number radar, number jam } ) -> nil</pre>

== SendMessage ==

{{LuaCallout
|prefix = Spring.
|name = SendMessage
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToPlayer
|arg1 = {{type|number}} playerID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToTeam
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToAllyTeam
|arg1 = {{type|number}} allyID
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SendMessageToSpectators
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = <PLAYER#> (with # being a playerid) inside the string will be replaced with the players name - i.e. : Spring.SendMessage ("<PLAYER1> did something") might display as "ProRusher did something"
}}

== Markers ==

{{LuaCallout
|prefix = Spring.
|name = MarkerAddPoint
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|string}} text = "" {{bracket}}
|arg5 = {{type|bool}} localOnly {{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerAddLine
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} z1
|arg4 = {{type|number}} x2
|arg5 = {{type|number}} y2
|arg6 = {{type|number}} z2
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = MarkerErasePosition
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= Sounds =

{{LuaCallout
|prefix = Spring.
|name = LoadSoundDef
|arg1 = {{type|string}} soundfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = Loads a SoundDefs file, the format is the same as in `gamedata/sounds.lua`.
}}

{{LuaCallout
|prefix = Spring.
|name = PlaySoundFile
|arg1 = {{type|string}} soundfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|number}} posx {{bracket}}
|arg4 = {{type|number}} posy {{bracket}}
|arg5 = {{type|number}} posz {{bracket}}
|arg6 = {{type|number}} speedx{{bracket}}
|arg7 = {{type|number}} speedy{{bracket}}
|arg8 = {{type|number}} speedz{{bracket}}
|arg9 = {{type|number}} {{pipe}} {{type|string}} channel {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|return = {{type|nil}} {{pipe}} {{type|bool}} playSound
|info = Possible arguments for channel argument:
}}
<pre> "general" || 0 || nil (default)
"battle" || "sfx" | 1
"unitreply" || "voice" || 2
"userinterface" || "ui" || 3</pre>

{{LuaCallout
|prefix = Spring.
|name = PlaySoundStream
|arg1 = {{type|string}} oggfile {{bracket}}
|arg2 = {{type|number}} volume = 1.0 {{bracket}}
|arg3 = {{type|bool}} enqueue {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Allows to play an Ogg Vorbis (.OGG) compressed sound file. In 83.0 and up multiple sound streams may be played at once.
}}

{{LuaCallout
|prefix = Spring.
|name = StopSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Terminates any SoundStream currently running.
}}

{{LuaCallout
|prefix = Spring.
|name = PauseSoundStream
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSoundStreamVolume
|arg1 = {{type|number}} volume
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = SendLuaUIMsg
|arg1 = {{type|string}} message
|arg2 = {{type|string}} mode
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Possible modes are: "s"/"specs" & "a"/"allies"
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaGaiaMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = SendLuaRulesMsg
|arg1 = {{type|string}} message
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= AI =

{{LuaCallout
|prefix = Spring.
|name = SendSkirmishAIMessage
|arg1 = {{type|number}} aiTeam
|arg2 = {{type|string}} message
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} ai_processed, { {{bracket|1}} = {{type|string}} response1, ... }
|info = {{new|83.0}} Note there is nothing in this table due to "limitations" of the AI interface.
}}

= Units =

{{LuaCallout
|prefix = Spring.
|name = SetUnitLeaveTracks
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} leavetracks
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

== Unit Selection ==

{{LuaCallout
|prefix = Spring.
|name = SelectUnitMap
|arg1 = { {{bracket|unitID}} = anything, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SelectUnitArray
|arg1 = { {{bracket|1}} = unitID1, {{bracket|2}} = unitID2, ... } {{bracket}}
|arg2 = {{type|bool}} append {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawSelectionInfo
|arg1 = {{type|bool}} drawSelectionInfo
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit Group ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} groupID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

== Give Order ==

{{LuaCallout
|prefix = Spring.
|name = GiveOrder
|arg1 = {{type|number}} cmdID
|arg2 = {{type|table}} params = {number, etc...}
|arg3 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. Gives order to all selected units.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|1}} = {{type|number}} unitID, etc... }
|arg2 = {{type|number}} cmdID
|arg3 = {{type|table}} params = {number, etc...}
|arg4 = {{type|table}} options = {"alt", "ctrl", "shift", "right"}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitMap
|arg1 = {{type|table}} unitMap = { {{bracket|unitID}} = arg1, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl.
}}

{{LuaCallout
|prefix = Spring.
|name = GiveOrderArrayToUnitArray
|arg1 = {{type|table}} unitArray = { {{bracket|11}} = {{type|number}} unitID, etc... }
|arg2 = {{type|table}} orderArray = { {{type|number}} cmdID, {{type|table}} params = {number, etc...}, {{type|table}} options = {"alt", "ctrl", "shift", "right"} } {{bracket}}
|arg3 = {{type|bool}} pairwise {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} true
|info = Needs ModUICtrl. "pairwise" paramater ({{new|89.0}}) is used to send multiple units a single individual command.
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildFacing
|arg1 = {{type|number}} facing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetBuildSpacing
|arg1 = {{type|number}} spacing
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

== Unit NoDraw,NoSelect,NoMinimap ==

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noSelect
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} noMinimap
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= Features =

{{LuaCallout
|prefix = Spring.
|name = SetFeatureFade
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} allow
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Control whether a feature will fade or not when zoomed out.
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} noDraw
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

{{LuaCallout
|prefix = Spring.
|name = SetFeatureSelectionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg3 = {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ
|arg4 = {{type|number}} vType
|arg5 = {{type|number}} tType
|arg6 = {{type|number}} Axis
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= Developers =

{{LuaCallout
|prefix = Spring.
|name = SetDrawSky
|arg1 = {{type|bool}} drawSky
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawWater
|arg1 = {{type|bool}} drawWater
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGround
|arg1 = {{type|bool}} drawGround
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = SetMapRenderingParams
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Allows to change map rendering params at runtime. "Params" table contains:
}}
<pre> params = {
splatTexMults = {number r, number g, number b, number a},
splatTexScales = {number r, number g, number b, number a},
voidWater = boolean value,
voidGround = boolean value,
splatDetailNormalDiffuseAlpha = boolean value,
}</pre>

{{LuaCallout
|prefix = Spring.
|name = SetLogSectionFilterLevel
|arg1 = {{type|string}} sectionName
|arg2 = {{type|string}} {{pipe}} {{type|number}} logLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{New|95.0}} See [[infolog.txt]] for possible log sections.
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawGroundDeferred
|arg1 = {{type|bool}} drawGroundDeferred {{bracket}}
|arg2 = {{type|bool}} drawGroundForward {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawGroundForward}} allows disabling of the forward pass
}}

{{LuaCallout
|prefix = Spring.
|name = SetDrawModelsDeferred
|arg1 = {{type|bool}} drawUnitsDeferred
|arg2 = {{type|bool}} drawFeaturesDeferred {{bracket}}
|arg3 = {{type|bool}} drawUnitsForward {{bracket}}
|arg4 = {{type|bool}} drawFeaturesForward {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} {{var|drawFeaturesForward}}, {{var|drawUnitsForward}} allows disabling of the respective forward passes
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingMode
|arg1 = {{type|bool}} allowCaptureMode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} This doesn't actually record the game in any way, it just regulates the framerate and interpolations.
}}

{{LuaCallout
|prefix = Spring.
|name = SetVideoCapturingTimeOffset
|arg1 = {{type|bool}} timeOffset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= GUI =

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|1}} = unitID, ... } {{bracket}}
|arg2 = {{type|bool}} false
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = DrawUnitCommands
|arg1 = {{type|table}} units = { {{bracket|unitID}} = arg1, ... }
|arg2 = {{type|bool}} true
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetTeamColor
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AssignMouseCursor
|arg1 = {{type|string}} cmdName
|arg2 = {{type|string}} iconFileName {{bracket}}
|arg3 = {{type|bool}} overwrite = true {{bracket}}
|arg4 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Changes/creates the cursor of a single CursorCmd. Note, that iconFileName is not the full filename instead it is like this: Wanted filename: Anims/cursorattack_0.bmp => iconFileName: cursorattack
}}

{{LuaCallout
|prefix = Spring.
|name = ReplaceMouseCursor
|arg1 = {{type|string}} oldFileName
|arg2 = {{type|string}} newFileName {{bracket}}
|arg3 = {{type|bool}} hotSpotTopLeft = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Mass replace all occurrence of the cursor in all CursorCmds.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} cmdID_cloneIcon {{pipe}} {{type|string}} iconname
|arg3 = {{type|table}} RGBA = { {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a } {{bracket}}
|arg4 = {{type|bool}} showArea {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

or

{{LuaCallout
|prefix = Spring.
|name = SetCustomCommandDrawData
|arg1 = {{type|number}} cmdID
|arg2 = {{type|nil}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} assigned
|info = Register your custom cmd so it gets visible in the unit's cmd queue
}}

= Sharing =

{{LuaCallout
|prefix = Spring.
|name = SetShareLevel
|arg1 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg2 = {{type|number}} shareLevel
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only! Note: shareLevel is 0<= x <= 1 .
}}

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

or

{{LuaCallout
|prefix = Spring.
|name = ShareResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} metal {{pipe}} {{type|string}} energy
|arg3 = {{type|number}} amount
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = LuaGadgets only!
}}

= UnitDef RadarIcons & BuildPics =

{{LuaCallout
|prefix = Spring.
|name = AddUnitIcon
|arg1 = {{type|string}} iconName
|arg2 = {{type|string}} texFile {{bracket}}
|arg3 = {{type|number}} size {{bracket}}
|arg4 = {{type|number}} dist {{bracket}}
|arg5 = {{type|bool}} radAdjust {{rbracket}}{{rbracket}}{{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} added
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FreeUnitIcon
|arg1 = {{type|string}} iconName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} freed
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefIcon
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} iconName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets radar icon.
}}

{{LuaCallout
|prefix = Spring.
|name = SetUnitDefImage
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|string}} luaTexture {{pipe}} {{type|string}} texFile
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl. Sets buildpic.
}}

= Camera =

{{LuaCallout
|prefix = Spring.
|name = SetCameraState
|arg1 = {{type|table}} camState
|arg2 = {{type|number}} camTime
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stateSet
|info = camState has the same format as the output of Spring.GetCameraState(). See [[Lua_camState]] for details about camState. The camState's mode/name must fit the rest of the state. Getting a state, changing its mode/name and then passing it to SetCameraState will have undesired results. [https://springrts.com/mantis/view.php?id=5028#c15491] Also see #5028]
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraTarget
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} transTime {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = For Spring Engine XZ represents horizontal, from north west corner of map and Y vertical, from water level and rising.
}}

{{LuaCallout
|prefix = Spring.
|name = SetCameraOffset
|arg1 = {{type|number}} px = 0 {{bracket}}
|arg2 = {{type|number}} py = 0 {{bracket}}
|arg3 = {{type|number}} pz = 0 {{bracket}}
|arg4 = {{type|number}} tx = 0 {{bracket}}
|arg5 = {{type|number}} ty = 0 {{bracket}}
|arg6 = {{type|number}} tz = 0 {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs ModUICtrl.
}}

= (Virtual-)FileSystem =

{{LuaCallout
|prefix = Spring.
|name = ExtractModArchiveFile
|arg1 = {{type|string}} modfile
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} extracted
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = CreateDir
|arg1 = {{type|string}} path
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} dirCreated
|info = Needs ModUICtrl.
}}

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

= Engine Config =

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

{{LuaCallout
|prefix = Spring.
|name = SetConfigInt
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigFloat
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetConfigString
|arg1 = {{type|string}} name
|arg2 = {{type|number}} value {{bracket}}
|arg3 = {{type|bool}} useOverlay = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}}
}}

= World Primitives =
outdated! use opengl api instead!

{{LuaCallout
|prefix = Spring.
|name = AddWorldIcon
|arg1 = {{type|number}} cmdID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldText
|arg1 = {{type|string}} text
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AddWorldUnit
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg3 = {{type|number}} team
|arg4 = {{type|number}} facing
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = SetSunManualControl
|arg1 = {{type|bool}} setManualControl
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunParameters
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 = {{type|number}} dist
|arg5 = {{type|number}} startTime
|arg6 = {{type|number}} orbitTime
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunDirection
|arg1 = {{type|number}} dirX
|arg2 = {{type|number}} dirY
|arg3 = {{type|number}} dirZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetSunLighting
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following sun lighting parameters:
}}
<pre> {ground,unit}{Ambient,Diffuse,Specular}Color and specularExponent
All Colourvalues have to in the Range from 0.0 to 1.0 for all colors and the alpha
Example usage: Spring.SetSunLighting({groundAmbientColor = {1, 0.1, 1}, groundDiffuseColor = {1, 0.1, 1} })</pre>

{{LuaCallout
|prefix = Spring.
|name = SetAtmosphere
|arg1 = {{type|table}} params
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} It can be used to modify the following atmosphere parameters:
}}
<pre> fog{Start,End}, {sun,sky,cloud}Color
Example usage: Spring.SetAtmosphere({ fogStart = 0, fogEnd = 0.5, fogColor = { 0.7, 0.2, 0.2, 1 }})</pre>

= Misc =

{{LuaCallout
|prefix = Spring.
|name = Reload
|arg1 = {{type|string}} startscript
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|99.0}} start-script is the CONTENT of the [[script.txt]] spring should use to start.
}}

{{LuaCallout
|prefix = Spring.
|name = Restart
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|0.79}} If this call returns, something went wrong. ''commandline_args'' are commandline arguments passed to spring executable.
}}

{{LuaCallout
|prefix = Spring.
|name = Start
|arg1 = {{type|string}} commandline_args
|arg2 = {{type|string}} startscript
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = -
|info = {{new|102.0}} If this call returns, something went wrong. Launches a new Spring instance without terminating the existing one. start-script is the CONTENT of the [[script.txt]] spring should use to start (if empty, no start-script is added, you can still point spring to your custom script.txt when you add the file-path to ''commandline_args''.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMIcon
|arg1 = {{type|string}} iconFileName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Sets the icon for the process which is seen in the OS task-bar and other places (default: spring-logo). Note: has to be 24bit or 32bit. Note: on windows, it has to be 32x32 pixels in size (recommended for cross-platform) Note: ''*.bmp'' images have to be in BGR format (default for m$ ones). Note: ''*.ico'' images are not supported.
}}

{{LuaCallout
|prefix = Spring.
|name = SetWMCaption
|arg1 = {{type|string}} title {{bracket}}
|arg2 = {{type|string}} titleShort = title {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}} Sets the window ''title'' for the process (default: "Spring <version>"). The ''shortTitle'' is displayed in the OS task-bar (default: "Spring <version>"). '''NOTE:''' ''shortTitle'' is only ever possibly used under X11 (Linux & OS X), but not with QT (KDE) and never under Windows. See [http://www.gpwiki.org/index.php/SDL:Tutorials:Initializing_SDL_Libraries#About_the_icon_.28.22Icon_Title.22.29_parameter_on_different_window-managers this site] for more details.
}}

{{LuaCallout
|prefix = Spring.
|name = ClearWatchDogTimer
|arg1 = {{bracket}} {{type|string}} threadName = main {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetClipboard
|arg1 = {{type|string}} text
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|98.0}}
}}

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

{{LuaCallout
|prefix = Spring.
|name = PreloadUnitDefModel
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = PreloadFetureDefModel
|arg1 = {{type|number}} featureDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{{new|101.0}}
}}

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

{{LuaCallout
|prefix = Spring.
|name = AddMapLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = AddModelLight
|arg1 = {{type|table}} lightParams
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} lightHandle
|info = (requires MaxDynamicMapLights > 0)
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateMapLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = UpdateModelLight
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|table}} lightParams
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetModelLightTrackingState
|arg1 = {{type|number}} lightHandle
|arg2 = {{type|number}} unitOrProjectileID
|arg3 = {{type|bool}} enableTracking
|arg4 = {{type|bool}} unitOrProjectile
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

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

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

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

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

= Map =

{{LuaCallout
|prefix = Spring.
|name = SetSkyBoxTexture
|arg1 = {{type|string}} texName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShadingTexture
|arg1 = {{type|string}} texType
|arg2 = {{type|string}} texName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = {{new|101.0}}
}}

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

{{LuaCallout
|prefix = Spring.
|name = SetMapSquareTexture
|arg1 = {{type|number}} texSqrX
|arg2 = {{type|number}} texSqrY
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = SetMapShader
|arg1 = {{type|number}} standardShaderID
|arg2 = {{type|number}} deferredShaderID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

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

[[category: Lua]]

Lua UnsyncedRead

2022-05-01T09:38:29Z

Beherith: /* Time */

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

== Replay/Spectating ==

{{LuaCallout
|prefix = Spring.
|name = IsReplay
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isReplay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetReplayLength
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} timeInSeconds
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetSpectatingState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} spectating, {{type|bool}} fullView, {{type|bool}} fullSelect
|info =
}}

== Game/Menu Name ==

{{LuaCallout
|prefix = Spring.
|name = GetGameName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}} Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".
}}

{{LuaCallout
|prefix = Spring.
|name = GetMenuName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}}
}}

== ModUI ==

{{LuaCallout
|prefix = Spring.
|name = GetModUICtrl
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} ModUICtrl
|info =
}}

== MyInfo ==

{{LuaCallout
|prefix = Spring.
|name = GetMyAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyTeamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

{{LuaCallout
|prefix = Spring.
|name = GetLocalPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyID
|info =
}}

== Team/Player Info ==

{{LuaCallout
|prefix = Spring.
|name = GetPlayerRoster
|arg1 = {{bracket}}{{type|number}} sortType{{rbracket}} {{pipe}} {{bracket}}{{type|number}} sortType{{rbracket}}, {{bracket}}{{type|bool}} showPathingPlayers{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} playerTable
|info = "playerTable" contains:
}}
<pre>playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

if pingTime == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamOrigColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerTraffic
|arg1 = {{type|number}} playerID {{bracket}}
|arg2 = {{type|number}} packetID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} traffic
|info =
}}

== Sound ==

{{LuaCallout
|prefix = Spring.
|name = GetSoundStreamTime
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playedTime, {{type|number}} totalTime,
|info =
}}

== Camera ==

{{LuaCallout
|prefix = Spring.
|name = GetCameraNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|camName}} = {{type|number}} camNum, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }
|info = See [[Lua_camState]] for details about Spring.GetCameraState output.
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraPosition
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraDirection
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} forward_x, {{type|number}} forward_y, {{type|number}} forward_z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraFOV
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} vFov, {{type|number}} hFov
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraVectors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} vectorTable
|info = vectorTable contains:
}}
<pre>vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}</pre>

=== Inview ===

{{LuaCallout
|prefix = Spring.
|name = GetVisibleUnits
|arg1 = {{bracket}}{{type|number}} teamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{rbracket}}{{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVisibleFeatures
|arg1 = {{bracket}}{{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{bracket}}
|arg4 = {{type|bool}} geos = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAABBInView
|arg1 = {{type|number}} minX, {{type|number}} minY, {{type|number}} minZ
|arg2 = {{type|number}} maxX, {{type|number}} maxY, {{type|number}} maxZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsSphereInView
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} radius {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitIcon
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitIcon
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInView
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitVisible
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|bool}} checkIcons {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isVisible
|info =
}}

=== Screen Trace ===

{{LuaCallout
|prefix = Spring.
|name = WorldToScreenCoords
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TraceScreenRay
|arg1 = {{type|number}} mouseX, {{type|number}} mouseY, {{bracket}}
|arg2 = {{type|bool}} onlyCoords {{bracket}}
|arg3 = {{type|bool}} useMinimap {{bracket}}
|arg4 = {{type|bool}} includeSky {{bracket}}
|arg5 = {{type|bool}} ignoreWater {{bracket}}
|arg6 ={{type|number}} D {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} unit, {{type|number}} unitID {{pipe}} {{type|string}} feature, {{type|number}} featureID {{pipe}} {{type|string}} ground, {{type|table}} coords = { {{bracket|1}} = {{type|number}} x, {{bracket|2}} = {{type|number}} y, {{bracket|3}} = {{type|number}} z }
|info = {{new|101.0}}
}}
<pre>Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")</pre>

{{LuaCallout
|prefix = Spring.
|name = GetPixelDir
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{New|95.0}}
}}

=== Screen & Window Geometry ===

{{LuaCallout
|prefix = Spring.
|name = GetViewGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} viewSizeX, {{type|number}} viewSizeY, {{type|number}} viewPosX, {{type|number}} viewPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWindowGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} winSizeX, {{type|number}} winSizeY, {{type|number}} winPosX, {{type|number}} winPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetScreenGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} screenSizeX, {{type|number}} screenSizeY, {{type|number}} ZERO, {{type|number}} ZERO
|info = Is missing multiscreen support!
}}

== Unit ==

{{LuaCallout
|prefix = Spring.
|name = IsUnitAllied
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitViewPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransformMatrix
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} invert = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} a11, {{type|number}} a12 ..., {{type|number}} a44 (4x4 matrix)
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

=== Selected Units ===

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsSorted
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{bracket}}{{type|number}} unitID{{rbracket}}, etc... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCounts
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCount
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitSelected
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isSelected
|info =
}}

=== Unit Groups ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|number}} = {{type|number}} unitCount, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedGroup
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIName
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} aiName
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} aiName, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnits
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsSorted
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCounts
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCount
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

== Feature ==

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetVisibleProjectiles
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|bool}} addSyncedProjectiles = true {{bracket}}
|arg3 = {{type|bool}} addWeaponProjectiles = true {{bracket}}
|arg4 = {{type|bool}} addPieceProjectiles = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} projectileID, ... }
|info =
}}

== UI ==

{{LuaCallout
|prefix = Spring.
|name = GetUICommands
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { command={{type|string}}, description={{type|string}}, synced={{type|bool}}, cheat={{type|bool}}}, ... }
|info = {{new|101.0}} Returns a list of available [[UI commands]].
}}

=== GUI Settings ===

{{LuaCallout
|prefix = Spring.
|name = IsGUIHidden
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isHidden
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveShadows
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShadows
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveAdvShading
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWaterMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|string}} mode
|info =
}}
<pre> mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown</pre>

{{LuaCallout
|prefix = Spring.
|name = GetMapDrawMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "normal" {{pipe}} {{type|string}} "height" {{pipe}} {{type|string}} "metal" {{pipe}} {{type|string}} "pathTraversability" {{pipe}} {{type|string}} "los"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawSelectionInfo
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} drawSelectInfo
|info = Returns whether "Selected units" text is displayed.
}}

=== Unit & Feature GUI States ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitLuaDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} unitDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noMinimap
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLuaDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} featureDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

=== Minimap ===

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} sizeX, {{type|number}} sizeY, {{type|bool}} minimized, {{type|bool}} maximized
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapDualScreen
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} false {{pipe}} {{type|string}} "left" {{pipe}} {{type|string}} "right"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAboveMiniMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAbove
|info =
}}

=== (Build-)Menu ===

{{LuaCallout
|prefix = Spring.
|name = GetActiveCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDefaultCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDescs
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
[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, .. }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDesc
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
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, .. }
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetCmdDescIndex
|arg1 = {{type|number}} cmdID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActivePage
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pageNum, {{type|number}} maxPages
|info =
}}

=== Build Facing ===

{{LuaCallout
|prefix = Spring.
|name = GetBuildFacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetBuildSpacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spacing
|info =
}}

=== GatherMode & InvertQueueKey ===

{{LuaCallout
|prefix = Spring.
|name = GetGatherMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gatherMode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetInvertQueueKey
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} queueKey
|info =
}}

=== Mouse States ===

{{LuaCallout
|prefix = Spring.
|name = GetMouseState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|bool}} leftPressed, {{type|bool}} middlePressed, {{type|bool}} rightPressed, {{type|bool}} offscreen
|info = {{new|104.0}} Sixth return value offscreen. X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner. For world coordinates see Spring.TraceScreenRay.
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseCursor
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string }} name, {{type|number}} scale
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseStartPosition
|arg1 = {{type|number}} mouseButton
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pressedX, {{type|number}} pressedY, {{type|number}} camPosX, {{type|number}} camPosY, {{type|number}} camPosZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

=== (Hot-)Keys ===

{{LuaCallout
|prefix = Spring.
|name = GetKeyState
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} keyState
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetModKeyState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} alt, {{type|bool}} ctrl, {{type|bool}} meta, {{type|bool}} shift
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPressedKeys
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} code{{rbracket}} = {{type|bool}}, {{bracket}}{{type|string}} name{{rbracket}} = {{type|bool}}, ... }
|info = {{new|99.0}}: {{type|string}} name Returns the SDL1 codes for the pressed keys, first as an integer, a string containing the hex representation. Use Spring.[[Lua_UnsyncedRead#GetKeySymbol|GetKeySymbol]] to convert to an SDL2 symbol.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyCode
|arg1 = {{type|string}} keysym
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} keyCode
|info = Returns the SDL1 code for the SDL2 symbol
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeySymbol
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "keysym1", {{type|string}} "keysym2"
|info = Converts an SDL1 keycode into an SDL2 keycode, represented as a hexadecimal string. For most cases, these values will be the same.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyBindings
|arg1 = {{type|string}} keyset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} keyBindings
|info = keyBindings contains:
}}
<pre>keyBindings = {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActionHotKeys
|arg1 = {{type|string}} action
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} hotKey, ... }
|info =
}}

=== Console ===

{{LuaCallout
|prefix = Spring.
|name = GetLastMessagePositions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { {{type|number}} x, {{type|number}} y, {{type|number}} z }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConsoleBuffer
|arg1 = {{bracket}}{{type|number}} maxLines{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { text = {{type|string}}, priority = {{type|number}} }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCurrentTooltip
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} tooltip
|info =
}}

=== LOS Colors ===

{{LuaCallout
|prefix = Spring.
|name = GetLosViewColors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} always = {r,g,b}, {{type|table}} LOS = {r,g,b}, {{type|table}} radar = {r,g,b}, {{type|table}} jam = {r,g,b}, {{type|table}} radar2 = {r,g,b}
|info = {{new|100}}
}}

== Config ==

{{LuaCallout
|prefix = Spring.
|name = GetConfigParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} configParams
|info = Same information as <code>spring --list-config-vars</code> configParams contains:
}}
<pre>configParams = {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetConfigInt
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configInt
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigFloat
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configFloat
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigString
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} configString
|info =
}}

== FPS & GetDrawFrame ==

{{LuaCallout
|prefix = Spring.
|name = GetFPS
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} fps
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} low_16bit, {{type|number}} high_16bit
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVideoCapturingMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} videoCaptureAllowed
|info = {{new|104.0}}
}}

== Time ==

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = Speed factors are by default 1.0, (the default simulation gamespeed) but are not 0 when the game is paused. Factor at 10x gamespeed is 10.0. {{new|98.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} finishedLoading, {{type|bool}} loadedFromSave, {{type|bool}} locallyPaused, {{type|bool}} laggingWrtExpectedFromSimtime
|info = {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimeOffset
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} offset
|info = Gets globalRendering->timeOffset, which contains the offset of the current draw frame from the last sim frame, expressed in fractions of a frame. Ideally, when running 30hz sim, and 60hz rendering, the draw frames should have and offset of either 0.0 frames, or 0.5 frames. When draw frames are not integer multiples of sim frames, some interpolation happens, and this timeoffset shows how far along it is.
}}

{{LuaCallout
|prefix = Spring.
|name = GetLastUpdateSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lastUpdateSeconds
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHasLag
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasLag
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = This function returns a timer type object, which we can use a pair of to calculate the time difference between two timer objects with DiffTimers. However, this time is at best millisecond resolution.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimer
|arg1 = {{bracket}} {{type|bool}} lastFrameTime {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = {{new|102.0}} Get a timer for the start of the frame, this should give better results for camera interpolations. If given an optional boolean true, then it returns the game->lastFrameTime instead of the lastFrameStart
}}

{{LuaCallout
|prefix = Spring.
|name = DiffTimers
|arg1 = {{type|timer}} cur
|arg2 = {{type|timer}} ago {{bracket}}
|arg3 = {{type|bool}} inMilliseconds {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info = {{New|95.0}} Optional third argument (boolean) to return dt in milliseconds.
}}

== Rendering ==

{{LuaCallout
|prefix = Spring.
|name = GetMapSquareTexture
|arg1 = {{type|number}} texSqrX, {{type|number}} texSqrY
|arg2 = {{type|number}} texMipLvl
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

== Logging ==

{{LuaCallout
|prefix = Spring.
|name = GetLogSections
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} logSections = { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }
|info =
}}

== Misc ==

{{LuaCallout
|prefix = Spring.
|name = GetClipboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} text
|info = {{new|98.0}}
}}

[[category: Lua]]

Lua UnsyncedRead

2022-04-20T14:09:16Z

Beherith: /* Time */

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

== Replay/Spectating ==

{{LuaCallout
|prefix = Spring.
|name = IsReplay
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isReplay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetReplayLength
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} timeInSeconds
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetSpectatingState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} spectating, {{type|bool}} fullView, {{type|bool}} fullSelect
|info =
}}

== Game/Menu Name ==

{{LuaCallout
|prefix = Spring.
|name = GetGameName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}} Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".
}}

{{LuaCallout
|prefix = Spring.
|name = GetMenuName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}}
}}

== ModUI ==

{{LuaCallout
|prefix = Spring.
|name = GetModUICtrl
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} ModUICtrl
|info =
}}

== MyInfo ==

{{LuaCallout
|prefix = Spring.
|name = GetMyAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyTeamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

{{LuaCallout
|prefix = Spring.
|name = GetLocalPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyID
|info =
}}

== Team/Player Info ==

{{LuaCallout
|prefix = Spring.
|name = GetPlayerRoster
|arg1 = {{bracket}}{{type|number}} sortType{{rbracket}} {{pipe}} {{bracket}}{{type|number}} sortType{{rbracket}}, {{bracket}}{{type|bool}} showPathingPlayers{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} playerTable
|info = "playerTable" contains:
}}
<pre>playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

if pingTime == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamOrigColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerTraffic
|arg1 = {{type|number}} playerID {{bracket}}
|arg2 = {{type|number}} packetID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} traffic
|info =
}}

== Sound ==

{{LuaCallout
|prefix = Spring.
|name = GetSoundStreamTime
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playedTime, {{type|number}} totalTime,
|info =
}}

== Camera ==

{{LuaCallout
|prefix = Spring.
|name = GetCameraNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|camName}} = {{type|number}} camNum, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }
|info = See [[Lua_camState]] for details about Spring.GetCameraState output.
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraPosition
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraDirection
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} forward_x, {{type|number}} forward_y, {{type|number}} forward_z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraFOV
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} vFov, {{type|number}} hFov
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraVectors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} vectorTable
|info = vectorTable contains:
}}
<pre>vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}</pre>

=== Inview ===

{{LuaCallout
|prefix = Spring.
|name = GetVisibleUnits
|arg1 = {{bracket}}{{type|number}} teamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{rbracket}}{{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVisibleFeatures
|arg1 = {{bracket}}{{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{bracket}}
|arg4 = {{type|bool}} geos = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAABBInView
|arg1 = {{type|number}} minX, {{type|number}} minY, {{type|number}} minZ
|arg2 = {{type|number}} maxX, {{type|number}} maxY, {{type|number}} maxZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsSphereInView
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} radius {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitIcon
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitIcon
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInView
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitVisible
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|bool}} checkIcons {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isVisible
|info =
}}

=== Screen Trace ===

{{LuaCallout
|prefix = Spring.
|name = WorldToScreenCoords
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TraceScreenRay
|arg1 = {{type|number}} mouseX, {{type|number}} mouseY, {{bracket}}
|arg2 = {{type|bool}} onlyCoords {{bracket}}
|arg3 = {{type|bool}} useMinimap {{bracket}}
|arg4 = {{type|bool}} includeSky {{bracket}}
|arg5 = {{type|bool}} ignoreWater {{bracket}}
|arg6 ={{type|number}} D {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} unit, {{type|number}} unitID {{pipe}} {{type|string}} feature, {{type|number}} featureID {{pipe}} {{type|string}} ground, {{type|table}} coords = { {{bracket|1}} = {{type|number}} x, {{bracket|2}} = {{type|number}} y, {{bracket|3}} = {{type|number}} z }
|info = {{new|101.0}}
}}
<pre>Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")</pre>

{{LuaCallout
|prefix = Spring.
|name = GetPixelDir
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{New|95.0}}
}}

=== Screen & Window Geometry ===

{{LuaCallout
|prefix = Spring.
|name = GetViewGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} viewSizeX, {{type|number}} viewSizeY, {{type|number}} viewPosX, {{type|number}} viewPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWindowGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} winSizeX, {{type|number}} winSizeY, {{type|number}} winPosX, {{type|number}} winPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetScreenGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} screenSizeX, {{type|number}} screenSizeY, {{type|number}} ZERO, {{type|number}} ZERO
|info = Is missing multiscreen support!
}}

== Unit ==

{{LuaCallout
|prefix = Spring.
|name = IsUnitAllied
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitViewPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransformMatrix
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} invert = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} a11, {{type|number}} a12 ..., {{type|number}} a44 (4x4 matrix)
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

=== Selected Units ===

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsSorted
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{bracket}}{{type|number}} unitID{{rbracket}}, etc... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCounts
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCount
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitSelected
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isSelected
|info =
}}

=== Unit Groups ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|number}} = {{type|number}} unitCount, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedGroup
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIName
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} aiName
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} aiName, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnits
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsSorted
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCounts
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCount
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

== Feature ==

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetVisibleProjectiles
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|bool}} addSyncedProjectiles = true {{bracket}}
|arg3 = {{type|bool}} addWeaponProjectiles = true {{bracket}}
|arg4 = {{type|bool}} addPieceProjectiles = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} projectileID, ... }
|info =
}}

== UI ==

{{LuaCallout
|prefix = Spring.
|name = GetUICommands
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { command={{type|string}}, description={{type|string}}, synced={{type|bool}}, cheat={{type|bool}}}, ... }
|info = {{new|101.0}} Returns a list of available [[UI commands]].
}}

=== GUI Settings ===

{{LuaCallout
|prefix = Spring.
|name = IsGUIHidden
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isHidden
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveShadows
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShadows
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveAdvShading
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWaterMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|string}} mode
|info =
}}
<pre> mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown</pre>

{{LuaCallout
|prefix = Spring.
|name = GetMapDrawMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "normal" {{pipe}} {{type|string}} "height" {{pipe}} {{type|string}} "metal" {{pipe}} {{type|string}} "pathTraversability" {{pipe}} {{type|string}} "los"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawSelectionInfo
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} drawSelectInfo
|info = Returns whether "Selected units" text is displayed.
}}

=== Unit & Feature GUI States ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitLuaDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} unitDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noMinimap
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLuaDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} featureDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

=== Minimap ===

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} sizeX, {{type|number}} sizeY, {{type|bool}} minimized, {{type|bool}} maximized
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapDualScreen
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} false {{pipe}} {{type|string}} "left" {{pipe}} {{type|string}} "right"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAboveMiniMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAbove
|info =
}}

=== (Build-)Menu ===

{{LuaCallout
|prefix = Spring.
|name = GetActiveCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDefaultCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDescs
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
[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, .. }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDesc
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
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, .. }
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetCmdDescIndex
|arg1 = {{type|number}} cmdID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActivePage
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pageNum, {{type|number}} maxPages
|info =
}}

=== Build Facing ===

{{LuaCallout
|prefix = Spring.
|name = GetBuildFacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetBuildSpacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spacing
|info =
}}

=== GatherMode & InvertQueueKey ===

{{LuaCallout
|prefix = Spring.
|name = GetGatherMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gatherMode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetInvertQueueKey
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} queueKey
|info =
}}

=== Mouse States ===

{{LuaCallout
|prefix = Spring.
|name = GetMouseState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|bool}} leftPressed, {{type|bool}} middlePressed, {{type|bool}} rightPressed, {{type|bool}} offscreen
|info = {{new|104.0}} Sixth return value offscreen. X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner. For world coordinates see Spring.TraceScreenRay.
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseCursor
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string }} name, {{type|number}} scale
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseStartPosition
|arg1 = {{type|number}} mouseButton
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pressedX, {{type|number}} pressedY, {{type|number}} camPosX, {{type|number}} camPosY, {{type|number}} camPosZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

=== (Hot-)Keys ===

{{LuaCallout
|prefix = Spring.
|name = GetKeyState
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} keyState
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetModKeyState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} alt, {{type|bool}} ctrl, {{type|bool}} meta, {{type|bool}} shift
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPressedKeys
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} code{{rbracket}} = {{type|bool}}, {{bracket}}{{type|string}} name{{rbracket}} = {{type|bool}}, ... }
|info = {{new|99.0}}: {{type|string}} name Returns the SDL1 codes for the pressed keys, first as an integer, a string containing the hex representation. Use Spring.[[Lua_UnsyncedRead#GetKeySymbol|GetKeySymbol]] to convert to an SDL2 symbol.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyCode
|arg1 = {{type|string}} keysym
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} keyCode
|info = Returns the SDL1 code for the SDL2 symbol
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeySymbol
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "keysym1", {{type|string}} "keysym2"
|info = Converts an SDL1 keycode into an SDL2 keycode, represented as a hexadecimal string. For most cases, these values will be the same.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyBindings
|arg1 = {{type|string}} keyset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} keyBindings
|info = keyBindings contains:
}}
<pre>keyBindings = {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActionHotKeys
|arg1 = {{type|string}} action
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} hotKey, ... }
|info =
}}

=== Console ===

{{LuaCallout
|prefix = Spring.
|name = GetLastMessagePositions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { {{type|number}} x, {{type|number}} y, {{type|number}} z }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConsoleBuffer
|arg1 = {{bracket}}{{type|number}} maxLines{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { text = {{type|string}}, priority = {{type|number}} }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCurrentTooltip
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} tooltip
|info =
}}

=== LOS Colors ===

{{LuaCallout
|prefix = Spring.
|name = GetLosViewColors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} always = {r,g,b}, {{type|table}} LOS = {r,g,b}, {{type|table}} radar = {r,g,b}, {{type|table}} jam = {r,g,b}, {{type|table}} radar2 = {r,g,b}
|info = {{new|100}}
}}

== Config ==

{{LuaCallout
|prefix = Spring.
|name = GetConfigParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} configParams
|info = Same information as <code>spring --list-config-vars</code> configParams contains:
}}
<pre>configParams = {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetConfigInt
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configInt
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigFloat
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configFloat
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigString
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} configString
|info =
}}

== FPS & GetDrawFrame ==

{{LuaCallout
|prefix = Spring.
|name = GetFPS
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} fps
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} low_16bit, {{type|number}} high_16bit
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVideoCapturingMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} videoCaptureAllowed
|info = {{new|104.0}}
}}

== Time ==

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = {{new|98.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} finishedLoading, {{type|bool}} loadedFromSave, {{type|bool}} locallyPaused, {{type|bool}} laggingWrtExpectedFromSimtime
|info = {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimeOffset
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} offset
|info = Gets globalRendering->timeOffset, which contains the offset of the current draw frame from the last sim frame, expressed in fractions of a frame. Ideally, when running 30hz sim, and 60hz rendering, the draw frames should have and offset of either 0.0 frames, or 0.5 frames. When draw frames are not integer multiples of sim frames, some interpolation happens, and this timeoffset shows how far along it is.
}}

{{LuaCallout
|prefix = Spring.
|name = GetLastUpdateSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lastUpdateSeconds
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHasLag
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasLag
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = This function returns a timer type object, which we can use a pair of to calculate the time difference between two timer objects with DiffTimers. However, this time is at best millisecond resolution.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimer
|arg1 = {{bracket}} {{type|bool}} lastFrameTime {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = {{new|102.0}} Get a timer for the start of the frame, this should give better results for camera interpolations. If given an optional boolean true, then it returns the game->lastFrameTime instead of the lastFrameStart
}}

{{LuaCallout
|prefix = Spring.
|name = DiffTimers
|arg1 = {{type|timer}} cur
|arg2 = {{type|timer}} ago {{bracket}}
|arg3 = {{type|bool}} inMilliseconds {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info = {{New|95.0}} Optional third argument (boolean) to return dt in milliseconds.
}}

== Rendering ==

{{LuaCallout
|prefix = Spring.
|name = GetMapSquareTexture
|arg1 = {{type|number}} texSqrX, {{type|number}} texSqrY
|arg2 = {{type|number}} texMipLvl
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

== Logging ==

{{LuaCallout
|prefix = Spring.
|name = GetLogSections
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} logSections = { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }
|info =
}}

== Misc ==

{{LuaCallout
|prefix = Spring.
|name = GetClipboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} text
|info = {{new|98.0}}
}}

[[category: Lua]]

Lua UnsyncedRead

2022-04-20T14:08:26Z

Beherith: /* Time */

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

== Replay/Spectating ==

{{LuaCallout
|prefix = Spring.
|name = IsReplay
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isReplay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetReplayLength
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} timeInSeconds
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetSpectatingState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} spectating, {{type|bool}} fullView, {{type|bool}} fullSelect
|info =
}}

== Game/Menu Name ==

{{LuaCallout
|prefix = Spring.
|name = GetGameName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}} Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".
}}

{{LuaCallout
|prefix = Spring.
|name = GetMenuName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}}
}}

== ModUI ==

{{LuaCallout
|prefix = Spring.
|name = GetModUICtrl
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} ModUICtrl
|info =
}}

== MyInfo ==

{{LuaCallout
|prefix = Spring.
|name = GetMyAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyTeamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

{{LuaCallout
|prefix = Spring.
|name = GetLocalPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyID
|info =
}}

== Team/Player Info ==

{{LuaCallout
|prefix = Spring.
|name = GetPlayerRoster
|arg1 = {{bracket}}{{type|number}} sortType{{rbracket}} {{pipe}} {{bracket}}{{type|number}} sortType{{rbracket}}, {{bracket}}{{type|bool}} showPathingPlayers{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} playerTable
|info = "playerTable" contains:
}}
<pre>playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

if pingTime == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamOrigColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerTraffic
|arg1 = {{type|number}} playerID {{bracket}}
|arg2 = {{type|number}} packetID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} traffic
|info =
}}

== Sound ==

{{LuaCallout
|prefix = Spring.
|name = GetSoundStreamTime
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playedTime, {{type|number}} totalTime,
|info =
}}

== Camera ==

{{LuaCallout
|prefix = Spring.
|name = GetCameraNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|camName}} = {{type|number}} camNum, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }
|info = See [[Lua_camState]] for details about Spring.GetCameraState output.
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraPosition
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraDirection
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} forward_x, {{type|number}} forward_y, {{type|number}} forward_z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraFOV
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} vFov, {{type|number}} hFov
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraVectors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} vectorTable
|info = vectorTable contains:
}}
<pre>vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}</pre>

=== Inview ===

{{LuaCallout
|prefix = Spring.
|name = GetVisibleUnits
|arg1 = {{bracket}}{{type|number}} teamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{rbracket}}{{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVisibleFeatures
|arg1 = {{bracket}}{{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{bracket}}
|arg4 = {{type|bool}} geos = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAABBInView
|arg1 = {{type|number}} minX, {{type|number}} minY, {{type|number}} minZ
|arg2 = {{type|number}} maxX, {{type|number}} maxY, {{type|number}} maxZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsSphereInView
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} radius {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitIcon
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitIcon
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInView
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitVisible
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|bool}} checkIcons {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isVisible
|info =
}}

=== Screen Trace ===

{{LuaCallout
|prefix = Spring.
|name = WorldToScreenCoords
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TraceScreenRay
|arg1 = {{type|number}} mouseX, {{type|number}} mouseY, {{bracket}}
|arg2 = {{type|bool}} onlyCoords {{bracket}}
|arg3 = {{type|bool}} useMinimap {{bracket}}
|arg4 = {{type|bool}} includeSky {{bracket}}
|arg5 = {{type|bool}} ignoreWater {{bracket}}
|arg6 ={{type|number}} D {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} unit, {{type|number}} unitID {{pipe}} {{type|string}} feature, {{type|number}} featureID {{pipe}} {{type|string}} ground, {{type|table}} coords = { {{bracket|1}} = {{type|number}} x, {{bracket|2}} = {{type|number}} y, {{bracket|3}} = {{type|number}} z }
|info = {{new|101.0}}
}}
<pre>Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")</pre>

{{LuaCallout
|prefix = Spring.
|name = GetPixelDir
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{New|95.0}}
}}

=== Screen & Window Geometry ===

{{LuaCallout
|prefix = Spring.
|name = GetViewGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} viewSizeX, {{type|number}} viewSizeY, {{type|number}} viewPosX, {{type|number}} viewPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWindowGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} winSizeX, {{type|number}} winSizeY, {{type|number}} winPosX, {{type|number}} winPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetScreenGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} screenSizeX, {{type|number}} screenSizeY, {{type|number}} ZERO, {{type|number}} ZERO
|info = Is missing multiscreen support!
}}

== Unit ==

{{LuaCallout
|prefix = Spring.
|name = IsUnitAllied
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitViewPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransformMatrix
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} invert = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} a11, {{type|number}} a12 ..., {{type|number}} a44 (4x4 matrix)
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

=== Selected Units ===

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsSorted
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{bracket}}{{type|number}} unitID{{rbracket}}, etc... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCounts
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCount
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitSelected
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isSelected
|info =
}}

=== Unit Groups ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|number}} = {{type|number}} unitCount, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedGroup
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIName
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} aiName
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} aiName, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnits
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsSorted
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCounts
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCount
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

== Feature ==

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetVisibleProjectiles
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|bool}} addSyncedProjectiles = true {{bracket}}
|arg3 = {{type|bool}} addWeaponProjectiles = true {{bracket}}
|arg4 = {{type|bool}} addPieceProjectiles = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} projectileID, ... }
|info =
}}

== UI ==

{{LuaCallout
|prefix = Spring.
|name = GetUICommands
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { command={{type|string}}, description={{type|string}}, synced={{type|bool}}, cheat={{type|bool}}}, ... }
|info = {{new|101.0}} Returns a list of available [[UI commands]].
}}

=== GUI Settings ===

{{LuaCallout
|prefix = Spring.
|name = IsGUIHidden
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isHidden
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveShadows
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShadows
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveAdvShading
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWaterMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|string}} mode
|info =
}}
<pre> mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown</pre>

{{LuaCallout
|prefix = Spring.
|name = GetMapDrawMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "normal" {{pipe}} {{type|string}} "height" {{pipe}} {{type|string}} "metal" {{pipe}} {{type|string}} "pathTraversability" {{pipe}} {{type|string}} "los"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawSelectionInfo
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} drawSelectInfo
|info = Returns whether "Selected units" text is displayed.
}}

=== Unit & Feature GUI States ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitLuaDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} unitDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noMinimap
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLuaDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} featureDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

=== Minimap ===

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} sizeX, {{type|number}} sizeY, {{type|bool}} minimized, {{type|bool}} maximized
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapDualScreen
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} false {{pipe}} {{type|string}} "left" {{pipe}} {{type|string}} "right"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAboveMiniMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAbove
|info =
}}

=== (Build-)Menu ===

{{LuaCallout
|prefix = Spring.
|name = GetActiveCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDefaultCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDescs
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
[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, .. }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDesc
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
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, .. }
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetCmdDescIndex
|arg1 = {{type|number}} cmdID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActivePage
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pageNum, {{type|number}} maxPages
|info =
}}

=== Build Facing ===

{{LuaCallout
|prefix = Spring.
|name = GetBuildFacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetBuildSpacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spacing
|info =
}}

=== GatherMode & InvertQueueKey ===

{{LuaCallout
|prefix = Spring.
|name = GetGatherMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gatherMode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetInvertQueueKey
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} queueKey
|info =
}}

=== Mouse States ===

{{LuaCallout
|prefix = Spring.
|name = GetMouseState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|bool}} leftPressed, {{type|bool}} middlePressed, {{type|bool}} rightPressed, {{type|bool}} offscreen
|info = {{new|104.0}} Sixth return value offscreen. X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner. For world coordinates see Spring.TraceScreenRay.
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseCursor
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string }} name, {{type|number}} scale
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseStartPosition
|arg1 = {{type|number}} mouseButton
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pressedX, {{type|number}} pressedY, {{type|number}} camPosX, {{type|number}} camPosY, {{type|number}} camPosZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

=== (Hot-)Keys ===

{{LuaCallout
|prefix = Spring.
|name = GetKeyState
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} keyState
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetModKeyState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} alt, {{type|bool}} ctrl, {{type|bool}} meta, {{type|bool}} shift
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPressedKeys
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} code{{rbracket}} = {{type|bool}}, {{bracket}}{{type|string}} name{{rbracket}} = {{type|bool}}, ... }
|info = {{new|99.0}}: {{type|string}} name Returns the SDL1 codes for the pressed keys, first as an integer, a string containing the hex representation. Use Spring.[[Lua_UnsyncedRead#GetKeySymbol|GetKeySymbol]] to convert to an SDL2 symbol.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyCode
|arg1 = {{type|string}} keysym
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} keyCode
|info = Returns the SDL1 code for the SDL2 symbol
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeySymbol
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "keysym1", {{type|string}} "keysym2"
|info = Converts an SDL1 keycode into an SDL2 keycode, represented as a hexadecimal string. For most cases, these values will be the same.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyBindings
|arg1 = {{type|string}} keyset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} keyBindings
|info = keyBindings contains:
}}
<pre>keyBindings = {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActionHotKeys
|arg1 = {{type|string}} action
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} hotKey, ... }
|info =
}}

=== Console ===

{{LuaCallout
|prefix = Spring.
|name = GetLastMessagePositions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { {{type|number}} x, {{type|number}} y, {{type|number}} z }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConsoleBuffer
|arg1 = {{bracket}}{{type|number}} maxLines{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { text = {{type|string}}, priority = {{type|number}} }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCurrentTooltip
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} tooltip
|info =
}}

=== LOS Colors ===

{{LuaCallout
|prefix = Spring.
|name = GetLosViewColors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} always = {r,g,b}, {{type|table}} LOS = {r,g,b}, {{type|table}} radar = {r,g,b}, {{type|table}} jam = {r,g,b}, {{type|table}} radar2 = {r,g,b}
|info = {{new|100}}
}}

== Config ==

{{LuaCallout
|prefix = Spring.
|name = GetConfigParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} configParams
|info = Same information as <code>spring --list-config-vars</code> configParams contains:
}}
<pre>configParams = {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetConfigInt
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configInt
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigFloat
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configFloat
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigString
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} configString
|info =
}}

== FPS & GetDrawFrame ==

{{LuaCallout
|prefix = Spring.
|name = GetFPS
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} fps
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} low_16bit, {{type|number}} high_16bit
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVideoCapturingMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} videoCaptureAllowed
|info = {{new|104.0}}
}}

== Time ==

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = {{new|98.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} finishedLoading, {{type|bool}} loadedFromSave, {{type|bool}} locallyPaused, {{type|bool}} laggingWrtExpectedFromSimtime
|info = {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimeOffset
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} offset
|info = Gets globalRendering->timeOffset, which contains the offset of the current draw frame from the last sim frame, expressed in fractions of a frame. Ideally, when running 30hz sim, and 60hz rendering, the draw frames should have and offset of either 0.0 frames, or 0.5 frames. When draw frames are not integer multiples of sim frames, some interpolation happens, and this timeoffset shows how far along it is.
}}

{{LuaCallout
|prefix = Spring.
|name = GetLastUpdateSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lastUpdateSeconds
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHasLag
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasLag
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = This function returns a timer type object, which we can use a pair of to calculate the time difference between two timer objects with DiffTimers. However, this time is at best millisecond resolution.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimer
|arg1 = {{type|bool}} lastFrameTime{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = {{new|102.0}} Get a timer for the start of the frame, this should give better results for camera interpolations. If given a boolean true, then it returns the game->lastFrameTime instead of the lastFrameStart
}}

{{LuaCallout
|prefix = Spring.
|name = DiffTimers
|arg1 = {{type|timer}} cur
|arg2 = {{type|timer}} ago {{bracket}}
|arg3 = {{type|bool}} inMilliseconds {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info = {{New|95.0}} Optional third argument (boolean) to return dt in milliseconds.
}}

== Rendering ==

{{LuaCallout
|prefix = Spring.
|name = GetMapSquareTexture
|arg1 = {{type|number}} texSqrX, {{type|number}} texSqrY
|arg2 = {{type|number}} texMipLvl
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

== Logging ==

{{LuaCallout
|prefix = Spring.
|name = GetLogSections
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} logSections = { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }
|info =
}}

== Misc ==

{{LuaCallout
|prefix = Spring.
|name = GetClipboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} text
|info = {{new|98.0}}
}}

[[category: Lua]]

Balanced Annihilation

2022-03-20T19:03:03Z

Beherith: Do not falsify information in the wiki regarding past maintainers of a project. Perform your edits to the tournament information separately.

[[category:Games]][[category:Balanced Annihilation]]
'''[[Games|<--Back to Games]]'''

https://balancedannihilation.com/balanced-annihilation.png

===Links===
* [https://balancedannihilation.com/ BA website]
* [https://discord.gg/jvFCZHBXTU BA Discord]
* [https://springrts.com/phpbb/viewforum.php?f=44 BA forum]

===Overview===
[https://balancedannihilation.com/ Balanced Annihilation] is a Total Annihilation mod remastered with improved graphics and balance. The philosophy of Balanced Annihilation follows three principles:

* '''Refined Total Annihilation mod:''' BA's lineage traces back to Total Annihilation and the mods that refined its classic graphics and gameplay across decades.

* '''Competitive Gameplay:''' BA has matured through over 15 years of playtesting by veteran players in both casual and tournament settings. Faction and unit choices offer many unique tactical possibilities.

* '''Stable Balance:''' BA is conservatively balanced to favour strategic play. Every unit has a role and few units get truly obsolete as the game progresses.

===Tournaments===
Balanced Annihilation runs competitive 1v1 tournaments that attract many dedicated players. At 42 players the [https://challonge.com/CROWN_CUP_2 2021 Crown Cup 2 tournament] was the largest tournament in Spring's 16 year history. Players battle for the BA crown, a unique in-game item for the commander that can only be aquired by winning the event.

*Crown Cup 1 https://challonge.com/CROWN_CUP '''1st Cartouche, 2nd PRO_rANDY, 3rd Teddy'''
*Crown Cup 2 https://challonge.com/CROWN_CUP_2 '''1st Cartouche, 2nd Teddy, 3rd PtaQ '''
*Crown Cup 3, '''Upcoming Event''' 12th March 2022 https://challonge.com/CROWN_CUP_3

===History===

Balanced Annihilation is a Total Annihilation remake built using the [https://en.wikipedia.org/wiki/Spring_Engine Spring engine] whose history traces back to the mod [[Absolute_Annihilation|Absolute Annihilation]] by Caydr (2002-2006). AA was based on [http://bsr.tauniverse.com/faq.html ÜberHack] by Brave Sir Robin (1998-2002). The [https://www.clan-sy.com/frame.html Swedish Yankspankers] work on the TA Demo Recorder (1999-2004) made it possible for AA to be ported to 3D and these efforts led to the creation of Balanced Annihilation in 2006. Zero-K and BAR were both forked from Balanced Annihilation in the past.

===Development===

The current developer is [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=10773 Ares] (2020). The previous maintainers, who shouldn't be forgotten, were:
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=2568 Shox] (2019)
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=10555 Floris] (2015-19)
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=9073 Decay] (2015-16)
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=7229 Silentwings] (2012-15)
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=5958 Beherith] (2011-12)
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=7403 Niobium] (2011)
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=4460 TheFatController] (2010-11)
* [https://springrts.com/phpbb/memberlist.php?mode=viewprofile&u=326 NOiZE]. (2006-11)

'''[[Games|<--Back to Games]]'''

Lua SyncedRead

2022-02-26T21:09:42Z

Beherith: /* GetUnits */

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

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

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

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[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
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info = Note that when called from a widget, this also returns units that are only radar blips. For units that are radar blips, you may want to check if they are in los, as GetUnitDefID() will still return true if they have previously been seen. See the UnsyncedRead GetVisibleUnits() call.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ). Also very important to note, that you can receive units that are 'already dead', when you do a Spring.GetAllUnits() call. These 'dead' units have already had their unitdestroyed callins called, and that will not get called again, and even more interestingly, these units are also valid, as in the above ValidUnitID callin will return true. The GetUnitIsDead howerver, will return true for these units, that are already dead but still valid units.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = Gets which team a unit belongs to. Note that this still returns the old team when called from the UnitTaken / UnitGiven callins.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets. And RAW returns an bitmask integer, where the bits are: 1: LOS_INLOS, the unit is currently in the los of the allyteam, 2: LOS_INRADAR the unit is currently in radar from the allyteam, 4: LOS_PREVLOS the unit has previously been in los from the allyteam, 8: LOS_CONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = 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 a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[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, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1 {{pipe}} {{type|number}} 255
|info = With x & z in worldspace coordinates. Returns 255 if grass is disabled in settings, or if map does not have a grassmap specified.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>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"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

Lua:Callins

2022-02-21T11:30:15Z

Beherith: /* 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.

'''Attention:''' some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace. This document will be continuously updated to properly alert about those situations.

== 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. A list of key codes can be seen at the [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{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 (including when the game is paused) and at least once per sim frame except when catching up. The parameter is the time since the last update. }}

=== Draw* Functions ===
Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.
 
Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

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

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

{{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
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

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

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{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, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== 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. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== 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 = UnitHarvestStorageFull
|args = unitID, unitDefID, unitTeam
|info = Called when a unit's harvestStorage is full (according to its unitDef's entry).
}}

{{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]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{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. Its called after the unit is in LOS, so you can query that unit.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam. For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.
}}

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

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam. Also called when a unit leaves LOS without any radar coverage. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.
}}

{{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. Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and reclaim they are positive.
}}

{{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 = playerID, teamID, readyState, clampedX, clampedY, clampedZ, 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.
NB: The order of the parameters changed with the addition of {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

{{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". {{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]] or [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaUIMsg]].
}}

{{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
|I recommend looking up the CallIns in Sourcecode, because the Lua-Documentation, generated from the lua handle of them is seriously flawed and not regenerated.
|Lua-Handler documented from version
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynced.h#L106
|Actual CallIn:
|args = proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|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. The start and hit position arguments are provided from 104.0 onwards.
}}

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

Lua:Callins

2022-02-21T11:28:51Z

Beherith: /* 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.

'''Attention:''' some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace. This document will be continuously updated to properly alert about those situations.

== 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. A list of key codes can be seen at the [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{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 (including when the game is paused) and at least once per sim frame except when catching up. The parameter is the time since the last update. }}

=== Draw* Functions ===
Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.
 
Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

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

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

{{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
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

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

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{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, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== 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. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== 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 = UnitHarvestStorageFull
|args = unitID, unitDefID, unitTeam
|info = Called when a unit's harvestStorage is full (according to its unitDef's entry).
}}

{{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]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{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. Its called after the unit is in LOS, so you can query that unit.
}}

{{LuaCallin
|name = UnitLeftLos
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves LOS of an allyteam. For widgets, this one is called just before the unit leaves los, so you can still get the position of a unit that left los.
}}

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

{{LuaCallin
|name = UnitLeftRadar
|args = unitID, unitTeam, allyTeam, unitDefID
|info = Called when a unit leaves radar of an allyteam. For widgets, this is called just after a unit leaves radar coverage, so widgets cannot get the position of units that left their radar.
}}

{{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. Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and reclaim they are positive.
}}

{{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 = playerID, teamID, readyState, clampedX, clampedY, clampedZ, 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.
NB: The order of the parameters changed with the addition of {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

{{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". {{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]] or [[Lua_UnsyncedCtrl#SendLuaMessage|Spring.SendLuaUIMsg]].
}}

{{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
|I recommend looking up the CallIns in Sourcecode, because the Lua-Documentation, generated from the lua handle of them is seriously flawed and not regenerated.
|Lua-Handler documented from version
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynced.h#L106
|Actual CallIn:
|args = proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|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. The start and hit position arguments are provided from 104.0 onwards.
}}

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

Lua SyncedRead

2022-02-20T21:03:12Z

Beherith: /* Unit Informations */

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

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

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

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[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
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ). Also very important to note, that you can receive units that are 'already dead', when you do a Spring.GetAllUnits() call. These 'dead' units have already had their unitdestroyed callins called, and that will not get called again, and even more interestingly, these units are also valid, as in the above ValidUnitID callin will return true. The GetUnitIsDead howerver, will return true for these units, that are already dead but still valid units.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = Gets which team a unit belongs to. Note that this still returns the old team when called from the UnitTaken / UnitGiven callins.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets. And RAW returns an bitmask integer, where the bits are: 1: LOS_INLOS, the unit is currently in the los of the allyteam, 2: LOS_INRADAR the unit is currently in radar from the allyteam, 4: LOS_PREVLOS the unit has previously been in los from the allyteam, 8: LOS_CONTRADAR the unit has continuously been in radar since it was last inlos by the allyteam
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = 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 a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[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, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1 {{pipe}} {{type|number}} 255
|info = With x & z in worldspace coordinates. Returns 255 if grass is disabled in settings, or if map does not have a grassmap specified.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>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"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

Lua SyncedRead

2022-02-18T08:33:29Z

Beherith: /* Unit Informations */

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

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

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

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[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
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ). Also very important to note, that you can receive units that are 'already dead', when you do a Spring.GetAllUnits() call. These 'dead' units have already had their unitdestroyed callins called, and that will not get called again, and even more interestingly, these units are also valid, as in the above ValidUnitID callin will return true. The GetUnitIsDead howerver, will return true for these units, that are already dead but still valid units.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = Gets which team a unit belongs to. Note that this still returns the old team when called from the UnitTaken / UnitGiven callins.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = 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 a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[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, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1 {{pipe}} {{type|number}} 255
|info = With x & z in worldspace coordinates. Returns 255 if grass is disabled in settings, or if map does not have a grassmap specified.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>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"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

Lua UnsyncedRead

2022-01-23T20:08:23Z

Beherith: /* Time */

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

== Replay/Spectating ==

{{LuaCallout
|prefix = Spring.
|name = IsReplay
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isReplay
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetReplayLength
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} timeInSeconds
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetSpectatingState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} spectating, {{type|bool}} fullView, {{type|bool}} fullSelect
|info =
}}

== Game/Menu Name ==

{{LuaCallout
|prefix = Spring.
|name = GetGameName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}} Apparently returns {{xtaglink|Modinfo.lua|name}} .. {{xtaglink|Modinfo.lua|version}} from [[Modinfo.lua]]. E.g. "Spring: 1944 test-5640-ac2d15b".
}}

{{LuaCallout
|prefix = Spring.
|name = GetMenuName
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} name
|info = {{new|104.0}}
}}

== ModUI ==

{{LuaCallout
|prefix = Spring.
|name = GetModUICtrl
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} ModUICtrl
|info =
}}

== MyInfo ==

{{LuaCallout
|prefix = Spring.
|name = GetMyAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyTeamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMyPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

== Local Player,Team,Ally ==
Redundant same as the GetMyXYZ functions!

{{LuaCallout
|prefix = Spring.
|name = GetLocalPlayerID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playerID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetLocalAllyTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} allyID
|info =
}}

== Team/Player Info ==

{{LuaCallout
|prefix = Spring.
|name = GetPlayerRoster
|arg1 = {{bracket}}{{type|number}} sortType{{rbracket}} {{pipe}} {{bracket}}{{type|number}} sortType{{rbracket}}, {{bracket}}{{type|bool}} showPathingPlayers{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} playerTable
|info = "playerTable" contains:
}}
<pre>playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}

if pingTime == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamOrigColor
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b, {{type|number}} a
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerTraffic
|arg1 = {{type|number}} playerID {{bracket}}
|arg2 = {{type|number}} packetID {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} traffic
|info =
}}

== Sound ==

{{LuaCallout
|prefix = Spring.
|name = GetSoundStreamTime
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} playedTime, {{type|number}} totalTime,
|info =
}}

== Camera ==

{{LuaCallout
|prefix = Spring.
|name = GetCameraNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|camName}} = {{type|number}} camNum, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }
|info = See [[Lua_camState]] for details about Spring.GetCameraState output.
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraPosition
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraDirection
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} forward_x, {{type|number}} forward_y, {{type|number}} forward_z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraFOV
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} vFov, {{type|number}} hFov
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCameraVectors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} vectorTable
|info = vectorTable contains:
}}
<pre>vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}</pre>

=== Inview ===

{{LuaCallout
|prefix = Spring.
|name = GetVisibleUnits
|arg1 = {{bracket}}{{type|number}} teamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{rbracket}}{{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVisibleFeatures
|arg1 = {{bracket}}{{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|number}} radius = 30 {{bracket}}
|arg3 = {{type|bool}} Icons = true {{bracket}}
|arg4 = {{type|bool}} geos = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAABBInView
|arg1 = {{type|number}} minX, {{type|number}} minY, {{type|number}} minZ
|arg2 = {{type|number}} maxX, {{type|number}} maxY, {{type|number}} maxZ
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsSphereInView
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z {{bracket}}
|arg2 = {{type|number}} radius {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitIcon
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitIcon
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInView
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isUnitInView
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitVisible
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|bool}} checkIcons {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isVisible
|info =
}}

=== Screen Trace ===

{{LuaCallout
|prefix = Spring.
|name = WorldToScreenCoords
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = TraceScreenRay
|arg1 = {{type|number}} mouseX, {{type|number}} mouseY, {{bracket}}
|arg2 = {{type|bool}} onlyCoords {{bracket}}
|arg3 = {{type|bool}} useMinimap {{bracket}}
|arg4 = {{type|bool}} includeSky {{bracket}}
|arg5 = {{type|bool}} ignoreWater {{bracket}}
|arg6 ={{type|number}} D {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} unit, {{type|number}} unitID {{pipe}} {{type|string}} feature, {{type|number}} featureID {{pipe}} {{type|string}} ground, {{type|table}} coords = { {{bracket|1}} = {{type|number}} x, {{bracket|2}} = {{type|number}} y, {{bracket|3}} = {{type|number}} z }
|info = {{new|101.0}}
}}
<pre>Extended to allow a custom plane, parameters are (0, 1, 0, D=0) where D is the offset D can be specified in the third argument (if all the bools are false) or in the seventh (as shown). Intersection coordinates are returned in t[4],t[5],t[6] when the ray goes offmap and includeSky is true), or when no unit or feature is hit (or onlyCoords is true). This will only work for units & objects with the default collission sphere. Per Piece collission and custom collission objects are not supported. The unit must be selectable, to appear to a screen trace ray.

To get map coordinates under mouse cursor: input mouse coordinates obtained via GetMouseState() and pass true for the onlyCoords parameter. Be careful as going off map will result in nil:
local mouseX, mouseY = Spring.GetMouseState()
print ("Mouse coordinates: (" .. mouseX .. ", " .. mouseY .. ")")
local desc, args = Spring.TraceScreenRay(mouseX, mouseY, true)
if nil == desc then return end -- off map
local x = args[1]
local y = args[2]
local z = args[3]
print ("World coordinates: (" .. x .. ", " .. y .. ", " .. z .. ")")</pre>

{{LuaCallout
|prefix = Spring.
|name = GetPixelDir
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{New|95.0}}
}}

=== Screen & Window Geometry ===

{{LuaCallout
|prefix = Spring.
|name = GetViewGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} viewSizeX, {{type|number}} viewSizeY, {{type|number}} viewPosX, {{type|number}} viewPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWindowGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} winSizeX, {{type|number}} winSizeY, {{type|number}} winPosX, {{type|number}} winPosY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetScreenGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} screenSizeX, {{type|number}} screenSizeY, {{type|number}} ZERO, {{type|number}} ZERO
|info = Is missing multiscreen support!
}}

== Unit ==

{{LuaCallout
|prefix = Spring.
|name = IsUnitAllied
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitViewPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransformMatrix
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} invert = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} a11, {{type|number}} a12 ..., {{type|number}} a44 (4x4 matrix)
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

=== Selected Units ===

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsSorted
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{bracket}}{{type|number}} unitID{{rbracket}}, etc... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCounts
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedUnitsCount
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitSelected
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isSelected
|info =
}}

=== Unit Groups ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitGroup
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|number}} = {{type|number}} unitCount, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSelectedGroup
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} groupNumber
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIName
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} aiName
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupAIList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} aiName, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnits
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsSorted
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCounts
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroupUnitsCount
|arg1 = {{type|number}} groupID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

== Feature ==

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSelectionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetVisibleProjectiles
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{bracket}}
|arg2 = {{type|bool}} addSyncedProjectiles = true {{bracket}}
|arg3 = {{type|bool}} addWeaponProjectiles = true {{bracket}}
|arg4 = {{type|bool}} addPieceProjectiles = true {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} projectileID, ... }
|info =
}}

== UI ==

{{LuaCallout
|prefix = Spring.
|name = GetUICommands
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { command={{type|string}}, description={{type|string}}, synced={{type|bool}}, cheat={{type|bool}}}, ... }
|info = {{new|101.0}} Returns a list of available [[UI commands]].
}}

=== GUI Settings ===

{{LuaCallout
|prefix = Spring.
|name = IsGUIHidden
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isHidden
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveShadows
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShadows
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = HaveAdvShading
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} haveShading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetWaterMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|string}} mode
|info =
}}
<pre> mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown</pre>

{{LuaCallout
|prefix = Spring.
|name = GetMapDrawMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "normal" {{pipe}} {{type|string}} "height" {{pipe}} {{type|string}} "metal" {{pipe}} {{type|string}} "pathTraversability" {{pipe}} {{type|string}} "los"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawSelectionInfo
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} drawSelectInfo
|info = Returns whether "Selected units" text is displayed.
}}

=== Unit & Feature GUI States ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitLuaDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} unitDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoDraw
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoMinimap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noMinimap
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNoSelect
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLuaDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} featureDraw
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoDraw
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noDraw
|info =
}}

=== Minimap ===

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapGeometry
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} sizeX, {{type|number}} sizeY, {{type|bool}} minimized, {{type|bool}} maximized
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMiniMapDualScreen
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} false {{pipe}} {{type|string}} "left" {{pipe}} {{type|string}} "right"
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsAboveMiniMap
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAbove
|info =
}}

=== (Build-)Menu ===

{{LuaCallout
|prefix = Spring.
|name = GetActiveCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDefaultCommand
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index {{bracket}}, {{type|number}} cmd_id, {{type|number}} cmd_type, {{type|string}} cmd_name {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDescs
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
[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, .. }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActiveCmdDesc
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} cmdDesc
|info = cmdDesc contains:
}}
<pre>cmdDesc = {
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, .. }
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetCmdDescIndex
|arg1 = {{type|number}} cmdID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetActivePage
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pageNum, {{type|number}} maxPages
|info =
}}

=== Build Facing ===

{{LuaCallout
|prefix = Spring.
|name = GetBuildFacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetBuildSpacing
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spacing
|info =
}}

=== GatherMode & InvertQueueKey ===

{{LuaCallout
|prefix = Spring.
|name = GetGatherMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gatherMode
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetInvertQueueKey
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} queueKey
|info =
}}

=== Mouse States ===

{{LuaCallout
|prefix = Spring.
|name = GetMouseState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|bool}} leftPressed, {{type|bool}} middlePressed, {{type|bool}} rightPressed, {{type|bool}} offscreen
|info = {{new|104.0}} Sixth return value offscreen. X, Y are the screen coordinates, not world ones. This coordinate system starts in the lower left corner. For world coordinates see Spring.TraceScreenRay.
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseCursor
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string }} name, {{type|number}} scale
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMouseStartPosition
|arg1 = {{type|number}} mouseButton
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pressedX, {{type|number}} pressedY, {{type|number}} camPosX, {{type|number}} camPosY, {{type|number}} camPosZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

=== (Hot-)Keys ===

{{LuaCallout
|prefix = Spring.
|name = GetKeyState
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} keyState
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetModKeyState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} alt, {{type|bool}} ctrl, {{type|bool}} meta, {{type|bool}} shift
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPressedKeys
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket}}{{type|number}} code{{rbracket}} = {{type|bool}}, {{bracket}}{{type|string}} name{{rbracket}} = {{type|bool}}, ... }
|info = {{new|99.0}}: {{type|string}} name Returns the SDL1 codes for the pressed keys, first as an integer, a string containing the hex representation. Use Spring.[[Lua_UnsyncedRead#GetKeySymbol|GetKeySymbol]] to convert to an SDL2 symbol.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyCode
|arg1 = {{type|string}} keysym
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} keyCode
|info = Returns the SDL1 code for the SDL2 symbol
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeySymbol
|arg1 = {{type|number}} key
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "keysym1", {{type|string}} "keysym2"
|info = Converts an SDL1 keycode into an SDL2 keycode, represented as a hexadecimal string. For most cases, these values will be the same.
}}

{{LuaCallout
|prefix = Spring.
|name = GetKeyBindings
|arg1 = {{type|string}} keyset
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} keyBindings
|info = keyBindings contains:
}}
<pre>keyBindings = {
[1] = {
[string actionCmd] = string actionExtra,
command = string actionCmd, {{new|97}}
boundWith = string boundWith, {{new|97}}
extra = string actionExtra, {{new|97}}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetActionHotKeys
|arg1 = {{type|string}} action
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|string}} hotKey, ... }
|info =
}}

=== Console ===

{{LuaCallout
|prefix = Spring.
|name = GetLastMessagePositions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { {{type|number}} x, {{type|number}} y, {{type|number}} z }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConsoleBuffer
|arg1 = {{bracket}}{{type|number}} maxLines{{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = { text = {{type|string}}, priority = {{type|number}} }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCurrentTooltip
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} tooltip
|info =
}}

=== LOS Colors ===

{{LuaCallout
|prefix = Spring.
|name = GetLosViewColors
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} always = {r,g,b}, {{type|table}} LOS = {r,g,b}, {{type|table}} radar = {r,g,b}, {{type|table}} jam = {r,g,b}, {{type|table}} radar2 = {r,g,b}
|info = {{new|100}}
}}

== Config ==

{{LuaCallout
|prefix = Spring.
|name = GetConfigParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} configParams
|info = Same information as <code>spring --list-config-vars</code> configParams contains:
}}
<pre>configParams = {
{
name = string,
type = string,
[ description = string, ]
[ defaultValue = string, ]
[ minimumValue = string, ]
[ maximumValue = string, ]
[ safemodeValue = string, ]
[ declarationFile = string, ]
[ declarationLine = number, ]
[ readOnly = bool, ]
},
...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetConfigInt
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configInt
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigFloat
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} configFloat
|info = {{new|104.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetConfigString
|arg1 = {{type|string}} name {{bracket}}
|arg2 = {{type|number}} default {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} configString
|info =
}}

== FPS & GetDrawFrame ==

{{LuaCallout
|prefix = Spring.
|name = GetFPS
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} fps
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetDrawFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} low_16bit, {{type|number}} high_16bit
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVideoCapturingMode
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} videoCaptureAllowed
|info = {{new|104.0}}
}}

== Time ==

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = {{new|98.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} finishedLoading, {{type|bool}} loadedFromSave, {{type|bool}} locallyPaused, {{type|bool}} laggingWrtExpectedFromSimtime
|info = {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimeOffset
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} offset
|info = Gets globalRendering->timeOffset, which contains the offset of the current draw frame from the last sim frame, expressed in fractions of a frame. Ideally, when running 30hz sim, and 60hz rendering, the draw frames should have and offset of either 0.0 frames, or 0.5 frames. When draw frames are not integer multiples of sim frames, some interpolation happens, and this timeoffset shows how far along it is.
}}

{{LuaCallout
|prefix = Spring.
|name = GetLastUpdateSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lastUpdateSeconds
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHasLag
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasLag
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFrameTimer
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|timer}}
|info = {{new|102.0}} Get a timer for the start of the frame, this should give better results for camera interpolations.
}}

{{LuaCallout
|prefix = Spring.
|name = DiffTimers
|arg1 = {{type|timer}} cur
|arg2 = {{type|timer}} ago {{bracket}}
|arg3 = {{type|bool}} inMilliseconds {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info = {{New|95.0}} Optional third argument (boolean) to return dt in milliseconds.
}}

== Rendering ==

{{LuaCallout
|prefix = Spring.
|name = GetMapSquareTexture
|arg1 = {{type|number}} texSqrX, {{type|number}} texSqrY
|arg2 = {{type|number}} texMipLvl
|arg3 = {{type|string}} luaTexName
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}

== Logging ==

{{LuaCallout
|prefix = Spring.
|name = GetLogSections
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} logSections = { "KeyBindings" = LOG.INFO, "Font" = LOG.INFO, "Sound" = LOG.WARNING, ... }
|info =
}}

== Misc ==

{{LuaCallout
|prefix = Spring.
|name = GetClipboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} text
|info = {{new|98.0}}
}}

[[category: Lua]]

Lua VFS

2022-01-14T11:17:23Z

Beherith: /* Files */

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

= Overview =

Although Spring can access the filesystem directly (via os module) it is more common that you
would want to access files included with your game or Spring. Trouble is, most of these files are
compressed into archives (.sdz/.sd7) so random access would generally be a difficult procedure.
Fortunately, the Spring Lua system automatically provides access to mod and base files via the VFS module.

The VFS module doesn't simply open archives though. What it does is map your game files, game
dependencies and Spring content onto a virtual file tree. All archives start from the 'roots' of the tree
and share the same virtual space, meaning that if two or more archives contain the same resource
file name the resources overlap and only one of the files will be retrieved. Overlapping directories
on the other hand are merged so the resulting virtual directory contains the contents of both. Here is
an example of how this works:

'''Archive 1 (games/mygame.sd7)'''

textures 
|__ texture1.png 
models 
|__ model1.mdl 

'''Archive 2 (base/springcontent.sdz'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 

'''VFS'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 
models 
|__ model1.mdl 

This raises the question: If both archives have a texture1.png then which texture1.png is retreived
via the VFS? The answer depends on the order the archives are loaded and the VFS mode (more on
modes below). Generally however, each archive loaded overrides any archives loaded
before it. The standard order of loading (from first to last) is:

# The main Spring/ game directory.
# The automatic dependencies springcontent.sdz and maphelper.sdz.
# Dependencies listed in your modinfo.lua (or modinfo.tdf), in the order listed.
# Your mod archive.

= Modes =

These modes are constants passed to VFS.Include() and friends to control the order that archives are
searched for a given file. They are case-sensitive.

'''VFS.RAW''' Only select uncompressed files.

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

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

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

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

'''VFS.ZIP''' Only select compressed files (.sdz,.sd7).

'''VFS.RAW_FIRST''' Try uncompressed files first, then compressed.

'''VFS.ZIP_FIRST''' Try compressed files first, then uncompressed.

'''VFS.RAW_ONLY''' (Deprecated. Same as VFS.RAW)

'''VFS.ZIP_ONLY''' (Deprecated. Same as VFS.ZIP.)

See also: https://github.com/spring/spring/blob/develop/rts/System/FileSystem/VFSModes.h

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

If nil then the env will be _G (global environment) If the optional env argument is provided any non-local variables and functions defined in
filename.lua are then accessable via env or _G. Vise-versa, any variables defined in env prior to
passing to VFS.Include are available to code in the included file. Code running in filename.lua will
see the contents of env in place of the normal _G environment. 

This loads and compiles the lua code from a file in the VFS. The path is relative to the main Spring directory, e.g. VFS.Include('LuaUI/includes/filename.lua', nil, [vfsmode]) 

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

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

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

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

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

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

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

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

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

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

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

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

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

= Archives =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''VFS.PackU8'''

'''VFS.PackU16'''

'''VFS.PackU32'''

'''VFS.PackS8'''

'''VFS.PackS16'''

'''VFS.PackS32'''

'''VFS.PackF32'''

arguments are:

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

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

'''VFS.UnpackU8'''

'''VFS.UnpackU16'''

'''VFS.UnpackU32'''

'''VFS.UnpackS8'''

'''VFS.UnpackS16'''

'''VFS.UnpackS32'''

'''VFS.UnpackF32'''

arguments are:

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

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

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

[[category: Lua]]

Lua VFS

2022-01-14T11:13:41Z

Beherith:

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

= Overview =

Although Spring can access the filesystem directly (via os module) it is more common that you
would want to access files included with your game or Spring. Trouble is, most of these files are
compressed into archives (.sdz/.sd7) so random access would generally be a difficult procedure.
Fortunately, the Spring Lua system automatically provides access to mod and base files via the VFS module.

The VFS module doesn't simply open archives though. What it does is map your game files, game
dependencies and Spring content onto a virtual file tree. All archives start from the 'roots' of the tree
and share the same virtual space, meaning that if two or more archives contain the same resource
file name the resources overlap and only one of the files will be retrieved. Overlapping directories
on the other hand are merged so the resulting virtual directory contains the contents of both. Here is
an example of how this works:

'''Archive 1 (games/mygame.sd7)'''

textures 
|__ texture1.png 
models 
|__ model1.mdl 

'''Archive 2 (base/springcontent.sdz'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 

'''VFS'''

textures 
|__ texture1.png 
|__ texture2.png 
|__ texture3.png 
models 
|__ model1.mdl 

This raises the question: If both archives have a texture1.png then which texture1.png is retreived
via the VFS? The answer depends on the order the archives are loaded and the VFS mode (more on
modes below). Generally however, each archive loaded overrides any archives loaded
before it. The standard order of loading (from first to last) is:

# The main Spring/ game directory.
# The automatic dependencies springcontent.sdz and maphelper.sdz.
# Dependencies listed in your modinfo.lua (or modinfo.tdf), in the order listed.
# Your mod archive.

= Modes =

These modes are constants passed to VFS.Include() and friends to control the order that archives are
searched for a given file. They are case-sensitive.

'''VFS.RAW''' Only select uncompressed files.

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

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

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

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

'''VFS.ZIP''' Only select compressed files (.sdz,.sd7).

'''VFS.RAW_FIRST''' Try uncompressed files first, then compressed.

'''VFS.ZIP_FIRST''' Try compressed files first, then uncompressed.

'''VFS.RAW_ONLY''' (Deprecated. Same as VFS.RAW)

'''VFS.ZIP_ONLY''' (Deprecated. Same as VFS.ZIP.)

See also: https://github.com/spring/spring/blob/develop/rts/System/FileSystem/VFSModes.h

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

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

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

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

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

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

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

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

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

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

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

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

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

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

= Archives =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''VFS.PackU8'''

'''VFS.PackU16'''

'''VFS.PackU32'''

'''VFS.PackS8'''

'''VFS.PackS16'''

'''VFS.PackS32'''

'''VFS.PackF32'''

arguments are:

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

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

'''VFS.UnpackU8'''

'''VFS.UnpackU16'''

'''VFS.UnpackU32'''

'''VFS.UnpackS8'''

'''VFS.UnpackS16'''

'''VFS.UnpackS32'''

'''VFS.UnpackF32'''

arguments are:

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

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

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

[[category: Lua]]

Lua VFS

2022-01-14T11:05:32Z

Beherith: /* Modes */

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

= Modes =

These modes are constants passed to VFS.Include() and friends to control the order that archives are
searched for a given file. They are case-sensitive.

'''VFS.RAW''' Only select uncompressed files.

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

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

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

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

'''VFS.ZIP''' Only select compressed files (.sdz,.sd7).

'''VFS.RAW_FIRST''' Try uncompressed files first, then compressed.

'''VFS.ZIP_FIRST''' Try compressed files first, then uncompressed.

'''VFS.RAW_ONLY''' (Deprecated. Same as VFS.RAW)

'''VFS.ZIP_ONLY''' (Deprecated. Same as VFS.ZIP.)

See also: https://github.com/spring/spring/blob/develop/rts/System/FileSystem/VFSModes.h

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

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

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

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

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

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

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

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

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

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

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

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

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

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

= Archives =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''VFS.PackU8'''

'''VFS.PackU16'''

'''VFS.PackU32'''

'''VFS.PackS8'''

'''VFS.PackS16'''

'''VFS.PackS32'''

'''VFS.PackF32'''

arguments are:

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

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

'''VFS.UnpackU8'''

'''VFS.UnpackU16'''

'''VFS.UnpackU32'''

'''VFS.UnpackS8'''

'''VFS.UnpackS16'''

'''VFS.UnpackS32'''

'''VFS.UnpackF32'''

arguments are:

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

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

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

[[category: Lua]]

Lua SyncedRead

2021-12-14T13:11:15Z

Beherith: /* Unit Informations */

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

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

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

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[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
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ). Also very important to note, that you can receive units that are 'already dead', when you do a Spring.GetAllUnits() call. These 'dead' units have already had their unitdestroyed callins called, and that will not get called again, and even more interestingly, these units are also valid, as in the above ValidUnitID callin will return true. The GetUnitIsDead howerver, will return true for these units, that are already dead but still valid units.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = 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 a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[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, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1 {{pipe}} {{type|number}} 255
|info = With x & z in worldspace coordinates. Returns 255 if grass is disabled in settings, or if map does not have a grassmap specified.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>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"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

Lua OpenGL Api

2021-11-30T15:26:26Z

Beherith: /* Textures */

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

= Spring =

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "pos"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "shadowDensity" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shadowDensity
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "diffuse" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "ambient" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "specular" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetAtmosphere
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} r, {{type|number}} g, {{type|number}} b
|info = {{new|101.0}} See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetWaterRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|string}} texName {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetMapRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = ConfigScreen
|arg1 = {{type|number}} screenWidth
|arg2 = {{type|number}} screenDistance
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used for Unit LODs.
}}

{{LuaCallout
|prefix = gl.
|name = DrawMiniMap
|arg1 = {{type|bool}} transform = true
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SlaveMiniMap
|arg1 = {{type|bool}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ConfigMiniMap
|arg1 = {{type|number}} intPX
|arg2 = {{type|number}} intPY
|arg3 = {{type|number}} intSX
|arg4 = {{type|number}} intSY
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetViewSizes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y
|info =
}}

= Matrices & Viewport =

{{LuaCallout
|prefix = gl.
|name = Viewport
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Translate
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} angle
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Billboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this to draw 2d primitives in DrawWorld().
}}
<pre>To render a 2D billboarded quad in the gameworld at world position x,y,z, you do the following (at a minimum; I am skipping blending / depthtesting) here:
gl.PushMatrix()
gl.Texture(read what you need here)
gl.Translate(x,y,z)
gl.Billboard()
gl.TexRect(x1,y1,x2,y2)
gl.PopMatrix()</pre>

{{LuaCallout
|prefix = gl.
|name = MatrixMode
|arg1 = {{type|number}} [[Lua_ConstGL#MatrixMode|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadIdentity
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadMatrix
|arg1 = 16 {{type|numbers}} or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Ortho
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Frustum
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushPopMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ClipPlane
|arg1 = {{type|number}} intPlane
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} A, {{type|number}} B, {{type|number}} C, {{type|number}} D
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: intPlane can only be 1 or 2.
}}

= Clear =

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.DEPTH_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} cleardepth {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.STENCIL_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} intClearStencil {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.COLOR_BUFFER_BIT}} {{pipe}} {{type|GL.ACCUM_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 = {{type|number}} a {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SwapBuffers
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.
}}

= ResetState/Matrices =

{{LuaCallout
|prefix = gl.
|name = ResetState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = DON'T USE IT UNLESS YOU KNOW WHAT YOU ARE DOING! Each call-in has different default states, but this function resets all states to the states below no matter what!
}}
<pre> ShadeModel = GL.SMOOTH
Scissor = false
Texture = false
Lighting = false,
ColorMask = true, true, true, true
DepthMask = false
DepthTest = false (GL.LEQUAL)
Culling = false (GL.BACK)
LogicOp = false (GL.INVERT)
AlphaTest = false (GL.GREATER, 0.5f)
Blending = true (GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA)</pre>

{{LuaCallout
|prefix = gl.
|name = ResetMatrices
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack</pre>

= Draw Basics =

{{LuaCallout
|prefix = gl.
|name = BeginEnd
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLType]]
|arg2 = {{type|function}} {{bracket}}
|arg3 = arg1
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Color
|arg1 = {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} {{pipe}} {{type|table}} colors = { {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|table}} vertex = { {{type|number}} x, {{type|number}} y, {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} w
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Normal
|arg1 = {{type|table}} normal = { {{type|number}} x, {{type|number}} y, {{type|number}} z } {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Rect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexRect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2 {{bracket}}
|arg5 = {{type|bool}} flip_s, {{type|bool}} flip_t {{pipe}} {{type|number}} s1, {{type|number}} t1, {{type|number}} s2, {{type|number}} t2 {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Texture rect.
}}

{{LuaCallout
|prefix = gl.
|name = Shape
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLtype]]
|arg2 = {{type|table}} elements
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Elements contains:
}}
<pre> elements = {
[1] = { v | vertex = { number x, number y, number z }, required
n | normal = { number x, number y, number z }, optional
t | texcoord = { number x, number y }, optional
c | color = { number r, number g, number b, number a } optional
},
etc ...
}</pre>

{{LuaCallout
|prefix = gl.
|name = SecondaryColor
|arg1 = {{type|table}} color = { {{type|number}} r, {{type|number}} g, {{type|number}} b } {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FogCoord
|arg1 = {{type|number}} value
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Display Lists =
Display Lists save given vertex attributes in a static buffer, so the GPU can directly read them (without the CPU). Display Lists are a lot faster (10-60x) than standard drawing with glShape/glBeginEnd, so try to use them when ever you can. If you want to learn more about them, g00gle is your friend ;)

{{LuaCallout
|prefix = gl.
|name = CreateList
|arg1 = {{type|function}} {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 ... {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} listID
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CallList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

{{LuaCallout
|prefix = gl.
|name = CreateVertexArray
|arg1 = {{type|number}} numElements
|arg2 = {{type|number}} numIndices {{bracket}}
|arg3 = {{type|bool}} persistentBuffer = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} bufferID
|info =
}}
<pre>See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry.</pre>

{{LuaCallout
|prefix = gl.
|name = UpdateVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} elementPos
|arg3 = {{type|number}} indexPos
|arg4 = {{type|table}} tbl {{pipe}} {{type|function}} func
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data
4 elements table example:
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }

Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices.</pre>

{{LuaCallout
|prefix = gl.
|name = RenderVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} primType {{bracket}}
|arg3 = {{type|number}} firstIndex = 0
|arg4 = {{type|number}} count = numElements {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES
firstIndex specifies the starting index in the enabled arrays.
count specifies the number of indices to be rendered.</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteVertexArray
|arg1 = {{type|number}} bufferID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Releases previously allocated VAO
}}

= Text =

{{LuaCallout
|prefix = gl.
|name = Text
|arg1 = {{type|string}} "text"
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} size {{bracket}}
|arg5 = {{type|string}} "options" {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> options are:
horizontal alignment:
'c' = center
'r' = right
vertical alignment:
'a' = ascender
't' = top
'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)</pre>

{{LuaCallout
|prefix = gl.
|name = GetTextWidth
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} width
|info = Width in pixels, with a font size of 1.0.
}}

{{LuaCallout
|prefix = gl.
|name = GetTextHeight
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height, {{type|number}} descender, {{type|number}} numlines
|info = Height in pixels, with a font size of 1.0. Further descriptions here: [[GetTextHeight]]
}}

{{LuaCallout
|prefix = gl.
|name = BeginText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering.
}}

{{LuaCallout
|prefix = gl.
|name = EndText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Unit/Feature Draw Functions =

{{LuaCallout
|prefix = gl.
|name = Unit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws a unit - on default it uses LOD, with lod<0 it is turned off, else it defines a specific level.
}}

{{LuaCallout
|prefix = gl.
|name = UnitRaw
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Doesn't apply worldspace->unit transformation! only works if rawdraw is true.
}}

{{LuaCallout
|prefix = gl.
|name = UnitShape
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} rawState
|arg4 = {{type|bool}} toScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.
}}

{{LuaCallout
|prefix = gl.
|name = UnitMultMatrix
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = world space -> unit space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMultMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = unit space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPiece
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws the unit piece.
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use gl.UnitPieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = Feature
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureRaw
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShape
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} custom
|arg4 = {{type|bool}} drawScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureMultMatrix
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} world space -> feature space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMultMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} feature space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePiece
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Draws the Feature piece.
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Use gl.FeaturePieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = DrawListAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} listID {{bracket}}
|arg3 = {{type|bool}} midPos
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} degrees
|arg6 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DrawFuncAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} midPos
|arg3 = {{type|function}} {{bracket}}, arg1, ... {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= States (Blending,AlphaTest...) =

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|string}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Mode can be set to:
}}
<pre>"add"
= GL.ONE, GL.ONE

"alpha_add"
= GL.SRC_ALPHA, GL.ONE

"alpha"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"reset"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"color"
= GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA

"modulate"
= GL.DST_COLOR, GL.ZERO

"disable"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA</pre>

{{LuaCallout
|prefix = gl.
|name = BlendEquation
|arg1 = {{type|number}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendFunc
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendEquationSeparate
|arg1 = {{type|number}} modeRGB
|arg2 = {{type|number}} modeAlpha
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = BlendFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcRGB]]
|arg2 = {{type|number}} [Lua_ConstGL#BlendingFactorDest|dstRGB]]
|arg3 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]]
|arg4 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstAlpha]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = AlphaTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 = {{type|number}} threshold
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Culling
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthClamp
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Not always available, needs GL.NV_depth_clamp!
}}

{{LuaCallout
|prefix = gl.
|name = DepthMask
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} masked
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} r, {{type|bool}} g, {{type|bool}} b, {{type|bool}} a
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LogicOp
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#LogicOp|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Fog
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Smoothing
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} point
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} line
|arg3 = {{type|bool}} enable {{pipe}} {{type|number}} polygon
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|number}} intX, {{type|number}} intY, {{type|number}} intW, {{type|number}} intH
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|string}} any
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use springs default line stipple.
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|number}} intFactor
|arg2 = {{type|number}} pattern
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonMode
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} [[Lua_ConstGL#PolygonMode|mode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonOffset
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} factor
|arg2 = {{type|number}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushAttrib
|arg1 = {{bracket}} {{type|number}} [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopAttrib
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Stencil =

{{LuaCallout
|prefix = gl.
|name = StencilTest
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMask
|arg1 = {{type|number}} mask
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilFunc
|arg1 = {{type|number}} func
|arg2 = {{type|number}} ref
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilOp
|arg1 = {{type|number}} fail
|arg2 = {{type|number}} zfail
|arg3 = {{type|number}} zpass
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMaskSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} mask
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} func
|arg3 = {{type|number}} ref
|arg4 = {{type|number}} mask
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilOpSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} fail
|arg3 = {{type|number}} zfail
|arg4 = {{type|number}} zpass
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= LineWidth & PointSize =

{{LuaCallout
|prefix = gl.
|name = LineWidth
|arg1 = {{type|number}} width
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PointSize
|arg1 = {{type|number}} size
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390
}}

{{LuaCallout
|prefix = gl.
|name = PointSprite
|arg1 = {{type|bool}} enable {{bracket}}
|arg2 = {{type|bool}} coord_replace
|arg3 = {{type|bool}} coord_origin_upper {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = PointParameter
|arg1 = {{type|number}} v1, {{type|number}} v2, {{type|number}} v3 {{bracket}}
|arg2 = {{type|number}} sizeMin
|arg3 = {{type|number}} sizeMax
|arg4 = {{type|number}} sizeFade {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= Textures =

{{LuaCallout
|prefix = gl.
|name = Texture
|arg1 = {{bracket}} {{type|number}} texNum, {{rbracket}} {{type|bool}} enable {{pipe}} {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} loaded
|info = This is the only call-out that is needed to load and draw any texture in a Lua script. All you have to do is pass it a valid path to a valid png and it will use that image for drawing any subsequent textured rectangles. This is shown in the last line of the following list of valid strings for the name parameter.
}}
name may be:

#12
= unitDef 12 buildpic

%34:1
= unitDef 34 s3o tex2 (:0->tex1,:1->tex2)

%-102:0
= featureDef 102 s3o tex1

!56
= lua generated texture 56 (= return value of gl.CreateTexture)

$units
= 3do textureatlas tex1

$units1
= 3do textureatlas tex1

$units2
= 3do textureatlas tex2

$shadow
= shadowmap

$specular
= specular cube map (removed in the latest develop)

$reflection
= reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)

$shading
= ground shading texture

$grass
= grass shading texture

$heightmap
= heightmap, the height in elmos is in the R channel (needs HeightMapTexture=1 set in spring config)

$minimap
= minimap texture

$map_reflection
= same as "$reflection" {{new|101.0}}

$sky_reflection
= defined for SSMF maps that have a skyReflectModTex {{new|101.0}}

$detail
= detail texture {{new|101.0}}

$normals
= auto generated normals texture, X normal component is in r,g and b channels, Z normal component is in the A channel. If you need Y you'll need to reconstruct it form X and Z. {{new|101.0}}

$ssmf_normals
= SSMF normals texture {{new|101.0}}

$ssmf_specular
= SSMF specular texture {{new|101.0}}

$ssmf_splat_distr
= SSMF splat distribution texture {{new|101.0}}

$ssmf_splat_detail
= SSMF splat detail texture {{new|101.0}}

$ssmf_splat_normals
= SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted

$ssmf_emission
= SSMF emission texture {{new|101.0}}

$ssmf_parallax
= SSMF parallax texture {{new|101.0}}

$info
= currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale

$info_losmap
= los texture (L-view)

$info_mtlmap
= metal map texture (F4-view)

$info_hgtmap
= height map texture (F1-view)

$info_blkmap
= blocking map texture (F2-view)

$map_gbuffer_normtex
= contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$map_gbuffer_difftex
= contains the diffuse texture buffer of the map in view {{new|95}}

$map_gbuffer_spectex
= contains the specular textures of the map in view {{new|95}}

$map_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$map_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$map_gbuffer_zvaltex
= contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use:

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;

$model_gbuffer_normtex
= contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$model_gbuffer_difftex
= contains the diffuse texture buffer of the models in view {{new|95}}

$model_gbuffer_spectex
= contains the specular textures of the models in view {{new|95}}

$model_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$model_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$model_gbuffer_zvaltex
= contains the depth values (z-buffer) of the models in view. {{new|95}}

${opt}:/LuaUI/images/image.png
= load a texture from the VFS

possible ${opt}'s are:
'n' = nearest
'l' = linear
'a' = aniso
'i' = invert
'g' = greyed
'c' = clamped
'b' = border
't%r,%g,%b' = tint
'r%width,%height' = resize
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

example: ":iac:/LuaUI/images/image.png"
example: ":cr16,16:/LuaUI/images/image.png"
example2: ":t1.0,0.5,0:/LuaUI/images/image.png" (orange tint)


{{LuaCallout
|prefix = gl.
|name = CreateTexture
|arg1 = {{type|number}} intXSize
|arg2 = {{type|number}} intYSize {{bracket}}
|arg3 = {{type|table}} texProps {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} texture
|info = texProps contains:
}}
<pre>texProps = {
[target = number,](like GL.TEXTURE_1D,GL.TEXTURE_2D,...)(Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[format = number,]
[min_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[mag_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[wrap_s = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_t = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_r = [[Lua_ConstGL#Texture_Clamping|number]],]
[aniso = number,]
[border = boolean,]
[fbo = boolean,] (needs GLEW_EXT_framebuffer_object!)
[fboDepth = boolean,] (needs GLEW_EXT_framebuffer_object!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
}</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteTexture
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteTextureFBO
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = TextureInfo
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} texInfo
|info = texInfo contains:
}}
<pre> texInfo = {
xsize = number,
ysize = number,
alpha = boolean, //not used yet
type = number, //not used yet
}

The format of the texture string is the same as in gl.Texture().</pre>

{{LuaCallout
|prefix = gl.
|name = MultiTexCoord
|arg1 = {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} {{pipe}} {{type|table}} texCoords = { {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} state
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|bool}} state
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CopyToTexture
|arg1 = {{type|string}} texture
|arg2 = {{type|number}} intXOff
|arg3 = {{type|number}} intYOff
|arg4 = {{type|number}} intX
|arg5 = {{type|number}} intY
|arg6 = {{type|number}} intW
|arg7 = {{type|number}} intH {{bracket}}
|arg8 = {{type|number}} target
|arg9 = {{type|number}} level {{rbracket}}
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = RenderToTexture
|arg1 = {{type|string}} fbotexture
|arg2 = {{type|function}} lua_func
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = GenerateMipmap
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} created
|info = Needs glGenerateMipmapEXT!
}}
<pre>The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")</pre>

{{LuaCallout
|prefix = gl.
|name = UnitTextures
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = UnitShapeTextures
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureTextures
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShapeTextures
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

= PixelReadback =

{{LuaCallout
|prefix = gl.
|name = SaveImage
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 = {{type|string}} filename {{bracket}}
|arg6 = {{type|table}} imgProps = { alpha={{type|bool}}, yflip={{type|bool}}, grayscale16bit={{type|bool}}, readbuffer={{type|number}} } {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index
}}

{{LuaCallout
|prefix = gl.
|name = ReadPixels
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h {{bracket}}
|arg5 = {{type|number}} format = GL.RGBA {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r {{bracket}}, g {{bracket}}, b {{bracket}}, a {rbracket}}{rbracket}}{rbracket}} {{pipe}} {{type|table}} readPixels = { { { 1 = {{type|number}} r, 2 = {{type|number}} g, 3 = {{type|number}} b, 4 = {{type|number}} a}, ... }, ... }
|info = This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.
}}

= Lights =

{{LuaCallout
|prefix = gl.
|name = Lighting
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ShadeModel
|arg1 = {{type|number}} [[Lua_ConstGL#ShadeModel|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|number}} [[Lua_ConstGL#Light_Specification|pname]]
|arg3 = {{type|number}} param
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|number}} [[Lua_ConstGL#Light_Specification|pname]]
|arg3 = {{type|number}} param1
|arg4 = {{type|number}} param2
|arg5 = {{type|number}} param3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Material
|arg1 = {{type|table}} material
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = material contains:
}}
<pre>material = {
ambient = {number r, number g, number b[, number a]},
diffuse = {number r, number g, number b[, number a]},
ambidiff = {number r, number g, number b[, number a]},
emission = {number r, number g, number b[, number a]},
specular = {number r, number g, number b[, number a]},
shininess = number specularExponent
}</pre>

= Hardware relevant =

{{LuaCallout
|prefix = gl.
|name = HasExtension
|arg1 = {{type|string}} extname
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasExtension
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetNumber
|arg1 = {{type|number}} ext
|arg2 = {{type|number}} intCount
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} number1 {{bracket}}, {{type|number}} number2, {{type|number}} number3, ... #count {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetString
|arg1 = {{type|number}} ext
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} extString
|info =
}}

= DrawGroundPrimitives =

{{LuaCallout
|prefix = gl.
|name = DrawGroundCircle
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 = {{type|number}} divs {{bracket}}
|arg6 = {{type|number}} slope {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: Number divs is the number of sides the circle will have. The higher the smoother the circle (and more GPU intensive).
}}

{{LuaCallout
|prefix = gl.
|name = DrawGroundQuad
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{bracket}}
|arg5 = {{type|bool}} useNorm {{bracket}}
|arg6 = {{type|number}} tu1, {{type|number}} tv1
|arg7 = {{type|number}} tu2, {{type|number}} tv2 {{rbracket}} {{pipe}} {{bracket}} {{type|bool}} useTextureCoord {{rbracket}} {{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: x1, z1, x2 & z2 are rounded, so don't use it for very small or moving objects. x and z correspond to the coordinates displayed by the tooltip. Also note: useNorm does nothing!
}}

= Queries =

{{LuaCallout
|prefix = gl.
|name = CreateQuery
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|userdata}} query
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = DeleteQuery
|arg1 = {{type|userdata}} query
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = RunQuery
|arg1 = {{type|userdata}} query
|arg2 = {{type|function}} func
|arg3 = {{type|arg1}}
|arg4 = {{type|arg2}}
|arg5 = ...
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = GetQuery
|arg1 = {{type|userdata}} query
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} renderedFragments
|info =
}}

= Extended =

{{LuaCallout
|prefix = gl.
|name = ActiveTexture
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|function}} func {{bracket}}
|arg3 = {{type|arg1}}
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetGlobalTexNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} texNames = { {{bracket|1}} = {{type|string}} texture, etc ... }
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetGlobalTexCoords
|arg1 = {{type|string}} 3doTextureName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} xstart, {{type|number}} ystart, {{type|number}} xend, {{type|number}} yend
|info = Gets the texcoord of a 3do texture in the 3do texture atlas.
}}

{{LuaCallout
|prefix = gl.
|name = UnsafeState
|arg1 = {{type|number}} state {{bracket}}
|arg2 = {{type|bool}} disable_state {{rbracket}}
|arg3 = {{type|bool}} func
|arg4 = {{type|arg1}}
|arg5 = {{type|arg2}}
|arg6 = ...
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Calls glEnable(state) or glDisable(state) (if disable_state==true) and then calls the lua_function and afterwards reverts the state.
}}

{{LuaCallout
|prefix = gl.
|name = GetShadowMapParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} xmid, {{type|number}} ymid, {{type|number}} p17, {{type|number}} p18
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.PROJECTION {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.MODELVIEW {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.TEXTURE {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "shadow"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "camera"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}
{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "caminv"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "camprj"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "billboard"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Flush
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Finish
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Shaders (GLSL) =
[[Lua_GLSL_Api]]

[[category: Lua]]

Lua OpenGL Api

2021-11-30T15:24:45Z

Beherith: /* Textures */

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

= Spring =

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "pos"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sunPosX, {{type|number}} sunPosY, {{type|number}} sunPosZ
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "shadowDensity" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} shadowDensity
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "diffuse" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "ambient" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetSun
|arg1 = {{type|string}} "specular" {{bracket}}
|arg2 = {{type|string}} "unit" {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetAtmosphere
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} r, {{type|number}} g, {{type|number}} b
|info = {{new|101.0}} See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetWaterRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|string}} texName {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = GetMapRendering
|arg1 = {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b {{pipe}} {{type|bool}} active
|info = {{new|104.0}} See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.
}}

{{LuaCallout
|prefix = gl.
|name = ConfigScreen
|arg1 = {{type|number}} screenWidth
|arg2 = {{type|number}} screenDistance
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Used for Unit LODs.
}}

{{LuaCallout
|prefix = gl.
|name = DrawMiniMap
|arg1 = {{type|bool}} transform = true
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SlaveMiniMap
|arg1 = {{type|bool}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ConfigMiniMap
|arg1 = {{type|number}} intPX
|arg2 = {{type|number}} intPY
|arg3 = {{type|number}} intSX
|arg4 = {{type|number}} intSY
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetViewSizes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y
|info =
}}

= Matrices & Viewport =

{{LuaCallout
|prefix = gl.
|name = Viewport
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopMatrix
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Translate
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scale
|arg1 = {{type|number}} angle
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Billboard
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use this to draw 2d primitives in DrawWorld().
}}
<pre>To render a 2D billboarded quad in the gameworld at world position x,y,z, you do the following (at a minimum; I am skipping blending / depthtesting) here:
gl.PushMatrix()
gl.Texture(read what you need here)
gl.Translate(x,y,z)
gl.Billboard()
gl.TexRect(x1,y1,x2,y2)
gl.PopMatrix()</pre>

{{LuaCallout
|prefix = gl.
|name = MatrixMode
|arg1 = {{type|number}} [[Lua_ConstGL#MatrixMode|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadIdentity
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LoadMatrix
|arg1 = 16 {{type|numbers}} or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Ortho
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Frustum
|arg1 = {{type|number}} left
|arg2 = {{type|number}} right
|arg3 = {{type|number}} bottom
|arg4 = {{type|number}} top
|arg5 = {{type|number}} near
|arg6 = {{type|number}} far
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushPopMatrix
|arg1 = ???
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = ???
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ClipPlane
|arg1 = {{type|number}} intPlane
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} A, {{type|number}} B, {{type|number}} C, {{type|number}} D
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: intPlane can only be 1 or 2.
}}

= Clear =

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.DEPTH_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} cleardepth {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.STENCIL_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} intClearStencil {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Clear
|arg1 = {{type|GL.COLOR_BUFFER_BIT}} {{pipe}} {{type|GL.ACCUM_BUFFER_BIT}} {{bracket}}
|arg2 = {{type|number}} r
|arg3 = {{type|number}} g
|arg4 = {{type|number}} b
|arg5 = {{type|number}} a {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = SwapBuffers
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|104.0}} Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.
}}

= ResetState/Matrices =

{{LuaCallout
|prefix = gl.
|name = ResetState
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = DON'T USE IT UNLESS YOU KNOW WHAT YOU ARE DOING! Each call-in has different default states, but this function resets all states to the states below no matter what!
}}
<pre> ShadeModel = GL.SMOOTH
Scissor = false
Texture = false
Lighting = false,
ColorMask = true, true, true, true
DepthMask = false
DepthTest = false (GL.LEQUAL)
Culling = false (GL.BACK)
LogicOp = false (GL.INVERT)
AlphaTest = false (GL.GREATER, 0.5f)
Blending = true (GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA)</pre>

{{LuaCallout
|prefix = gl.
|name = ResetMatrices
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack</pre>

= Draw Basics =

{{LuaCallout
|prefix = gl.
|name = BeginEnd
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLType]]
|arg2 = {{type|function}} {{bracket}}
|arg3 = arg1
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Color
|arg1 = {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} {{pipe}} {{type|table}} colors = { {{type|number}} r, {{type|number}} g, {{type|number}} b {{bracket}}, {{type|number}} a {{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|table}} vertex = { {{type|number}} x, {{type|number}} y, {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Vertex
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} w
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Normal
|arg1 = {{type|table}} normal = { {{type|number}} x, {{type|number}} y, {{type|number}} z } {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Rect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexRect
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} y1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} y2 {{bracket}}
|arg5 = {{type|bool}} flip_s, {{type|bool}} flip_t {{pipe}} {{type|number}} s1, {{type|number}} t1, {{type|number}} s2, {{type|number}} t2 {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Texture rect.
}}

{{LuaCallout
|prefix = gl.
|name = Shape
|arg1 = {{type|number}} [[Lua_ConstGL#Drawing_Primitives|GLtype]]
|arg2 = {{type|table}} elements
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Elements contains:
}}
<pre> elements = {
[1] = { v | vertex = { number x, number y, number z }, required
n | normal = { number x, number y, number z }, optional
t | texcoord = { number x, number y }, optional
c | color = { number r, number g, number b, number a } optional
},
etc ...
}</pre>

{{LuaCallout
|prefix = gl.
|name = SecondaryColor
|arg1 = {{type|table}} color = { {{type|number}} r, {{type|number}} g, {{type|number}} b } {{pipe}} {{type|number}} r, {{type|number}} g, {{type|number}} b
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FogCoord
|arg1 = {{type|number}} value
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Display Lists =
Display Lists save given vertex attributes in a static buffer, so the GPU can directly read them (without the CPU). Display Lists are a lot faster (10-60x) than standard drawing with glShape/glBeginEnd, so try to use them when ever you can. If you want to learn more about them, g00gle is your friend ;)

{{LuaCallout
|prefix = gl.
|name = CreateList
|arg1 = {{type|function}} {{bracket}}
|arg2 = arg1 {{bracket}}
|arg3 = arg2 ... {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} listID
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CallList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteList
|arg1 = {{type|number}} listID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

{{LuaCallout
|prefix = gl.
|name = CreateVertexArray
|arg1 = {{type|number}} numElements
|arg2 = {{type|number}} numIndices {{bracket}}
|arg3 = {{type|bool}} persistentBuffer = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} bufferID
|info =
}}
<pre>See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry.</pre>

{{LuaCallout
|prefix = gl.
|name = UpdateVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} elementPos
|arg3 = {{type|number}} indexPos
|arg4 = {{type|table}} tbl {{pipe}} {{type|function}} func
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data
4 elements table example:
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }

Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices.</pre>

{{LuaCallout
|prefix = gl.
|name = RenderVertexArray
|arg1 = {{type|number}} bufferID
|arg2 = {{type|number}} primType {{bracket}}
|arg3 = {{type|number}} firstIndex = 0
|arg4 = {{type|number}} count = numElements {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info =
}}
<pre>primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES
firstIndex specifies the starting index in the enabled arrays.
count specifies the number of indices to be rendered.</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteVertexArray
|arg1 = {{type|number}} bufferID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} success
|info = Releases previously allocated VAO
}}

= Text =

{{LuaCallout
|prefix = gl.
|name = Text
|arg1 = {{type|string}} "text"
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} size {{bracket}}
|arg5 = {{type|string}} "options" {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}
<pre> options are:
horizontal alignment:
'c' = center
'r' = right
vertical alignment:
'a' = ascender
't' = top
'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)</pre>

{{LuaCallout
|prefix = gl.
|name = GetTextWidth
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} width
|info = Width in pixels, with a font size of 1.0.
}}

{{LuaCallout
|prefix = gl.
|name = GetTextHeight
|arg1 = {{type|string}} "text"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height, {{type|number}} descender, {{type|number}} numlines
|info = Height in pixels, with a font size of 1.0. Further descriptions here: [[GetTextHeight]]
}}

{{LuaCallout
|prefix = gl.
|name = BeginText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering.
}}

{{LuaCallout
|prefix = gl.
|name = EndText
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Unit/Feature Draw Functions =

{{LuaCallout
|prefix = gl.
|name = Unit
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws a unit - on default it uses LOD, with lod<0 it is turned off, else it defines a specific level.
}}

{{LuaCallout
|prefix = gl.
|name = UnitRaw
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Doesn't apply worldspace->unit transformation! only works if rawdraw is true.
}}

{{LuaCallout
|prefix = gl.
|name = UnitShape
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} rawState
|arg4 = {{type|bool}} toScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.
}}

{{LuaCallout
|prefix = gl.
|name = UnitMultMatrix
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = world space -> unit space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMultMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = unit space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = UnitPiece
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Draws the unit piece.
}}

{{LuaCallout
|prefix = gl.
|name = UnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use gl.UnitPieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = Feature
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureRaw
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} rawdraw
|arg3 = {{type|number}} intLOD {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShape
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|number}} teamID
|arg3 = {{type|bool}} custom
|arg4 = {{type|bool}} drawScreen
|arg5 = {{type|bool}} opaque
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureMultMatrix
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} world space -> feature space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMultMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} feature space -> piece space
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePiece
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Draws the Feature piece.
}}

{{LuaCallout
|prefix = gl.
|name = FeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} intPiece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{new|101.0}} Use gl.FeaturePieceMultMatrix instead!
}}

{{LuaCallout
|prefix = gl.
|name = DrawListAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} listID {{bracket}}
|arg3 = {{type|bool}} midPos
|arg4 = {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ
|arg5 = {{type|number}} degrees
|arg6 = {{type|number}} rotX, {{type|number}} rotY, {{type|number}} rotZ {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DrawFuncAtUnit
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} midPos
|arg3 = {{type|function}} {{bracket}}, arg1, ... {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= States (Blending,AlphaTest...) =

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Blending
|arg1 = {{type|string}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Mode can be set to:
}}
<pre>"add"
= GL.ONE, GL.ONE

"alpha_add"
= GL.SRC_ALPHA, GL.ONE

"alpha"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"reset"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA

"color"
= GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA

"modulate"
= GL.DST_COLOR, GL.ZERO

"disable"
= GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA</pre>

{{LuaCallout
|prefix = gl.
|name = BlendEquation
|arg1 = {{type|number}} mode
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendFunc
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcmode]]
|arg2 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstmode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = BlendEquationSeparate
|arg1 = {{type|number}} modeRGB
|arg2 = {{type|number}} modeAlpha
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = BlendFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcRGB]]
|arg2 = {{type|number}} [Lua_ConstGL#BlendingFactorDest|dstRGB]]
|arg3 = {{type|number}} [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]]
|arg4 = {{type|number}} [[Lua_ConstGL#BlendingFactorDest|dstAlpha]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs openGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = AlphaTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 = {{type|number}} threshold
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthTest
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#AlphaFunction and DepthFunction|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Culling
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DepthClamp
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Not always available, needs GL.NV_depth_clamp!
}}

{{LuaCallout
|prefix = gl.
|name = DepthMask
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} masked
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = ColorMask
|arg1 = {{type|bool}} r, {{type|bool}} g, {{type|bool}} b, {{type|bool}} a
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LogicOp
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} [[Lua_ConstGL#LogicOp|func]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Fog
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Smoothing
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} point
|arg2 = {{type|bool}} enable {{pipe}} {{type|number}} line
|arg3 = {{type|bool}} enable {{pipe}} {{type|number}} polygon
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = {{removed|104.0}}
}}

{{LuaCallout
|prefix = gl.
|name = EdgeFlag
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Scissor
|arg1 = {{type|number}} intX, {{type|number}} intY, {{type|number}} intW, {{type|number}} intH
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|string}} any
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Use springs default line stipple.
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = LineStipple
|arg1 = {{type|number}} intFactor
|arg2 = {{type|number}} pattern
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonMode
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} [[Lua_ConstGL#PolygonMode|mode]]
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PolygonOffset
|arg1 = {{type|bool}} enable {{pipe}} {{type|number}} factor
|arg2 = {{type|number}} units
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PushAttrib
|arg1 = {{bracket}} {{type|number}} [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PopAttrib
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Stencil =

{{LuaCallout
|prefix = gl.
|name = StencilTest
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMask
|arg1 = {{type|number}} mask
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilFunc
|arg1 = {{type|number}} func
|arg2 = {{type|number}} ref
|arg3 = {{type|number}} mask
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilOp
|arg1 = {{type|number}} fail
|arg2 = {{type|number}} zfail
|arg3 = {{type|number}} zpass
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = StencilMaskSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} mask
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilFuncSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} func
|arg3 = {{type|number}} ref
|arg4 = {{type|number}} mask
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = StencilOpSeparate
|arg1 = {{type|number}} [[Lua_ConstGL#Culling|face]]
|arg2 = {{type|number}} fail
|arg3 = {{type|number}} zfail
|arg4 = {{type|number}} zpass
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= LineWidth & PointSize =

{{LuaCallout
|prefix = gl.
|name = LineWidth
|arg1 = {{type|number}} width
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = PointSize
|arg1 = {{type|number}} size
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390
}}

{{LuaCallout
|prefix = gl.
|name = PointSprite
|arg1 = {{type|bool}} enable {{bracket}}
|arg2 = {{type|bool}} coord_replace
|arg3 = {{type|bool}} coord_origin_upper {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = PointParameter
|arg1 = {{type|number}} v1, {{type|number}} v2, {{type|number}} v3 {{bracket}}
|arg2 = {{type|number}} sizeMin
|arg3 = {{type|number}} sizeMax
|arg4 = {{type|number}} sizeFade {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs OpenGL2.0!
}}

= Textures =

{{LuaCallout
|prefix = gl.
|name = Texture
|arg1 = {{bracket}} {{type|number}} texNum, {{rbracket}} {{type|bool}} enable {{pipe}} {{type|string}} name
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} loaded
|info = This is the only call-out that is needed to load and draw any texture in a Lua script. All you have to do is pass it a valid path to a valid png and it will use that image for drawing any subsequent textured rectangles. This is shown in the last line of the following list of valid strings for the name parameter.
}}
name may be:

#12
= unitDef 12 buildpic

%34:1
= unitDef 34 s3o tex2 (:0->tex1,:1->tex2)

%-102:0
= featureDef 102 s3o tex1

!56
= lua generated texture 56 (= return value of gl.CreateTexture)

$units
= 3do textureatlas tex1

$units1
= 3do textureatlas tex1

$units2
= 3do textureatlas tex2

$shadow
= shadowmap

$specular
= specular cube map (removed in the latest develop)

$reflection
= reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)

$shading
= ground shading texture

$grass
= grass shading texture

$heightmap
= heightmap (needs HeightMapTexture=1 set in spring config)

$minimap
= minimap texture

$map_reflection
= same as "$reflection" {{new|101.0}}

$sky_reflection
= defined for SSMF maps that have a skyReflectModTex {{new|101.0}}

$detail
= detail texture {{new|101.0}}

$normals
= auto generated normals texture, X component is in r,g and b channels, Z component is in the A channel. {{new|101.0}}

$ssmf_normals
= SSMF normals texture {{new|101.0}}

$ssmf_specular
= SSMF specular texture {{new|101.0}}

$ssmf_splat_distr
= SSMF splat distribution texture {{new|101.0}}

$ssmf_splat_detail
= SSMF splat detail texture {{new|101.0}}

$ssmf_splat_normals
= SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted

$ssmf_emission
= SSMF emission texture {{new|101.0}}

$ssmf_parallax
= SSMF parallax texture {{new|101.0}}

$info
= currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale

$info_losmap
= los texture (L-view)

$info_mtlmap
= metal map texture (F4-view)

$info_hgtmap
= height map texture (F1-view)

$info_blkmap
= blocking map texture (F2-view)

$map_gbuffer_normtex
= contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$map_gbuffer_difftex
= contains the diffuse texture buffer of the map in view {{new|95}}

$map_gbuffer_spectex
= contains the specular textures of the map in view {{new|95}}

$map_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$map_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$map_gbuffer_zvaltex
= contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use:

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;

$model_gbuffer_normtex
= contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}

$model_gbuffer_difftex
= contains the diffuse texture buffer of the models in view {{new|95}}

$model_gbuffer_spectex
= contains the specular textures of the models in view {{new|95}}

$model_gbuffer_emittex
= for emissive materials (bloom would be the canonical use) {{new|95}}

$model_gbuffer_misctex
= for arbitrary shader data {{new|95}}

$model_gbuffer_zvaltex
= contains the depth values (z-buffer) of the models in view. {{new|95}}

${opt}:/LuaUI/images/image.png
= load a texture from the VFS

possible ${opt}'s are:
'n' = nearest
'l' = linear
'a' = aniso
'i' = invert
'g' = greyed
'c' = clamped
'b' = border
't%r,%g,%b' = tint
'r%width,%height' = resize
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

example: ":iac:/LuaUI/images/image.png"
example: ":cr16,16:/LuaUI/images/image.png"
example2: ":t1.0,0.5,0:/LuaUI/images/image.png" (orange tint)


{{LuaCallout
|prefix = gl.
|name = CreateTexture
|arg1 = {{type|number}} intXSize
|arg2 = {{type|number}} intYSize {{bracket}}
|arg3 = {{type|table}} texProps {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} texture
|info = texProps contains:
}}
<pre>texProps = {
[target = number,](like GL.TEXTURE_1D,GL.TEXTURE_2D,...)(Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[format = number,]
[min_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[mag_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[wrap_s = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_t = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_r = [[Lua_ConstGL#Texture_Clamping|number]],]
[aniso = number,]
[border = boolean,]
[fbo = boolean,] (needs GLEW_EXT_framebuffer_object!)
[fboDepth = boolean,] (needs GLEW_EXT_framebuffer_object!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
}</pre>

{{LuaCallout
|prefix = gl.
|name = DeleteTexture
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info =
}}

{{LuaCallout
|prefix = gl.
|name = DeleteTextureFBO
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} deleted
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = TextureInfo
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} texInfo
|info = texInfo contains:
}}
<pre> texInfo = {
xsize = number,
ysize = number,
alpha = boolean, //not used yet
type = number, //not used yet
}

The format of the texture string is the same as in gl.Texture().</pre>

{{LuaCallout
|prefix = gl.
|name = MultiTexCoord
|arg1 = {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} {{pipe}} {{type|table}} texCoords = { {{type|number}} x {{bracket}}, {{type|number}} y {{bracket}}, {{type|number}} z {{bracket}}, {{type|number}} w {{rbracket}}{{rbracket}}{{rbracket}} }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexEnv
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexEnv
|arg1 = {{type|number}} texNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} state
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = TexGen
|arg1 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg2 = {{type|bool}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg3 = {{type|number}} var1
|arg4 = {{type|number}} var2
|arg5 = {{type|number}} var3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|bool}} state
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} [[Lua_ConstGL#Texture_Environment|value]]
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = MultiTexGen
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|number}} [[Lua_ConstGL#Texture_Generation|target]]
|arg3 = {{type|number}} [[Lua_ConstGL#Texture_Environment|pname]]
|arg4 = {{type|number}} var1
|arg5 = {{type|number}} var2
|arg6 = {{type|number}} var3
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = CopyToTexture
|arg1 = {{type|string}} texture
|arg2 = {{type|number}} intXOff
|arg3 = {{type|number}} intYOff
|arg4 = {{type|number}} intX
|arg5 = {{type|number}} intY
|arg6 = {{type|number}} intW
|arg7 = {{type|number}} intH {{bracket}}
|arg8 = {{type|number}} target
|arg9 = {{type|number}} level {{rbracket}}
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = RenderToTexture
|arg1 = {{type|string}} fbotexture
|arg2 = {{type|function}} lua_func
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs GLEW_EXT_framebuffer_object!
}}

{{LuaCallout
|prefix = gl.
|name = GenerateMipmap
|arg1 = {{type|string}} texture
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} created
|info = Needs glGenerateMipmapEXT!
}}
<pre>The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")</pre>

{{LuaCallout
|prefix = gl.
|name = UnitTextures
|arg1 = {{type|number}} unitID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = UnitShapeTextures
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureTextures
|arg1 = {{type|number}} featureID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = gl.
|name = FeatureShapeTextures
|arg1 = {{type|number}} featureDefID
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

= PixelReadback =

{{LuaCallout
|prefix = gl.
|name = SaveImage
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h
|arg5 = {{type|string}} filename {{bracket}}
|arg6 = {{type|table}} imgProps = { alpha={{type|bool}}, yflip={{type|bool}}, grayscale16bit={{type|bool}}, readbuffer={{type|number}} } {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index
}}

{{LuaCallout
|prefix = gl.
|name = ReadPixels
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} w
|arg4 = {{type|number}} h {{bracket}}
|arg5 = {{type|number}} format = GL.RGBA {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} r {{bracket}}, g {{bracket}}, b {{bracket}}, a {rbracket}}{rbracket}}{rbracket}} {{pipe}} {{type|table}} readPixels = { { { 1 = {{type|number}} r, 2 = {{type|number}} g, 3 = {{type|number}} b, 4 = {{type|number}} a}, ... }, ... }
|info = This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.
}}

= Lights =

{{LuaCallout
|prefix = gl.
|name = Lighting
|arg1 = {{type|bool}} enable
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = ShadeModel
|arg1 = {{type|number}} [[Lua_ConstGL#ShadeModel|mode]]
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|bool}} enable
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|number}} [[Lua_ConstGL#Light_Specification|pname]]
|arg3 = {{type|number}} param
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = Light
|arg1 = {{type|number}} intLight
|arg2 = {{type|number}} [[Lua_ConstGL#Light_Specification|pname]]
|arg3 = {{type|number}} param1
|arg4 = {{type|number}} param2
|arg5 = {{type|number}} param3
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Material
|arg1 = {{type|table}} material
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = material contains:
}}
<pre>material = {
ambient = {number r, number g, number b[, number a]},
diffuse = {number r, number g, number b[, number a]},
ambidiff = {number r, number g, number b[, number a]},
emission = {number r, number g, number b[, number a]},
specular = {number r, number g, number b[, number a]},
shininess = number specularExponent
}</pre>

= Hardware relevant =

{{LuaCallout
|prefix = gl.
|name = HasExtension
|arg1 = {{type|string}} extname
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} hasExtension
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetNumber
|arg1 = {{type|number}} ext
|arg2 = {{type|number}} intCount
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} number1 {{bracket}}, {{type|number}} number2, {{type|number}} number3, ... #count {{rbracket}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetString
|arg1 = {{type|number}} ext
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} extString
|info =
}}

= DrawGroundPrimitives =

{{LuaCallout
|prefix = gl.
|name = DrawGroundCircle
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 = {{type|number}} divs {{bracket}}
|arg6 = {{type|number}} slope {{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: Number divs is the number of sides the circle will have. The higher the smoother the circle (and more GPU intensive).
}}

{{LuaCallout
|prefix = gl.
|name = DrawGroundQuad
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2 {{bracket}}
|arg5 = {{type|bool}} useNorm {{bracket}}
|arg6 = {{type|number}} tu1, {{type|number}} tv1
|arg7 = {{type|number}} tu2, {{type|number}} tv2 {{rbracket}} {{pipe}} {{bracket}} {{type|bool}} useTextureCoord {{rbracket}} {{rbracket}}
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Note: x1, z1, x2 & z2 are rounded, so don't use it for very small or moving objects. x and z correspond to the coordinates displayed by the tooltip. Also note: useNorm does nothing!
}}

= Queries =

{{LuaCallout
|prefix = gl.
|name = CreateQuery
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|userdata}} query
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = DeleteQuery
|arg1 = {{type|userdata}} query
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = RunQuery
|arg1 = {{type|userdata}} query
|arg2 = {{type|function}} func
|arg3 = {{type|arg1}}
|arg4 = {{type|arg2}}
|arg5 = ...
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Needs >=OpengGL2.0!
}}

{{LuaCallout
|prefix = gl.
|name = GetQuery
|arg1 = {{type|userdata}} query
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} renderedFragments
|info =
}}

= Extended =

{{LuaCallout
|prefix = gl.
|name = ActiveTexture
|arg1 = {{type|number}} intTexNum
|arg2 = {{type|function}} func {{bracket}}
|arg3 = {{type|arg1}}
|arg4 = ... {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetGlobalTexNames
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} texNames = { {{bracket|1}} = {{type|string}} texture, etc ... }
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetGlobalTexCoords
|arg1 = {{type|string}} 3doTextureName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} xstart, {{type|number}} ystart, {{type|number}} xend, {{type|number}} yend
|info = Gets the texcoord of a 3do texture in the 3do texture atlas.
}}

{{LuaCallout
|prefix = gl.
|name = UnsafeState
|arg1 = {{type|number}} state {{bracket}}
|arg2 = {{type|bool}} disable_state {{rbracket}}
|arg3 = {{type|bool}} func
|arg4 = {{type|arg1}}
|arg5 = {{type|arg2}}
|arg6 = ...
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = Calls glEnable(state) or glDisable(state) (if disable_state==true) and then calls the lua_function and afterwards reverts the state.
}}

{{LuaCallout
|prefix = gl.
|name = GetShadowMapParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} xmid, {{type|number}} ymid, {{type|number}} p17, {{type|number}} p18
|info =
}}

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.PROJECTION {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.MODELVIEW {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = GL.TEXTURE {{bracket}}
|arg2 = {{type|number}} intI
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc... {{pipe}} {{type|number}} Matrix{{bracket|i}}
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "shadow"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "camera"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}
{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "caminv"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "camprj"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

or

{{LuaCallout
|prefix = gl.
|name = GetMatrixData
|arg1 = {{type|string}} "billboard"
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} number1, etc...
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Flush
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

{{LuaCallout
|prefix = gl.
|name = Finish
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info =
}}

= Shaders (GLSL) =
[[Lua_GLSL_Api]]

[[category: Lua]]

Lua:Callins

2021-11-25T14:35:19Z

Beherith: /* Synced Only */

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

'''Attention:''' some callins will only work on the unsynced portion of the gadget. Due to the type-unsafe nature of lua parsing, those callins not firing up might be hard to trace. This document will be continuously updated to properly alert about those situations.

== 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. A list of key codes can be seen at the [https://wiki.libsdl.org/SDLKeycodeLookup SDL wiki].
}}

{{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 (including when the game is paused) and at least once per sim frame except when catching up. The parameter is the time since the last update. }}

=== Draw* Functions ===
Inside the Draw* functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.
 
Avoid doing heavy calculations inside these callins; ideally, do the calculations elsewhere and use Draw callins only for drawing.

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

{{LuaCallin
|name = DrawWorldPreParticles
|info = ??? {{new|104.0}}
}}

{{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
|args = vsx, vsy
|info = ??? Also available to LuaMenu.
}}

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

{{LuaCallin
|name = DrawScreenPost
|args = vsx, vsy
|info = {{new|104.0}} Similar to {{name|DrawScreenEffects}}, this can be used to alter the contents of a frame after it has been completely rendered (i.e. World, MiniMap, Menu, UI).
}}

{{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, [[Lua_UnitRendering#Lua.27s_DrawXYZ-Callin|enabled here]].
}}

== Unsynced Menu Only ==

{{LuaCallin
|name = AllowDraw
|return = {{type|bool}} allowDraw
|info = Enables Draw{Genesis,Screen,ScreenPost} callins if {{value|true}} is returned, otherwise they are called once every 30 seconds. Only active when a game isn't running.
}}

{{LuaCallin
|name = ActivateMenu
|info = Called whenever LuaMenu is on with no game loaded.
}}

{{LuaCallin
|name = ActivateGame
|info = Called whenever LuaMenu is on with a game loaded.
}}

== 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. From 104.0 onwards, will not be called when a saved game is loaded.
}}

{{LuaCallin
|name = GameStart
|info = Called upon the start of the game. From 104.0 onwards, will not be called when a saved game is loaded.
}}

=== 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]]. Should be called more reliably with small values of experience grade in 104.0+.
}}

{{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. Note that this is also called for resurrecting features, and for refilling features with resources before resurrection. On reclaim the part values are negative, and on refill and reclaim they are positive.
}}

{{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 = playerID, teamID, readyState, clampedX, clampedY, clampedZ, 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.
NB: The order of the parameters changed with the addition of {{var|teamID}} in 104.0. Previouly it was:
{{var|clampedX, clampedY, clampedZ, playerID, readyState, rawX, rawY, rawZ}}
}}

{{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". {{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
|I recommend looking up the CallIns in Sourcecode, because the Lua-Documentation, generated from the lua handle of them is seriously flawed and not regenerated.
|Lua-Handler documented from version
|args = proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|https://github.com/spring/spring/blob/d085e297416bd963ec25eaa3dbf0796ba22a3582/rts/Lua/LuaHandleSynced.h#L106
|Actual CallIn:
|args = proID, shieldCarrier, boolBounceProjectile, beamEmitterWeaponNum, beamEmitterUnitID, startX, startY, startZ, hitX, hitY, hitZ
|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. The start and hit position arguments are provided from 104.0 onwards.
}}

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

Gamedev:UnitDefs

2021-09-29T14:49:49Z

Beherith: /* Resources */

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

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

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

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

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

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

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

==Data Types==
{{DataTypes}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = windGenerator
|type = float
|default = 0.0
|description = The maximum amount of the energy resource the unit generates which is dependant on the map wind. Works only for structures. If wind speed is higher than this, the unit will still only produce this much. If wind speed is less, it will produce as much as windspeed is.}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{tag
|name = frontToSpeed
|type = float
|default = 0.1
|description = How far nose can be unaligned to speed vector before accelleration is applied.
}}

{{tag
|name = speedToFront
|type = float
|default = 0.07
|description = Rate for the nose to align to new (true) direction change. Values above 0.1 may lead to cumulative speedup issues.
}}

{{tag
|name = crashDrag
|type = float
|default = 0.005
|description = The drag used when crashing. Clamped between <code>0.0</code> and <code>1.0</code>.
}}

{{tag
|name = maxBank
|type = float
|default = 0.8
|description = The maximum roll (z-axis rotation) the aircraft can achieve.
}}

{{tag
|name = maxPitch
|type = float
|default = 0.45
|description = The maximum pitch (x-axis rotation) the aircraft tries to keep.
}}

{{tag
|name = turnRadius
|type = float
|default = 500.0
|description = Hint to Spring unit AI about the required turning radius.
}}

{{tag
|name = verticalSpeed
|type = float
|default = 3.0
|description = The speed of takeoff and landing, at least for gunships ({{taglink|hoverAttack|true}}).
}}

{{tag
|name = maxAileron
|type = float
|default = 0.015
|description = The maximum turn speed around the roll (z) axis.
}}

{{tag
|name = maxElevator
|type = float
|default = 0.01
|description = The maximum turn speed around the pitch (x) axis.
}}

{{tag
|name = maxRudder
|type = float
|default = 0.004
|description = The maximum turn speed around the yaw (y) axis.
}}

{{tag
|name = maxAcc
|type = float
|default = 0.065
|description = The maximum acceleration or 'engine power' of the aircraft.
}}

{{tag
|name = attackSafetyDistance
|type = float
|default = 0
| special = Exists only in version 99.0
|description = Fighters abort dive toward target if within attackSafetyDistance and try to climb back to normal altitude while still moving toward target. It's disabled by default. Set to half of the minimum weapon range to avoid collisions, enemy fire, AOE damage. If set to greater than the weapon range, the unit will fly over the target like a bomber. This tag was removed in version 100.0 and changed to a [[Lua_MoveCtrl#MoveType-Controlling|Spring.SetMoveTypeData]] key.
}}

====Flares====
The following set of tags are rarely used and are hardcoded to only work vs. missile weapons. The texture is hardcoded to be <code>flareprojectiletexture</code> defined in [[Resources.lua]]. 
{{tag
|name = canDropFlare
|type = bool
|default = false
|description = Can this aircraft drop flares to distract missile weapons?
}}

{{tag
|name = flareReload
|type = float
|default = 5.0
|lua = flareReloadTime
|description = The time in seconds between successive flare drops.
}}

{{tag
|name = flareDelay
|type = float
|default = 0.3
|description = The delay between detecting an incoming missile and launching flares. Multiplied by a random number between 1 and 16.
}}

{{tag
|name = flareEfficiency
|type = float
|default = 0.5
|description = The probability that an incoming missile will target the flare instead of the aircraft.
}}

{{tag
|name = flareDropVector
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The direction vector which flares are emitted in.
}}

{{tag
|name = flareTime
|type = int
|default = 3
|description = The lifetime of a dropped flare in [[frames]].
}}

{{tag
|name = flareSalvoSize
|type = int
|default = 4
|description = How many flares are dropped at once?
}}

{{tag
|name = flareSalvoDelay
|type = int
|default = 0
|description = The delay in [[frames]] between the release of each individual flare in a burst.
}}

===Transports===
{{tag
|name = transportSize
|type = int
|default = 0
|description = The size of units that the transport can pick up, in terms of the passengers {{taglink|footprintX}}.}}

{{tag
|name = minTransportSize
|type = int
|default = 0
|description = The smallest size of unit that the transport can pick up, in terms of the passengers {{taglink|footprintX}}.}}

{{tag
|name = transportCapacity
|type = int
|default = 0
|description = The total number of units that the transport can pick up, with each unit multiplied by it's {{taglink|footprintX}} size. Prior to 101.0 if this tag is not present, then any Script.AttachUnit and Script.DropUnit call in the animation script will be ignored (See [[Animation-LuaCallouts#Other]]), in successive versions all units can use [[Lua_SyncedCtrl#Unit_Control|Spring.UnitAttach]] et al regardless of this tag.}}

{{tag
|name = transportMass
|type = float
|default = 100000.0
|description = The total cumulative {{taglink|mass}} of passengers the transport can carry.}}

{{tag
|name = minTransportMass
|type = float
|default = 0.0
|description = The minimum {{taglink|mass}} passenger the transport can carry.}}

{{tag
|name = loadingRadius
|type = float
|default = 220.0
|description = How far away in [[elmo]]s can the transporter pick up and drop units?}}

{{tag
|name = unloadSpread
|type = float
|default = 5.0
|description = How spread out the passengers are when unloaded. Is multiplied by the passengers radius.}}

{{tag
|name = isFirePlatform
|type = bool
|default = false
|description = Can transported units still aim and shoot while loaded by this transport?}}

{{tag
|name = holdSteady
|type = bool
|default = false
|description = If <code>true</code> - passengers are slaved to orientation of transporter attachment piece, if <code>false</code> - passengers are slaved to orientation of transporter body.}}

{{tag
|name = releaseHeld
|type = bool
|default = false
|description = Does the transporter unload it's passengers when it dies?}}

{{tag
|name = cantBeTransported
|type = bool
|default = false for mobile units, true for structures
|description = Controls if a unit is transportable at all or not. If <code>false</code> it is overridden by [[Modrules.lua]] <code>transportability</code> subtable tags.}}

{{tag
|name = transportByEnemy
|type = bool
|default = true
|description = Controls if a unit can be transported by an enemy transport. i.e. can it be kidnapped.}}

{{tag
|name = transportUnloadMethod
|type = int
|default = 0
|description = For air transports. Can be <code>0</code> - Land to unload individually, <code>1</code> - Flyover drop (i.e. Parachute), or <code>2</code> - Land and flood unload all passengers. Can be used on ground transports with mixed results.}}

{{tag
|name = fallSpeed
|type = float
|default = 0.2
|description = For air transports with {{taglink|transportUnloadMethod|1}}. The speed in [[elmo]]s per second which units will fall at when released from the transport.}}

{{tag
|name = unitFallSpeed
|type = float
|default = 0.0
|description = Allows you to override {{taglink|fallSpeed}} for an individual passenger.}}

===Categories===
{{tag
|name = category
|type = string
|default = ""
|description = The category tag is a string of separate words, each representing a category of units. There is a maximum of 32 categories. The primary purpose of categories is weapon targeting (See [[#weapons]]).}}

{{tag
|name = noChaseCategory
|type = string
|default = ""
|description = The unit will still target enemies with a matching {{taglink|category}}, but will not chase after it if it moves out of weapon range.}}

===Decals===
{{tag
|name = leaveTracks
|type = bool
|default = false
|description = Does the unit leave a track mark decal behind it when it moves? For mobile units.}}

{{tag
|name = trackType
|type = string
|default = "stdTank"
|description = The filename of the image, without extension, assumed to be in <code>Bitmaps/Tracks/</code>, to be used as the track decal. The red channel of the image controls the brightness and the green channel the alpha (how visible it is) of the track. Blue channel is unused.}}

{{tag
|name = trackWidth
|type = float
|default = 32.0
|description = The width of the track decal left on the ground, in [[elmo]]s.}}

{{tag
|name = trackOffset
|type = float
|default = 0.0
|description = How far back in [[elmo]]s the track should be drawn from the centre of the unit.}}

{{tag
|name = trackStrength
|type = float
|default = 32.0
|description = How visible or 'deep' the track mark should be. Also used to determine how long the decal should last.}}

{{tag
|name = trackStretch
|type = float
|default = 1.0
|description = How much the track is stretched in the forward direction compared to the sides (i.e. used to change aspect ratio).}}

{{tag
|name = useBuildingGroundDecal
|type = bool
|default = false
|description = For structures, do they display a ground decal on the terrain under their model?}}

{{tag
|name = buildingGroundDecalType
|type = string
|default = ""
|description = The filename of the image to be used as ground decal. Assumed to be in <code>Unittextures/</code>.}}

{{tag
|name = buildingGroundDecalSizeX
|type = int
|default = 4
|description = How wide the decal is left to right, in footprint units.}}

{{tag
|name = buildingGroundDecalSizeY
|type = int
|default = 4
|description = How wide the decal is top to bottom, in footprint units.}}

{{tag
|name = buildingGroundDecalDecaySpeed
|type = float
|default = 0.1
|description = A measure of how quickly the decal should fade out if the structure dies. Essentially this value is multiplied by the time since death and subtracted from the original alpha until the decal is fully transparent.}}

===Collision Volumes===
For a deeper explanation of these tags, see [[Gamedev:CollisionVolumes]]. Note that all collision checks first do a pre-check with the unit ''radius'' before doing the colvol checks. Ergo the unit ''radius'' must be larger or equal to the colvol!

{{tag
|name = usePieceCollisionVolumes
|type = bool
|default = false
|lua = collisionVolume.defaultToPieceTree
|description = When turned on the model and UnitDef collision volumes are ignored and Spring generates a bounding box volume for each piece of the unit model. These volumes can be manipulated or replaced by [[Lua_SyncedCtrl#Unit_Control | Spring.SetUnitPieceCollisionVolumeData]]. Increases the performance cost of collision calculations.}}

{{tag
|name = useFootPrintCollisionVolume
|type = bool
|default = false
|special = {{new|92.0}}
|lua = .collisionVolume.defaultToFootprint
|description = Replaces any defined collision volume with a box with dimensions equal to the object's footprint (this also overrides any custom scaling and/or offsets).
}}

The following three tags can instead be replaced with a [[#collisionVolume]] subtable:

{{tag
|name = collisionVolumeType
|type = string
|default = "s"
|lua = collisionVolume.type
|description = What shape should the unit's collision volume be? Can be {{value|"box"}}, {{value|"sphere}} or a cylinder aligned to an axis; {{value|"cylX"}}, {{value|"cylY"}}, {{value|"cylZ"}}.}}

{{tag
|name = collisionVolumeScales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = collisionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the collision volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = collisionVolumeOffsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = collisionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the hit volume centre in each axis.}}

The following tags have now been removed from the engine:

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

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

===Selection Volumes===
Introduced in 104.0, units may now have custom selection volumes in exactly the same way as collision volumes were already defined.

{{tag
|name = usePieceSelectionVolumes
|type = bool
|default = false
|special = {{new|104.0}}
|lua = .selectionVolume.defaultToPieceTree
|description = When turned on the model and UnitDef selection volumes are ignored and Spring generates a bounding box volume for each piece of the unit model (the same volumes are used for collision and selection). These volumes can be manipulated or replaced by [[Lua_SyncedCtrl#Unit_Control | Spring.SetUnitPieceColisionVolumeData]]. Increases the performance cost of selection calculations.}}

{{tag
|name = useFootPrintSelectionVolume
|type = bool
|default = false
|special = {{new|104.0}}
|lua = .selectionVolume.defaultToFootprint
|description = Replaces any defined selection volume with a box with dimensions equal to the object's footprint (this also overrides any custom scaling and/or offsets).
}}

The following three tags can instead be replaced with a [[#selectionVolume]] subtable:

{{tag
|name = selectionVolumeType
|type = string
|default = "s"
|special = {{new|104.0}}
|lua = collisionVolume.type
|description = What shape should the unit's selection volume be? Can be {{value|"box"}}, {{value|"sphere}} or a cylinder aligned to an axis; {{value|"cylX"}}, {{value|"cylY"}}, {{value|"cylZ"}}.}}

{{tag
|name = selectionVolumeScales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = {{new|104.0}}
|lua = .selectionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the selection volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = selectionVolumeOffsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|special = {{new|104.0}}
|lua = .selectionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the selection volume centre in each axis.}}

===Attack Behaviours===
{{tag
|name = highTrajectory
|type = int
|default = 0
|lua = highTrajectoryType
|description = Can the unit fire it's (ballistic) weapons in a high trajectory arc? Can be <code>0</code> - Low trajectory only, <code>1</code> - High trajectory only, or <code>2</code> - Toggle button.}}

{{tag
|name = kamikaze
|type = bool
|default = false
|lua = canKamikaze
|description = Does the unit attack its target by blowing itself up?}}

{{tag
|name = kamikazeDistance
|type = float
|default = 0.0
|lua = kamikazeDist
|description = How close to the target, in [[elmo]]s, the unit must get before detonating. Measured in 3D, not 2D.}}

{{tag
|name = kamikazeUseLOS
|type = bool
|default = false
|description = Does the target unit have to be in LOS when detonating or only within {{taglink|kamikazeDistance}}.}}

{{tag
|name = strafeToAttack
|type = bool
|default = false
|description = Should the unit move sideways when it can't shoot?}}

===Other===
{{tag
|name = decoyFor
|type = string
|default = ""
|description = The UnitDef name (not human {{taglink|name}}) which this unit is a decoy for.}}

{{tag
|name = selfDestructCountdown
|type = int
|default = 5
|lua = selfDCountdown
|description = The length in seconds taken between issuing self destruct order and the unit exploding.}}

{{tag
|name = damageModifier
|type = float
|default = 1.0
|lua = armoredMultiple
|description = The multiplier applied to weapon damage when the units ARMORED status (See [[Lua_ConstCOB]]) is turned on.}}

{{tag
|name = isTargetingUpgrade
|type = bool
|default = false
|lua = targFac
|description = Does the unit upgrade the targeting so that units shoot accurately at enemy units which are in radar but not in LOS.}}

{{tag
|name = isFeature
|type = bool
|default = false
|description = Does the unit immediately die into it's {{taglink|corpse}} feature when built? Used mainly for making walls.}}

{{tag
|name = hideDamage
|type = bool
|default = false
|description = Should the units current health be invisible to enemy players?}}

{{tag
|name = showPlayerName
|type = bool
|default = false
|description = Should the unit display it's controlling player as its name instead of {{taglink|name}}. Generally used for commander or hero units.}}

{{tag
|name = showNanoFrame
|type = bool
|default = true
|description = Does the unit show an OTA-style nanoframe whilst being constructed?}}

{{tag
|name = unitRestricted
|type = int
|default = MAX_UNITS
|lua = maxThisUnit
|description = How many of this unit type may a player control at once? Defaults to being the maximum amount of units controllable. Is overridden by lobby unit restrictions.}}

{{tag
|name = power
|type = float
|default = {{taglink|buildCostMetal}} + ({{taglink|buildCostEnergy}} / 60.0)
|description = The relative power of the unit. Used in weapon targeting priority and experience gain calculations.}}

==Sub Tables==

===collisionVolume===
The <code>collisionVolume</code> subtable of a UnitDef replaces the older individual {{taglink|collisionVolumeType}}, {{taglink|collisionVolumeScales}} and {{taglink|collisionVolumeOffsets}} tags.

{{tag
|name = type
|type = string
|default = "s"
|lua = .collisionVolume.type
|description = What shape should the unit's collision volume be? Can be {{value|"box"}}, {{value|"sphere"}} or a {{value|"cylinder"}}.}}

{{tag
|name = axis
|type = string
|default = "z"
|description = Which axis does the unit's collision volume lie along? Can be {{value|"x"}}, {{value|"y"}} or {{value|"z"}}.}}

{{tag
|name = scales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .collisionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the collision volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = offsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .collisionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the hit volume centre in each axis.}}

===selectionVolume===
The <code>selectionVolume</code> subtable of a UnitDef can replace the individual {{taglink|selectionVolumeType}}, {{taglink|selectionVolumeScales}} and {{taglink|selectionVolumeOffsets}} tags.

{{tag
|name = type
|type = string
|default = "s"
|lua = .selectionVolume.type
|description = What shape should the unit's selection volume be? Can be {{value|"box"}}, {{value|"sphere"}} or a {{value|"cylinder"}}.}}

{{tag
|name = axis
|type = string
|default = "z"
|description = Which axis does the unit's selection volume lie along? Can be {{value|"x"}}, {{value|"y"}} or {{value|"z"}}.}}

{{tag
|name = scales
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .selectionVolume.scale{X{{pipe}}Y{{pipe}}Z}
|description = The lengths of the selection volume in each of the three axes. Note that non-spherical ellipsoids and elliptical cylinders are not supported.}}

{{tag
|name = offsets
|type = float[3]
|default = {0.0, 0.0, 0.0}
|lua = .selectionVolume.offset{X{{pipe}}Y{{pipe}}Z}
|description = The offset from the unit centre to the selection volume centre in each axis.}}

===weapons===
The <code>weapons</code> subtable of a UnitDef tells Spring which weapons the unit has. It is a simple array (number indexed table) of <code>weaponName</code>s (not the human readable <code>name</code>!).

The following additional tags are associated with this subtable:

{{tag
|name = name
|type = string
|default = ""
|description = The <code>weaponName</code> of the weapon (See [[Gamedev:WeaponDefs]]). If using the [[weapondefs_post.lua]] provided by [[springcontent.sdz]], you may include the WeaponDef tables within the UnitDef as the <code>weaponDefs</code> subtable, and refer to them with <code>def</code> rather than <code>name</code>. This can be a useful way to organise definitions if units do not generally share weapons.}}

{{tag
|name = badTargetCategory
|type = string
|default = ""
|description = A string of unit {{taglink|category}} entries which this weapon prefers to avoid targeting. i.e. given two units which ''can'' be targeted, any unit whose {{taglink|category}} matches any entry in this tag, will be targeted last. (See [[#Categories]])}}

{{tag
|name = onlyTargetCategory
|type = string
|default = ""
|description = A string of unit {{taglink|category}} entries which this weapon can target. i.e. any unit whose {{taglink|category}} does not match any entry in this tag, cannot be targeted by this weapon. (See [[#Categories]])}}

{{tag
|name = slaveTo
|type = int
|default = 0
|description = The number of the weapon which this weapon is slaved to. A slaved weapon can only target what it's master is targeting. Weapon numbers start at <code>1</code> and correspond to the index of the weapon within the subtable.}}

{{tag
|name = mainDir
|type = float[3]
|default = {0.0, 0.0, 1.0} i.e. forwards
|description = A vector representing the firing direction of this weapon if it has a limited firing arc. Used in conjunction with {{taglink|maxAngleDif}} (See [[Gamedev:WeaponMainDir]]).}}

{{tag
|name = maxAngleDif
|type = float
|default = 360.0
|description = How wide this weapons limited firing arc is in degrees. Symmetrical about {{taglink|mainDir}} i.e. <code>180.0</code> is 90 degree freedom either way (See [[Gamedev:WeaponMainDir]]).}}

{{tag
|name = fuelUsage
|type = float
|default = 0.0
|description = How much fuel in seconds is deducted from the units initial {{taglink|maxFuel}} when this weapon fires.}}

===buildOptions===
The <code>buildOptions</code> subtable of a UnitDef tells Spring which other units the unit can build (in the case of a builder) or produce (in the case of a factory).
It is a simple array (number indexed table) of <code>unitName</code>s (not the human readable {{taglink|name}}!).

There are no additional tags specific to this subtable.

===SFXTypes===
The <code>SFXTypes</code> subtable of a UnitDef tells Spring which [[CEG]] effects are associated with the unit. It consists of two further subtables, with no additional tags specific to them.

====explosionGenerators====

The <code>explosionGenerators</code> subtable of <code>SFXTypes</code> tells Spring which [[CEG]]s the unit's script can call, via the <code>EmitSFX()</code> callout (See [[Animation-LuaCallouts#Effects]]). It is a simple array (number indexed table) of CEG names, prefaced by the string <code>"custom:"</code>.

====pieceExplosionGenerators====
{{new|83.0}}

The <code>pieceExplosionGenerators</code> subtable of <code>SFXTypes</code> tells Spring which [[CEG]]s the unit's script can pick at random to attach to a flying unit piece, created from the <code>Explode()</code> callout (See [[Animation-LuaCallouts#Effects]]). It is a simple array (number indexed table) of CEG names, with no prefix.

Forum thread (with examples): {{forumlink|topic=27554|title=pieceExplosionGenerators}}

===sounds===

The <code>sounds</code> subtable of a UnitDef tells Spring which sound files to play when the unit triggers various events.

Files are assumed to be in the <code>Sounds/</code> directory; accepted formats are .wav and .ogg, the former being assumed if no extension is given.

Sounds can be defined in one of three ways:

# Each event can be used as though it were a <code>string</code> tag referring to the filename.
# Each event can be the name of a subtable, which is a simple array containing the filenames. One sound is picked at random from the list each time the event occurs.
# Each event can be the name of a subtable, which is a simple array containing further tables, which contain the following tags:
{{tag
|name = file
|type = string
|default = ""
|description = The filename of the sound to play.}}

{{tag
|name = volume
|type = float
|default = 1.0
|description = The default volume of the sound.}}

Spring checks any referenced sound filename to see if a SoundItem has been created, which allows greater control over how it is played (See [[Sounds.lua]]).

====sounds Example====

For clarification, here is an example of all three methods:

<code><pre>sounds = {
-- Method 1
ok = 'oksound', -- .wav appended
-- Method 2
arrived = {
'arrived1.wav',
'arrived2.wav',
},
-- Method 3
select = {
{ file = 'selsound1.ogg', volume = 2.0 },
{ file = 'selsound2.ogg', volume = 2.5 },
},
}</pre></code>

====sounds Events====

The events called by the engine are as follows:

{{ItemType
|name = ok
|description = Unit is issued a command.
}}

{{ItemType
|name = select
|description = Unit is selected by the player.
}}

{{ItemType
|name = arrived
|description = Unit has arrived at its destination. Mobile ground units only.
}}

{{ItemType
|name = build
|description = Unit begins building. Called for both factories and mobile construction units.
}}

{{ItemType
|name = activate
|description = Unit is activated, i.e. Is turned on. Also called when a mobile ground unit starts moving.
}}

{{ItemType
|name = deactivate
|description = Unit deactivates, i.e. Is turned off.
}}

{{ItemType
|name = cant
|description = Unit cannot carry out this order. Loaded but not currently called by the engine.
}}

{{ItemType
|name = underattack
|description = Unit gets attacked. Loaded but not currently called by the engine.
}}

===customParams===
The <code>customParams</code> subtable of a UnitDef allows the game designer to give their units custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
MC:L implements OO with inheritance (base classes in [http://sourceforge.net/p/mwspring/code/HEAD/tree/Gamedata/unitdefs_pre.lua#l36 unitdefs_pre.lua])

{{ExampleRepoLinks
|path = units/
|entity = UnitDefs
}}

[[Category: Game Dev]]

Lua SyncedRead

2021-04-17T09:29:12Z

Beherith: /* Ground */

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

== Game ==

=== Special TeamID Variables ===
The following special TeamIDs are not supported by all functions. For Widgets, instead of Spring.MY_UNITS, use Spring.GetLocalTeamID(). 

{{LuaConstant
|type = number
|name = Spring.ALL_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.MY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ALLY_UNITS
|info =
}}

{{LuaConstant
|type = number
|name = Spring.ENEMY_UNITS
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGaiaTeamID
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} teamID
|info =
}}

=== GameStates ===

{{LuaCallout
|prefix = Spring.
|name = IsGodModeEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsCheatingEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsDevLuaEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsEditDefsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = AreHelperAIsEnabled
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = FixedAllies
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} enabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsGameOver
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} enabled
|info =
}}

=== RulesParams ===
The following functions allow to save data per game, team and unit. The advantage of it is that it can be read from anywhere (even from LuaUI and AIs!) 
String values are new since 95.0.

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParam
|arg1 = {{type|number}} ruleIndex {{pipe}} {{type|string}} ruleName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameRulesParams
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParam
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamRulesParams
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParam
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRulesParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParam
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} index {{pipe}} {{type|string}} ruleName
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|string}} value
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRulesParams
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|ruleName1}} = {{type|number}} value1 {{pipe}} {{type|string}} value1, ... }
|info =
}}

=== Mod-/Map-Options ===

{{LuaCallout
|prefix = Spring.
|name = GetModOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMapOptions
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { } {{pipe}} { "keyName1" = {{type|string}} "value", "keyName2" = {{type|string}} "value", ... }
|info =
}}

Warning: boolean values are not transfered from C to Lua correctly. For this reason the respective option has to be converted to a number and checked accordingly via an IF statement as shown below: 
<pre>if (tonumber(Spring.GetModOptions.exampleOption) == 1) then...end</pre>
The following check therefore is insufficient!
<pre>if (Spring.GetModOptions.exampleOption) then...end</pre>

=== Speed/Time ===

{{LuaCallout
|prefix = Spring.
|name = GetGameSpeed
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} userSpeedFactor, {{type|number}} speedFactor, {{type|bool}} paused
|info = As of 98.0 moved to [[Lua_UnsyncedRead]] due to desyncs in replays/demos
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameFrame
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} frameNum%dayFrames, {{type|number}} frameNum/dayFrames
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGameSeconds
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} seconds
|info =
}}

=== Vectors ===

{{LuaCallout
|prefix = Spring.
|name = GetWind
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ, {{type|number}} strength, {{type|number}} normDirX, {{type|number}} normDirY, {{type|number}} normDirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetHeadingFromVector
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetVectorFromHeading
|arg1 = {{type|number}} heading
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} z
|info =
}}

== Sides/Factions ==

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|string}} sideName
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 = {{type|number}} sideID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} sideName, {{type|string}} startUnit, {{type|string}} caseSensitiveSideName
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetSideData
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = { sideName = {{type|string}}, caseName = {{type|string}}, startUnit = {{type|string}}} }, {{bracket|2}} = { ..., ..., ... }, ... }
|info =
}}

== Teams ==
=== StartBoxes/StartPositions ===

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamStartBox
|arg1 = {{type|number}} allyID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} xMin, {{type|number}} zMin, {{type|number}} xMax, {{type|number}} zMax
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamStartPosition
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

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

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

{{LuaCallout
|prefix = Spring.
|name = GetPlayerList
|arg1 = {{bracket}} {{type|number}} teamID = -1 {{pipe}} {{type|bool}} onlyActive = false {{bracket}}
|arg2 = {{type|number}} teamID {{pipe}} {{type|bool}} onlyActive {{rbracket}} {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} playerID, etc... }
|info = From 104.0 onwards spectators will be ignored if a valid (>=0) teamID is given.
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamList
|arg1 = {{bracket}} {{type|number}} allyTeamID = -1 {{rbracket}}
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamList
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}} teamID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerInfo
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|bool}} active, {{type|bool}} spectator, {{type|number}} teamID, {{type|number}} allyTeamID, {{type|number}} pingTime, {{type|number}} cpuUsage, {{type|string}} "country", {{type|number}} rank, {{type|table}} customPlayerKeys
|info = PRE-83.0: in synced code "name" is "SYNCED_NONAME"!
}}

{{LuaCallout
|prefix = Spring.
|name = GetPlayerControlledUnit
|arg1 = {{type|number}} playerID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAIInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} skirmishAIID, {{type|string}} "name", {{type|number}} hostingPlayerID, {{type|string}} "shortName", {{type|string}} "version", {{type|table}} options
|info = Note: Before 0.82, the first argument was teamID, and then every other argument with a shifted position. shortName, (synced => "SYNCED_NOSHORTNAME"; non-local => "UNKNOWN") version, (synced => "SYNCED_NOVERSION"; non-local => "UNKNOWN") options (synced & non-local => empty-table)
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllyTeamInfo
|arg1 = {{type|number}} allyteamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamInfo
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID, {{type|number}} leader, {{type|bool}} isDead, {{type|bool}} isAiTeam, {{type|string}} "side", {{type|number}} allyTeam, {{type|number}} incomeMultiplier, {{type|table}} customTeamKeys
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamResources
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} currentLevel, {{type|number}} storage, {{type|number}} pull, {{type|number}} income, {{type|number}} expense, {{type|number}} share, {{type|number}} sent, {{type|number}} received
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} killed, {{type|number}} died, {{type|number}} capturedBy, {{type|number}} capturedFrom, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|string}} "metal" {{pipe}} "energy"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} used, {{type|number}} produced, {{type|number}} excessed, {{type|number}} received, {{type|number}} sent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} cur_max_index
|info = cur_max_index is possible range for startIndex/endIndex :={1..cur_max_index}
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitStats
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex = startIndex {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} stats (see below for table content description)
|info =
}}
<pre> table stats = {
[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
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetTeamLuaAI
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "luaAI"
|info = Returns string containing name of AI defined in file LuaAI.lua as name="<AI name>". Maybe it returns whole table with all values there, but in my LuaAI.lua name is on first position...
}}

=== Teams/PlayersAllied ===

{{LuaCallout
|prefix = Spring.
|name = AreTeamsAllied
|arg1 = {{type|number}} teamID1
|arg2 = {{type|number}} teamID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = ArePlayersAllied
|arg1 = {{type|number}} playerID1
|arg2 = {{type|number}} playerID2
|arg3 = ...
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isAllied
|info =
}}

== Units ==
=== GetUnits ===

{{LuaCallout
|prefix = Spring.
|name = GetAllUnits
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnits
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsSorted
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitDefTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = { {{bracket|1}} = {{type|number}} unitID, ... }, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsCounts
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} countTable = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = count, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitsByDefs
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID {{pipe}} tableUnitDefs = { {{type|number}} unitDefID1, ... }
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitDefCount
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} unitDefID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetTeamUnitCount
|arg1 = {{type|number}} teamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} count
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|number}} teamID {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInBox
|arg1 = {{type|number}} xmin, {{type|number}} ymin, {{type|number}} zmin
|arg2 = {{type|number}} xmax, {{type|number}} ymax, {{type|number}} zmax {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInSphere
|arg1 = {{type|number}} x, {{type|number}} y, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInCylinder
|arg1 = {{type|number}} x, {{type|number}} z
|arg2 = {{type|number}} radius {{bracket}}
|arg3 = {{type|number}} teamID {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitsInPlanes
|arg1 = {{type|table}} planes = { {{bracket|1}} = {{type|number}} normalVecX, {{type|number}} normalVecY, {{type|number}} normalVecZ, {{type|number}} d }, etc... }
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitTable = { {{bracket|1}} = {{type|number}} unitID, etc... }
|info = Plane normals point towards accepted space, so the acceptance criteria for each plane is:
}}
<pre> radius = unit radius
px, py, pz = unit position
[(nx * px) + (ny * py) + (nz * pz) + (d - radius)] <= 0</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestAlly
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNearestEnemy
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} range {{bracket}}
|arg3 = {{type|bool}} useLOS {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Post 95.0 this no longer returns neutral units.
}}

=== Unit Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidUnitID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} valid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsDead
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isDead
|info = Returns false if unit exists and is alive, true for a brief period of time after unit dies, nil otherwise. Keep this in mind when using (not Spring.GetUnitIsDead() ).
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTooltip
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} tooltip
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefID
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitAllyTeam
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLineage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} lineage {{pipe}} {{type|number}} lineage, {{type|bool}} lineageIsRoot
|info = {{Removed|83.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNeutral
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} neutral
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHealth
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} paralyzeDamage, {{type|number}} captureProgress, {{type|number}} buildProgress
|info = Build progress is returned as floating point number between 0.0 and 1.0.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitArmored
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} armored, {{type|number}} armorMultiple
|info = armorMultiple new in version 0.83.x.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsStunned
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} stunned_or_inbuild, {{type|bool}} stunned, {{type|bool}} inbuild
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMaxRange
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} maxEngagementRange
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitResources
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalMake, {{type|number}} metalUse, {{type|number}} energyMake, {{type|number}} energyUse
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHarvestStorage
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metal
|info = See also {{xtaglink|Gamedev:UnitDefs|harvestStorage}} UnitDef tag.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMetalExtraction
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} metalExtraction
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitExperience
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} experience
|info = 0.82+ and later
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStates
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} unitStates
|info = The unitStates table arguments are:
}}
<pre>unitStates = {
"firestate" = number,
"movestate" = number,
"repeat" = boolean,
"cloak" = boolean,
"active" = boolean,
"trajectory" = boolean,
["autoland" = boolean,]
["autorepairlevel" = number,]
["loopbackattack" = boolean]
} </pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsActive
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} active
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsCloaked
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isCloaked
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSelfDTime
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} time
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitStockpile
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} numStockpiled, {{type|number}} numStockpileQued, {{type|number}} buildPercent
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeight
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRadius
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMass
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBlocking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}} Additional output arguments.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosition
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} basePointX, {{type|number}} basePointY, {{type|number}} basePointZ {{bracket}}, {{type|number}} midPointX, {{type|number}} midPointY, {{type|number}} midPointZ {{bracket}}, {{type|number}} aimPointX, {{type|number}} aimPointY, {{type|number}} aimPointZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBasePosition
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = {{Removed|89.0}} Use GetUnitPosition instead. Returned the bottom of the unit.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDirection
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Returns the direction vector.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitHeading
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info = Returns heading directions used in COB scripts.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitRotation
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitVelocity
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = VelLength new in 95.0, it returns the velocity length in one frame. Multiply by 30 (game frames/s) to get an equivalent to unitDef.speed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitBuildFacing
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} facing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsBuilding
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = Returns what unit a constructor/factory is currently building.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCurrentBuildPower
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} buildPower
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitNanoPieces
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} piece1, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTransporter
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitIsTransporting
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{bracket|1}} = {{type|number}} unitID, etc ... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitShieldState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} weaponID = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} isEnabled, {{type|number}} curPower
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitTravel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} travel, {{type|number}} travelPeriod
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFuel
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} fuel
|info = Marked as deprecated.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "dir"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} "mode" {{pipe}} {{type|string}} "dir" {{pipe}} {{type|string}} "moveFactor" {{pipe}} {{type|string}} "minDamage" {{pipe}} {{type|string}} "maxDamage"
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} flankingBonusMode {{pipe}} {{type|number}} flankingBonusDir.x, {{type|number}} flankingBonusDir.y, {{type|number}} flankingBonusDir.z {{pipe}} {{type|number}} flankingBonusMobilityAdd {{pipe}} {{type|number}} minDamage {{pipe}} {{type|number}} maxDamage
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitFlanking
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mode, {{type|number}} modilityAdd, {{type|number}} minDamage, {{type|number}} maxDamage, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSensorRadius
|arg1 = {{type|number}} unitID
|arg2 = {{type|string}} type
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info = Possible types are: los, airLos, radar, sonar, seismic, radarJammer, sonarJammer
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLosState
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} allyTeamID {{bracket}}
|arg3 = {{type|bool}} raw {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} raw {{pipe}} {{bracket}} {{type|string}} "los" = true {{bracket}}, {{type|string}} "radar" = true {{bracket}}, {{type|string}} "typed" = true {{rbracket}}{{rbracket}}{{rbracket}}
|info = Raw is only available in gadgets.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitSeparation
|arg1 = {{type|number}} unitID1
|arg2 = {{type|number}} unitID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{bracket}}
|arg4 = {{type|bool}} surfaceDist {{rbracket}}{{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = SurfaceDist new in 95.0. Returns the distance of two units. SurfaceDist calculates the distance between the unitsphere surfaces instead of their midpos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitFeatureSeparation
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} featureID {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitDefDimensions
|arg1 = {{type|number}} unitDefID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} defDimensions
|info = DefDimensions table arguments are:
}}
<pre>defDimensions = {
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttacker
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitLastAttackedPiece
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitMoveTypeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} movetypeData
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

==== Unit Weapon Informations ====

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} angleGood, {{type|bool}} loaded, {{type|number}} reloadFrame, {{type|number}} salvoLeft, {{type|number}} numStockpiled
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponState
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

The following 4 tags were added in 104.0:
"salvoError"
"salvoLeft"
"nextSalvo"
"targetMoveError"</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum {{pipe}} {{type|string}} "selfDestruct" {{pipe}} {{type|string}} "explode"
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} tagVariable
|info = String argument "tag" can return a specific variable. Possilbe tags are:
}}
<pre> "paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponVectors
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTryTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} For a position it just checks if the weapon can attackGround. For a unit existance, category, death status, crashing status, LOS status, neutral status, ally status and transport status are checked.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks TryTarget, TestRange, and that weapon emit point is not below ground, then checks FreeLineOfFire.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTestRange
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Checks if target is in range including height modifiers and cylinder targeting if set.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|94.0}} Runs a raytrace from unit aimpoint respecting collision flags.
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponHaveFreeLineOfFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|number}} targetID {{pipe}} {{bracket}} {{type|number}} srcPosX {{bracket}}
|arg4 = {{type|number}} srcPosY {{bracket}}
|arg5 = {{type|number}} srcPosZ {{bracket}}
|arg6 = {{type|number}} tgtPosX {{bracket}}
|arg7 = {{type|number}} tgtPosY {{bracket}}
|arg8 = {{type|number}} tgtPosZ {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} success
|info = {{new|104.0}} The param list was changed so that the source firing position can also be passed.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponCanFire
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} canFire
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitWeaponTarget
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} 0 {{pipe}} {{type|number}} 1, {{type|bool}} isUserTarget, {{type|number}} unitID {{pipe}} {{type|number}} 2, {{type|bool}} isUserTarget, { {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ } {{pipe}} {{type|number}} 3, {{type|bool}} isUserTarget, {{type|number}} projectileID
|info = {{new|95.0}} Returned number of args is always 3 if targetType != None.
}}

{{LuaCallout
|prefix = Spring.
|name = GetRadarErrorParams
|arg1 = {{type|number}} allyTeamID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyteamErrorSize, {{type|number}} baseErrorSize, {{type|number}} baseErrorMult
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPosErrorParams
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posErrorVector.x, {{type|number}} posErrorVector.y, {{type|number}} posErrorVector.z, {{type|number}} posErrorDelta.x, {{type|number}} posErrorDelta.y, {{type|number}} posErrorDelta.z, {{type|number}} nextPosErrorUpdatebaseErrorMult
|info = {{new|95.0}}
}}

==== Unit LOS ====

{{LuaCallout
|prefix = Spring.
|name = IsUnitInLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInAirLos
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inAirLOS
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInRadar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inRadar
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = IsUnitInJammer
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} allyID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} inJammer
|info = {{new|101.0}}
}}

=== Unit Pieces ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitVectors
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} { {{type|number}} frontX, {{type|number}} frontY, {{type|number}} frontZ } , { {{type|number}} upX, {{type|number}} upY, {{type|number}} upZ } , { {{type|number}} rightX, {{type|number}} rightY, {{type|number}} rightZ }
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosition
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceDirection
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPiecePosDir
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMatrix
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceList
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceMap
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceInfo
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptPiece
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} scriptPiece {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{bracket}} {{type|number}} scriptPieceNum = {{type|number}} modelPieceNum {{rbracket}} {{pipe}} {{type|number}} modelPieceNum
|info = 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 a pieceID via Cob2Lua you have to translate it with this function. Btw. the COB ScriptPiece number is equal with the piece position in the piece definition in your cob/bos.
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitScriptNames
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "cobpiecename1" = {{type|number}} ScriptPieceNum1, ... , {{type|string}} "cobpiecenameN" = {{type|number}} ScriptPieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetUnitPieceCollisionVolumeData
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} scaleX,{{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = As of 101.0 this is 1-based piece index argument (was 0-based).
}}

=== CommandQueues ===

Spring.GetCommandQueue function is identical to Spring.GetUnitCommands function. Here only Spring.GetUnitCommands will be listed:

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetUnitCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = This function can trigger an error if called too often without passing a second parameter. Refer to [https://github.com/spring/spring/blob/92c54d5b15775c39a8c67b203c28fe9b9db51cea/rts/Lua/LuaSyncedRead.cpp#L3983-L3996 LuaSyncedRead.cpp#L3983-L3996]. CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFullBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetRealBuildQueue
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} buildOrders = { {{bracket|1}} = { {{bracket}}{{type|number}} unitDefID{{rbracket}} = {{type|number}} count }, etc... }
|info = Cleans the buildqueue of things the unit can't build itself.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} count = 0
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} commandQueueSize
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCommands
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count = -1 {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable
|info = CommandQueueTable table arguments are:
}}
<pre>commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFactoryCounts
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} count {{bracket}}
|arg3 = {{type|bool}} addCMDs {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandQueueTable = { {{bracket|2}} = { {{bracket}}{{type|number}} unitDefID {{pipe}} {{type|number}} -cmdID{{rbracket}} = {{type|number}} count }, ... }
|info = Gets the buildqueue of a factory.
}}

=== Command Descriptions/Buttons ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitCmdDescs
|arg1 = {{type|number}} unitID {{bracket}}
|arg2 = {{type|number}} startIndex {{bracket}}
|arg3 = {{type|number}} endIndex {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} commandDescTable
|info = CommandDescTable arguments are:
}}
<pre>commandDescTable = {
[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, ... }
}, ...
}</pre>

{{LuaCallout
|prefix = Spring.
|name = FindUnitCmdDesc
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} cmdID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} index
|info =
}}

== Features ==
=== GetFeatures ===

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInRectangle
|arg1 = {{type|number}} xMin
|arg2 = {{type|number}} zMin
|arg3 = {{type|number}} xMax
|arg4 = {{type|number}} zMax
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInSphere
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} radius
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturesInCylinder
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 = {{type|number}} radius
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetAllFeatures
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} featureTable = { {{bracket|1}} = {{type|number}} featureID, etc... }
|info =
}}

=== Feature Informations ===

{{LuaCallout
|prefix = Spring.
|name = ValidFeatureID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isValid
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDefID
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} featureDefID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureAllyTeam
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} allyID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHealth
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} health, {{type|number}} maxHealth, {{type|number}} resurrectProgress
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeight
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} height
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRadius
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} radius
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureMass
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} mass
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureSeparation
|arg1 = {{type|number}} featureID1
|arg2 = {{type|number}} featureID2 {{bracket}}
|arg3 = {{type|bool}} 2D {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} distance
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePosition
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} midPos {{bracket}}
|arg3 = {{type|bool}} aimPos {{rbracket}}{{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} bpX, {{type|number}} bpY, {{type|number}} bpZ {{bracket}}, {{type|number}} mpX, {{type|number}} mpY, {{type|number}} mpZ {{bracket}}, {{type|number}} apX, {{type|number}} apY, {{type|number}} apZ {{rbracket}}{{rbracket}}
|info = Since 89.0, returns the base (default), middle or aim position of the feature.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureVelocity
|arg1 = {{type|number}} featureID {{bracket}}
|arg2 = {{type|bool}} norm {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ, {{type|number}} velLength
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureDirection
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureRotation
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} pitch, {{type|number}} yaw, {{type|number}} roll
|info = {{New|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureHeading
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} heading
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResources
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} RemainingMetal, {{type|number}} maxMetal, {{type|number}} RemainingEnergy, {{type|number}} maxEnergy, {{type|number}} reclaimLeft, {{type|number}} reclaimTime
|info = reclaimTime {{new|105.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureNoSelect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} noSelect
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureResurrect
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} UnitDefName, {{type|number}} buildFacing
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceCollisionVolumeData
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceID
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} scaleX, {{type|number}} scaleY, {{type|number}} scaleZ, {{type|number}} offsetX, {{type|number}} offsetY, {{type|number}} offsetZ, {{type|number}} volumeType, {{type|number}} testType, {{type|number}} primaryAxis, {{type|bool}} disabled
|info = {{new|101.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeatureBlocking
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBlocking, {{type|bool}} isSolidObjectCollidable, {{type|bool}} isProjectileCollidable, {{type|bool}} isRaySegmentCollidable, {{type|bool}} crushable, {{type|bool}} blockEnemyPushing, {{type|bool}} blockHeightChanges
|info = {{new|95.0}}
}}

=== Feature Pieces ===

Works analogue to #Unit_Pieces

{{LuaCallout
|prefix = Spring.
|name = GetFeatureLastAttackedPiece
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} pieceName, {{type|number}} gameframe
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMap
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{type|string}} "piecename1" = {{type|number}} pieceNum1, ... , {{type|string}} "piecenameN" = {{type|number}} pieceNumN }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceList
|arg1 = {{type|number}} featureID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|string}} "piecename", ... , {{bracket|pieceNumN}} = {{type|string}} "piecename" }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceInfo
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|table}} pieceInfo
|info = {{new|95.0}} "parent" field {{new|101.0}} parent for root pieces is now "[null]" instead of "" table pieceInfo contains:
}}
<pre>pieceInfo = {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}</pre>

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosition
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info = Returns piece position in unit space. Also remember to multiply the x-axis value with -1 if you want to move a piece to another piece.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceDirection
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = Fixed since 101. Now returns the same direction as Spring.GetUnitPiecePosDir.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePiecePosDir
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} pieceNum
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ, {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = 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.
}}

{{LuaCallout
|prefix = Spring.
|name = GetFeaturePieceMatrix
|arg1 = {{type|number}} featureID
|arg2 = {{type|number}} piece
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = { {{bracket|1}} = {{type|number}}, ... , {{bracket|16}} = {{type|number}} }
|info =
}}

== COB ==

{{LuaCallout
|prefix = Spring.
|name = GetCOBUnitVar
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBTeamVar
|arg1 = {{type|number}} teamID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBAllyTeamVar
|arg1 = {{type|number}} allyID
|arg2 = {{type|number}} varID {{bracket}}
|arg3 = {{type|bool}} unpack = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetCOBGlobalVar
|arg1 = {{type|number}} varID {{bracket}}
|arg2 = {{type|bool}} unpack = false {{rbracket}}
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} value {{pipe}} {{type|number}} unpackedX, {{type|number}} unpackedY
|info =
}}

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

{{LuaCallout
|prefix = Spring.
|name = GetGroundHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundOrigHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info = This returns the ground's original height (i.e. before terraforming) at a given x,z position.
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundNormal
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z {{bracket}}
|arg3 = {{type|bool}} smoothedNormal = false {{rbracket}}
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} x, {{type|number}} y, {{type|number}} z, {{type|number}} slope
|info = {{new|100.0}}: smoothedNormal and slope
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundInfo
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|string}} "Type", {{type|number}} metal, {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

or

{{LuaCallout
|prefix = Spring.
|name = GetGroundBlocked
|arg1 = {{type|number}} x1
|arg2 = {{type|number}} z1
|arg3 = {{type|number}} x2
|arg4 = {{type|number}} z2
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "feature", {{type|number}} featureID {{pipe}} {{type|string}} "unit", {{type|number}} unitID
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetGroundExtremes
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} minHeight, {{type|number}} maxHeight
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetSmoothMeshHeight
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} y
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalMapSize
|arg1 =
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} sizeX, {{type|number}} sizeY
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalAmount
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} metalAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetMetalExtraction
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} extractionAmount
|info = With x & z in metal map coordinates (worldspace/16)
}}

{{LuaCallout
|prefix = Spring.
|name = GetTerrainTypeData
|arg1 = {{type|number}} i
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} "name", {{type|number}} hardness, {{type|number}} tankSpeed, {{type|number}} kbotSpeed, {{type|number}} hoverSpeed, {{type|number}} shipSpeed, {{type|bool}} receiveTracks
|info = {{new|92.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetGrass
|arg1 = {{type|number}} x
|arg2 = {{type|number}} z
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} 0 {{pipe}} {{type|number}} 1 {{pipe}} {{type|number}} 255
|info = With x & z in worldspace coordinates. Returns 255 if grass is disabled in settings, or if map does not have a grassmap specified.
}}

=== Test Orders ===

{{LuaCallout
|prefix = Spring.
|name = TestMoveOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} pos.x {{bracket}}, {{type|number}} pos.y {{bracket}}, {{type|number}} pos.z {{bracket}}
|arg3 = {{type|number}} dir.x {{bracket}}, {{type|number}} dir.y {{bracket}}, {{type|number}} dir.z {{bracket}}
|arg4 = {{type|bool}} testTerrain {{bracket}}
|arg5 = {{type|bool}} testObjects {{bracket}}
|arg6 = {{type|bool}} centerOnly {{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} validMove
|info = {{New|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = TestBuildOrder
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} facing
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|number}} blocking {{bracket}}, {{type|number}} featureID {{rbracket}}
|info =
}}
<pre>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"</pre>

{{LuaCallout
|prefix = Spring.
|name = Pos2BuildPos
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z {{bracket}}
|arg5 = {{type|number}} facing {{rbracket}}
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info =
}}

=== PathFinding ===

{{LuaCallout
|prefix = Spring.
|name = GetUnitEstimatedPath
|arg1 = {{type|number}} unitID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} waypoints, {{type|table}} waypointIndices
|info = The table arguments are:
}}
<pre>table waypoints = {
[1] = { x,y,z }, ...
}

table waypointIndices= {
[1] = startIdxOfDetailedPath,
[2] = startIdxOfDetailedEstimatedPath1,
[3] = startIdxOfDetailedEstimatedPath2,
}

GetUnitEstimatedPath() returns 2 tables:
1 table the waypoints and 1 table with indices (in the waypoint table)
when a new (more lazy) pathfinding algorithm begins.
So the waypoint table contains 3 different levels of details.</pre>

=== LOS ===

{{LuaCallout
|prefix = Spring.
|name = IsPosInLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInRadar
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInRadar
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = IsPosInAirLos
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z
|arg4 = {{type|number}} allyID
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} isInAirLos
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPositionLosState
|arg1 = {{type|number}} x
|arg2 = {{type|number}} y
|arg3 = {{type|number}} z {{bracket}}
|arg4 = {{type|number}} allyID {{rbracket}}
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|bool}} LosOrRadar, {{type|bool}} inLos, {{type|bool}} inRadar, {{type|bool}} jammed
|info = Jammed new in 95.0, indicates if a position is actively being radar- or sonar-jammed by ANY allyteam.
}}

{{LuaCallout
|prefix = Spring.
|name = GetClosestValidPosition
|arg1 = {{type|number}} unitDefID
|arg2 = {{type|number}} x
|arg3 = {{type|number}} y
|arg4 = {{type|number}} z
|arg5 = {{type|number}} r
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}}
|info = CURRENTLY UNFINISHED! Always returns nil!
}}

== Projectiles ==

{{LuaCallout
|prefix = Spring.
|name = GetProjectilesInRectangle
|arg1 = {{type|number}} xmin
|arg2 = {{type|number}} zmin
|arg3 = {{type|number}} xmax
|arg4 = {{type|number}} zmax {{bracket}}
|arg5 = {{type|bool}} excludeWeaponProjectiles {{bracket}}
|arg6 = {{type|bool}} excludePieceProjectiles {{rbracket}}{{rbracket}}
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|table}} projectileTable = { {{bracket|1}} = {{type|number}} projectileID, etc... }
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileOwnerID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} unitID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTeamID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} teamID
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDefID
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} weaponDefID
|info = Using this to get a weaponDefID is HIGHLY preferred to indexing WeaponDefNames via GetProjectileName.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileName
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|string}} name
|info = It is recommended to rather use GetProjectileDefID for indexing purposes.
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileType
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} weapon, {{type|bool}} piece
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTarget
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} targetTypeInt, {{type|number}} targetID {{pipe}} {{type|table}} targetPos = {x, y, z}
|info =
}}
<pre>Pre version 95.0 return arguments: -> nil | number targetID, string targetTypeStr

targetTypeStr could be one of:
'u' - unit
'f' - feature
'p' - projectile

while targetTypeInt was one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE</pre>

{{LuaCallout
|prefix = Spring.
|name = GetProjectileIntercepted
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|bool}} isBeingIntercepted
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectilePosition
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} posX, {{type|number}} posY, {{type|number}} posZ
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileVelocity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} velX, {{type|number}} velY, {{type|number}} velZ
|info = {{new|95.0}}: returns (targetPos - startPos) for Beamlasers and similar weapons
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileGravity
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} gravity
|info =
}}

{{LuaCallout
|prefix = Spring.
|name = GetPieceProjectileParams
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} explosionFlags, {{type|number}} spinAngle, {{type|number}} spinSpeed, {{type|number}} spinVectorX, {{type|number}} spinVectorY, {{type|number}} spinVectorZ
|info = {{new|95.0}} ExplosionFlags use binary flags with the following integer equivalents (more info [http://springrts.com/wiki/Animation-CobConstants#explode here] ): SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16, NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileTimeToLive
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} ttl
|info = {{new|99.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDirection
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} dirX, {{type|number}} dirY, {{type|number}} dirZ
|info = {{new|95.0}}
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinAngle
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} angle
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinSpeed
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} spinSpeed
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileSpinVec
|arg1 = {{type|number}} projectileID
|arg2 =
|arg3 =
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} x, {{type|number}} y, {{type|number}} z
|info = Deprecated in 95.0 - use GetPieceProjectileParams instead!
}}

{{LuaCallout
|prefix = Spring.
|name = GetProjectileDamages
|arg1 = {{type|number}} unitID
|arg2 = {{type|number}} weaponNum
|arg3 = {{type|string}} tag
|arg4 =
|arg5 =
|arg6 =
|arg7 =
|arg8 =
|arg9 =
|return = {{type|nil}} {{pipe}} {{type|number}} damage
|info = {{new|101.0}}
}}
<pre>The string tag can be:
"paralyzeDamageTime"
"impulseFactor"
"impulseBoost"
"craterMult"
"craterBoost"
"dynDamageExp"
"dynDamageMin"
"dynDamageRange"
"dynDamageInverted"
"craterAreaOfEffect"
"damageAreaOfEffect"
"edgeEffectiveness"
"explosionSpeed"
- or -
an armor type index to get the damage against it.</pre>

[[category: Lua]]

Lua OpenGL Api

2021-04-15T09:53:27Z

Beherith: /* PixelReadback */

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

= Spring =
'''gl.GetSun'''
() -> number sunPosX, number sunPosY, number sunPosZ
( "pos" ) -> number sunPosX, number sunPosY, number sunPosZ
( "shadowDensity" [, "unit"] ) -> number shadowDensity
( "diffuse" [, "unit"] ) -> nil | number r, number g, number b
( "ambient" [, "unit"] ) -> nil | number r, number g, number b
( "specular" [, "unit"] ) -> nil | number r, number g, number b

'''gl.GetAtmosphere''' {{new|101.0}}
( string name ) -> number r, number g, number b

See [[Lua_UnsyncedCtrl#Sun|Spring.SetAtmosphere]] for details.

'''gl.GetWaterRendering''' {{new|104.0}}
( string name ) -> number r, number g, number b | string texName | number scalar | boolean active | nil

See [[Lua_UnsyncedCtrl#Developers|Spring.SetWaterParams]] for details.

'''gl.GetMapRendering''' {{new|104.0}}
( string name ) -> number r, number g, number b | boolean active | nil

See [[Lua_UnsyncedCtrl#Developers|Spring.SetMapRenderingParams]] for details.

'''gl.ConfigScreen''' used for Unit LODs
( number screenWidth, number screenDistance ) -> nil

'''gl.DrawMiniMap''' argument new in 0.82+
( boolean tansform = true ) -> nil

'''gl.SlaveMiniMap'''
( boolean mode ) -> nil

'''gl.ConfigMiniMap'''
( int px, int py, int sx, int sy ) -> nil

'''gl.GetViewSizes'''
( ) -> number x, number y

= Matrices & Viewport =
'''gl.Viewport'''
( number x, number y, number w, number h ) -> nil

'''gl.PushMatrix'''
() -> nil

'''gl.PopMatrix'''
() -> nil

'''gl.Translate'''
(number x, number y, number z) -> nil

'''gl.Scale'''
( number x, number y, number z ) -> nil

'''gl.Rotate'''
( number angle, number x, number y, number z ) -> nil

'''gl.Billboard'''
( ) -> nil
Use this to draw 2d primitives in DrawWorld().
To render a 2D billboarded quad in the gameworld at world position x,y,z, you do the following (at a minimum; I am skipping blending / depthtesting) here:
gl.PushMatrix()
gl.Texture(read what you need here)
gl.Translate(x,y,z)
gl.Billboard()
gl.TexRect(x1,y1,x2,y2)
gl.PopMatrix()

'''gl.MatrixMode'''
( number [[Lua_ConstGL#MatrixMode|mode]] ) -> nil

'''gl.LoadIdentity'''
( ) -> nil

'''gl.LoadMatrix'''
( 16 numbers or a [https://github.com/spring/spring/blob/develop/rts/Lua/LuaOpenGLUtils.cpp#L60 matrix name] ) -> nil

'''gl.MultMatrix'''
( ?? ) -> ??

'''gl.Ortho'''
( number left, number right, number bottom, number top, number near, number far ) -> nil

'''gl.Frustum'''
( number left, number right, number bottom, number top, number near, number far ) -> nil

'''gl.PushPopMatrix'''
( ?? ) -> ??

'''gl.ClipPlane'''
( int plane, note: $plane can only be 1 or 2
boolean enable |
number A, number B, number C, number D ) -> nil

= Clear =
'''gl.Clear'''
( GL.DEPTH_BUFFER_BIT [, number cleardepth] ) -> nil
( GL.STENCIL_BUFFER_BIT [, int clearstencil] ) -> nil
( GL.COLOR_BUFFER_BIT | GL.ACCUM_BUFFER_BIT [, number r, number g, number b, number a] ) -> nil

'''gl.SwapBuffers''' {{new|104.0}}
() -> nil

Available only in LuaMenu, meant for frame-limited LuaMenu's that want identical content in both buffers.

= ResetState/Matrices =
'''gl.ResetState''' DON'T USE IT UNLESS YOU KNOW WHAT YOU ARE DOING! Each call-in has different default states, but this function resets all states to the states below no matter what!
() -> nil

ShadeModel = GL.SMOOTH
Scissor = false
Texture = false
Lighting = false,
ColorMask = true, true, true, true
DepthMask = false
DepthTest = false (GL.LEQUAL)
Culling = false (GL.BACK)
LogicOp = false (GL.INVERT)
AlphaTest = false (GL.GREATER, 0.5f)
Blending = true (GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA)


'''gl.ResetMatrices'''
() -> nil

Resets GL.TEXTURE matrix stack
Resets GL.MODELVIEW matrix stack
Resets GL.PROJECTION matrix stack


= Draw Basics =
'''gl.BeginEnd'''
( number [[Lua_ConstGL#Drawing_Primitives|GLType]], function [, arg1,... ] ) -> nil

'''gl.Color'''
( { number r, number g, number b[, number a] } |
number r, number g, number b[, number a] ) -> nil

'''gl.Vertex'''
( { number x, number y [, number z [, number w ]] } |
number x, number y |
number x, number y, number z |
number x, number y, number z, number w ) -> nil

'''gl.Normal'''
( number x, number y, number z |
{ number x, number y, number z } ) -> nil

'''gl.EdgeFlag'''
( boolean enable ) -> nil

'''gl.Rect'''
( number x1, number y1, number x2, number y2 ) -> nil

'''gl.TexRect''' texture rect
( number x1, number y1, number x2, number y2,
[ boolean flip_s, boolean flip_t | number s1, number t1, number s2, number t2 ] ) -> nil

'''gl.Shape'''
( number [[Lua_ConstGL#Drawing_Primitives|GLtype]],
elements = {
[1] = { v | vertex = { number x, number y, number z }, required
n | normal = { number x, number y, number z }, optional
t | texcoord = { number x, number y }, optional
c | color = { number r, number g, number b, number a } optional
},
etc ...
}
) -> nil

'''gl.SecondaryColor'''
( { number r, number g, number b } |
number r, number g, number b ) -> nil

'''gl.FogCoord'''
( number value ) -> nil

= Display Lists =
Display Lists save given vertex attributes in a static buffer, so the GPU can directly read them (without the CPU). Display Lists are a lot faster (10-60x) than standard drawing with glShape/glBeginEnd, so try to use them when ever you can. If you want to learn more about them, g00gle is your friend ;)

'''gl.CreateList'''
( function [,arg1 [,arg2...]] ) -> number listID

'''gl.CallList'''
( number listID ) -> nil

'''gl.DeleteList'''
( number listID ) -> nil

= Vertex Array Objects =
 Only available in "develop" branch of spring (the future 105.0+). This is conceptually similar and serve as modern OpenGL replacement to deprecated Display Lists. 

'''gl.CreateVertexArray'''
( number numElements, number numIndices, [boolean persistentBuffer = false] ) -> number bufferID

See what elements and indices are here: http://www.opengl-tutorial.org/intermediate-tutorials/tutorial-9-vbo-indexing/ 
numElements and numIndices define the size of for elements and indices respectively. if indices are not going to be used, then set numIndices to 0 
Persistent buffers (persistentBuffer = true) are more efficient for dynamically/often updated geometry. 

'''gl.UpdateVertexArray'''
( number bufferID, number elementPos, number indexPos, table tbl | function func ) -> boolean success

{elementPos, indexPos} define starting element in {element, index} VBO corresponding to 1st element of the supplied vertex data 
4 elements table example: 
local verts = {
p = {0,0,0,1, 4,0,0,1, 4,4,0,1, 0,4,0,1},
n = {0,1,0 , 0,1,0 , 0,1,0 , 0,1,0 },
uv = {0,0,0,0, 1,0,0,0, 1,1,0,0, 0,1,0,0},
c0 = {1,0,0,1, 0,1,0,1, 0,0,1,1, 1,1,1,0},
i = {0, 1, 2, 2, 1, 3}, optional, use in case of indexed VBO
c1 = {...} }
 Alternatively Lua func can use gl.Vertex/gl.Color/gl.Normal/gl.TexCoord to define vertices, similarly how it used to be done in gl.BeginEnd.Note there is no function yet to define indices. 

'''gl.RenderVertexArray'''
( number bufferID, number primType, [number firstIndex = 0, count = numElements] ) -> boolean success
primType can be GL.POINTS, GL.LINE_STRIP, GL.LINE_LOOP, GL.LINES, GL.LINE_STRIP_ADJACENCY, GL.LINES_ADJACENCY, GL.TRIANGLE_STRIP, GL.TRIANGLE_FAN, GL.TRIANGLES, GL.TRIANGLE_STRIP_ADJACENCY, GL.TRIANGLES_ADJACENCY and GL.PATCHES 
firstIndex specifies the starting index in the enabled arrays. 
count specifies the number of indices to be rendered. 

'''gl.DeleteVertexArray'''
( number bufferID ) -> boolean success
Releases previously allocated VAO 

= Text =
'''gl.Text'''
(string "text", number x, number y, number size [, string "options"] )

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

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

'''gl.GetTextWidth'''
(string "text") -> number width (in pixels, with a font size of 1.0)

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

If you have multiple gl.Text calls, then you can bunch them between a gl.BeginText and gl.EndText to speedup the rendering. 
'''gl.BeginText'''
( ) -> nil
'''gl.EndText'''
( ) -> nil

= Unit/Feature Draw Functions =
'''gl.Unit''' (draws an unit; on default it uses LOD, with lod<0 it is turned off, else it defines a specific level)
( number unitID, [ boolean rawdraw, int lod ] ) -> nil

'''gl.UnitRaw''' (doesn't apply worldspace->unit transformation! only works if rawdraw is true )
( number unitID, [ boolean rawdraw, int lod ] ) -> nil

'''gl.UnitShape'''
( number unitDefID, number teamID, bool rawState, bool toScreen, bool opaque ) -> nil

{{new|101.0}} The three extra boolean arguments make it so that calling only these functions is enough to get correctly rendered models; pass in 'false' for the THIRD argument to get the fixed behavior, omit it or pass in 'true' [default] to render with your own custom state instead. The FOURTH argument should be 'true' if in DrawScreen and 'false' (default) if in DrawWorld; any transforms for these two functions *MUST* include a gl.LoadIdentity call when argument #3 is false (whether they are used in DrawWorld or in DrawScreen) the FIFTH argument determines whether the model is drawn opaque ('true' [default]) or with translucency ('false'); only has an effect when argument #3 is false.

'''gl.UnitMultMatrix''' (world space -> unit space)
( number unitID ) -> nil

'''gl.UnitPieceMultMatrix''' (unit space -> piece space)
( number unitID, int piece ) -> nil

'''gl.UnitPiece''' (draws the unit piece)
( number unitID, int piece ) -> nil

'''gl.UnitPieceMatrix''' (use gl.UnitPieceMultMatrix instead!)
( number unitID, int piece ) -> nil

'''gl.Feature'''
( number featureID ) -> nil

'''gl.FeatureRaw''' {{new|101.0}}
( number featureID, [ boolean rawdraw, int lod ] ) -> nil

'''gl.FeatureShape'''
( number featureDefID, number teamID, bool custom, bool drawScreen, bool opaque ) -> nil

'''gl.FeatureMultMatrix''' {{new|101.0}} (world space -> feature space)
( number featureID ) -> nil

'''gl.FeaturePieceMultMatrix''' {{new|101.0}} (feature space -> piece space)
( number featureID, int piece ) -> nil

'''gl.FeaturePiece''' {{new|101.0}} (draws the Feature piece)
( number featureID, int piece ) -> nil

'''gl.FeaturePieceMatrix''' {{new|101.0}} (use gl.FeaturePieceMultMatrix instead!)
( number featureID, int piece ) -> nil

'''gl.DrawListAtUnit'''
( number unitID, number listID, [ boolean midPos,
number scaleX, number scaleY, number scaleZ,
number degrees, number rotX, number rotX, number rotZ ] ) -> nil

'''gl.DrawFuncAtUnit'''
( number unitID, boolean midPos, function [, arg1,... ]) -> nil

= States (Blending,AlphaTest...) =
'''gl.Blending'''
( boolean enable | number [[Lua_ConstGL#BlendingFactorSrc|srcmode]], number [[Lua_ConstGL#BlendingFactorDest|dstmode]] ) -> nil
( string mode ) -> nil
{| cellpadding="0" cellspacing="0" style="margin-top: -5px; margin-left:5px"
! style="color:#55ee99" | mode maybe:
|-
| style="color:#55ee99" | "add"
| style="color:#55ee99" | = GL.ONE, GL.ONE
|-
| style="color:#55ee99" | "alpha_add"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE
|-
| style="color:#55ee99" | "alpha"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
|-
| style="color:#55ee99" | "reset"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
|-
| style="color:#55ee99" | "color"
| style="color:#55ee99" | = GL.SRC_COLOR, GL.ONE_MINUS_SRC_ALPHA
|-
| style="color:#55ee99" | "modulate"
| style="color:#55ee99" | = GL.DST_COLOR, GL.ZERO
|-
| style="color:#55ee99" | "disable"
| style="color:#55ee99" | = GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA
|}

'''gl.BlendEquation'''
( number mode ) -> nil

'''gl.BlendFunc'''
( number [[Lua_ConstGL#BlendingFactorSrc|srcmode]], number [[Lua_ConstGL#BlendingFactorDest|dstmode]] ) -> nil

'''gl.BlendEquationSeparate''' (needs openGL2.0!)
( number modeRGB, number modeAlpha ) -> nil

'''gl.BlendFuncSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#BlendingFactorSrc|srcRGB]], number [[Lua_ConstGL#BlendingFactorDest|dstRGB]], number [[Lua_ConstGL#BlendingFactorSrc|srcAlpha]], number [[Lua_ConstGL#BlendingFactorDest|dstAlpha]] ) -> nil

'''gl.AlphaTest'''
( boolean enable | number [[Lua_ConstGL#AlphaFunction and DepthFunction|func]], number threshold ) -> nil

'''gl.DepthTest'''
( boolean enable | number [[Lua_ConstGL#AlphaFunction and DepthFunction|func]] ) -> nil

'''gl.Culling'''
( boolean enable | number [[Lua_ConstGL#Culling|face]] ) -> nil

'''gl.DepthClamp''' not always available, needs GL.NV_depth_clamp!
( boolean enable ) -> nil

'''gl.DepthMask'''
( boolean enable ) -> nil

'''gl.ColorMask'''
( boolean ) -> nil
( boolean r, boolean g, boolean b, boolean a ) -> nil

'''gl.LogicOp'''
( boolean enable | number [[Lua_ConstGL#LogicOp|func]] ) -> nil

'''gl.Fog'''
( boolean enable ) -> nil

'''gl.Smoothing''' {{removed|104.0}}
( (boolean enable | number POINT),
(boolean enable | number LINE),
(boolean enable | number POLYGON) ) -> nil

'''gl.EdgeFlag'''
( boolean enable ) -> nil

'''gl.Scissor'''
( boolean ) -> nil
( int x, int y, int w, int h ) -> nil

'''gl.LineStipple'''
( string any ) -> nil (use springs default line stipple)
( boolean enable ) -> nil
( int factor, number pattern ) -> nil

'''gl.PolygonMode'''
( number [[Lua_ConstGL#Culling|face]], number [[Lua_ConstGL#PolygonMode|mode]] ) -> nil

'''gl.PolygonOffset'''
( boolean enable | number factor, number units ) -> nil

'''gl.PushAttrib'''
( [ number [[Lua_ConstGL#glPushAttrib.28.29_bits|attrib]] ] ) -> nil

'''gl.PopAttrib'''
() -> nil

= Stencil =
'''gl.StencilTest'''
( boolean enable ) -> nil
'''gl.StencilMask'''
( number mask ) -> nil
'''gl.StencilFunc'''
( number func, number ref, number mask ) -> nil
'''gl.StencilOp'''
( number fail, number zfail, number zpass ) -> nil

'''gl.StencilMaskSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#Culling|face]], number mask ) -> nil
'''gl.StencilFuncSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#Culling|face]], number func, number ref, number mask ) -> nil
'''gl.StencilOpSeparate''' (needs openGL2.0!)
( number [[Lua_ConstGL#Culling|face]], number fail, number zfail, number zpass ) -> nil

= LineWidth & PointSize =
'''gl.LineWidth'''
( number width ) -> nil

'''gl.PointSize''' (values != 1 can break severely on ATI cards, see http://springrts.com/mantis/view.php?id=2390)
( number size ) -> nil

'''gl.PointSprite''' (needs openGL2.0!)
( boolean enable, [boolean coord_replace, boolean coord_origin_upper] ) -> nil

'''gl.PointParameter''' (needs openGL2.0!)
( number v1, number v2, number v3,
[ number sizeMin, number sizeMax, number sizeFade ] ) -> nil

= Textures =
'''gl.Texture'''
( [ number texNum, ] boolean enable | string name ) -> nil | boolean loaded
This is the only call-out that is needed to load and draw any texture in a Lua script. All you have to do is pass it a valid path to a valid png and it will use that image for drawing any subsequent textured rectangles. This is shown in the last line of the following list of valid strings for the name parameter.


{| cellpadding="0" cellspacing="0" style="margin-top: -5px; margin-left:5px"
! style="color:#55ee99; text-align:left" |`name` may be:
|-
| style="color:#55ee99" | #12
| style="color:#55ee99" | = unitDef 12 buildpic
|-
| style="color:#55ee99" | %34:1
| style="color:#55ee99" | = unitDef 34 s3o tex2 (:0->tex1,:1->tex2)
|-
| style="color:#55ee99" | %-102:0
| style="color:#55ee99" | = featureDef 102 s3o tex1
|-
| style="color:#55ee99" | !56
| style="color:#55ee99" | = lua generated texture 56 (= return value of gl.CreateTexture)
|-
| style="color:#55ee99" | $units
| style="color:#55ee99" | = 3do textureatlas tex1
|-
| style="color:#55ee99" | $units1
| style="color:#55ee99" | = 3do textureatlas tex1
|-
| style="color:#55ee99" | $units2
| style="color:#55ee99" | = 3do textureatlas tex2
|-
| style="color:#55ee99" | $shadow
| style="color:#55ee99" | = shadowmap
|-
| style="color:#55ee99" | $specular
| style="color:#55ee99" | = specular cube map (removed in the latest develop)
|-
| style="color:#55ee99" | $reflection
| style="color:#55ee99" | = reflection cube map (can be mipmaped starting from 104.0.1-714-ga29177f. Set CubeTexGenerateMipMaps=1 in settings)
|-
| style="color:#55ee99" | $shading
| style="color:#55ee99" | = ground shading texture
|-
| style="color:#55ee99" | $grass
| style="color:#55ee99" | = grass shading texture
|-
| style="color:#55ee99" | $heightmap
| style="color:#55ee99" | = heightmap (needs HeightMapTexture=1 set in spring config)
|-
| style="color:#55ee99" | $minimap
| style="color:#55ee99" | = minimap texture
|-
| style="color:#55ee99" | $map_reflection
| style="color:#55ee99" | = same as "$reflection" {{new|101.0}}
|-
| style="color:#55ee99" | $sky_reflection
| style="color:#55ee99" | = defined for SSMF maps that have a skyReflectModTex {{new|101.0}}
|-
| style="color:#55ee99" | $detail
| style="color:#55ee99" | = detail texture {{new|101.0}}
|-
| style="color:#55ee99" | $normals
| style="color:#55ee99" | = auto generated normals texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_normals
| style="color:#55ee99" | = SSMF normals texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_specular
| style="color:#55ee99" | = SSMF specular texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_distr
| style="color:#55ee99" | = SSMF splat distribution texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_detail
| style="color:#55ee99" | = SSMF splat detail texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_splat_normals
| style="color:#55ee99" | = SSMF splat normals texture {{new|101.0}}, used as "$ssmf_splat_normals" or "$ssmf_splat_normals:X", 'X' can be a value between 0 and 3, defaults to 0 if ":X" is omitted
|-
| style="color:#55ee99" | $ssmf_emission
| style="color:#55ee99" | = SSMF emission texture {{new|101.0}}
|-
| style="color:#55ee99" | $ssmf_parallax
| style="color:#55ee99" | = SSMF parallax texture {{new|101.0}}
|-
| style="color:#55ee99" | $info
| style="color:#55ee99" | = currently active info texture (los, airlos, radar, jammer) Note that textures contain no data until user switches to their respective modes and non-active textures are not updated in the background, so will go stale
|-
| style="color:#55ee99" | $info_losmap
| style="color:#55ee99" | = los texture (L-view)
|-
| style="color:#55ee99" | $info_mtlmap
| style="color:#55ee99" | = metal map texture (F4-view)
|-
| style="color:#55ee99" | $info_hgtmap
| style="color:#55ee99" | = height map texture (F1-view)
|-
| style="color:#55ee99" | $info_blkmap
| style="color:#55ee99" | = blocking map texture (F2-view)
|-
| style="color:#55ee99" | $map_gbuffer_normtex
| style="color:#55ee99" | = contains the smoothed normals buffer of the map in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_difftex
| style="color:#55ee99" | = contains the diffuse texture buffer of the map in view {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_spectex
| style="color:#55ee99" | = contains the specular textures of the map in view {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_emittex
| style="color:#55ee99" | = for emissive materials (bloom would be the canonical use) {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_misctex
| style="color:#55ee99" | = for arbitrary shader data {{new|95}}
|-
| style="color:#55ee99" | $map_gbuffer_zvaltex
| style="color:#55ee99" | = contains the depth values (z-buffer) of the map in view. {{new|95}} To translate this to world position coordinates, use: 

'''No clip control / clipspace for depth is [-1,1]'''
vec4 worldpos= viewProjectionInv * vec4(vec3(gl_TexCoord[0].st,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x) * 2.0 - 1.0, 1.0);

'''Default if clip control is supported / clipspace for depth is [0,1].'''
vec4 worldpos= viewProjectionInv * vec4(gl_TexCoord[0].st * 2.0 - 1.0,
texture2D( map_gbuffer_zvaltex,gl_TexCoord[0].st ).x, 1.0);

worldpos.xyz = worldpos.xyz / worldpos.w;
|-
| style="color:#55ee99" | $model_gbuffer_normtex
| style="color:#55ee99" | = contains the smoothed normals buffer of the models in view in world space coordinates (note that to get true normal vectors from it, you must multiply the vector by 2 and subtract 1) {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_difftex
| style="color:#55ee99" | = contains the diffuse texture buffer of the models in view {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_spectex
| style="color:#55ee99" | = contains the specular textures of the models in view {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_emittex
| style="color:#55ee99" | = for emissive materials (bloom would be the canonical use) {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_misctex
| style="color:#55ee99" | = for arbitrary shader data {{new|95}}
|-
| style="color:#55ee99" | $model_gbuffer_zvaltex
| style="color:#55ee99" | = contains the depth values (z-buffer) of the models in view. {{new|95}}
|-
| style="color:#55ee99" | ${opt}:/LuaUI/images/image.png
| style="color:#55ee99" | = load a texture from the VFS
|}

possible ${opt}'s are:
'n' = nearest
'l' = linear
'a' = aniso
'i' = invert
'g' = greyed
'c' = clamped
'b' = border
't%r,%g,%b' = tint
'r%width,%height' = resize
The above ${opt}'s are NOT available for .DDS textures! .dds will load faster than other image formats.

example: ":iac:/LuaUI/images/image.png"
example: ":cr16,16:/LuaUI/images/image.png"
example2: ":t1.0,0.5,0:/LuaUI/images/image.png" (orange tint)


'''gl.CreateTexture'''
( int xsize, int ysize,
[ {
[target = number,] (like GL.TEXTURE_1D,GL.TEXTURE_2D,...) (Added support for GL_TEXTURE_2D_MULTISAMPLE in 104.0.1-1015-g8e36ef2 maintenance)
[format = number,]
[min_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[mag_filter = [[Lua_ConstGL#Texture_Filtering|number]],]
[wrap_s = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_t = [[Lua_ConstGL#Texture_Clamping|number]],]
[wrap_r = [[Lua_ConstGL#Texture_Clamping|number]],]
[aniso = number,]
[border = boolean,]
[fbo = boolean,] (needs GLEW_EXT_framebuffer_object!)
[fboDepth = boolean,] (needs GLEW_EXT_framebuffer_object!)
[samples = number,] specify any number here and target = GL_TEXTURE_2D_MULTISAMPLE to create multisample texture (Added in 104.0.1-1015-g8e36ef2 maintenance)
} ]
) -> string

'''gl.DeleteTexture'''
( string texture ) -> boolean

'''gl.DeleteTextureFBO''' (needs GLEW_EXT_framebuffer_object!)
( string texture ) -> boolean

'''gl.TextureInfo'''
( string texture ) -> nil | {
xsize = number,
ysize = number,
alpha = boolean, //not used yet
type = number, //not used yet
}

the format of the texture string is the same as in gl.Texture()


'''gl.TexCoord'''
( number x |
number x, number y |
number x, number y, number z |
number x, number y, number z, number w |
{ number x [, number y [, number z [, number w ]]] } ) -> nil

'''gl.MultiTexCoord'''
( int texNum,
number x |
number x, number y |
number x, number y, number z |
number x, number y, number z, number w |
{ number x [, number y [, number z [, number w ]]] } ) -> nil

'''gl.TexEnv'''
( number [[Lua_ConstGL#Texture_Environment|target]], number [[Lua_ConstGL#Texture_Environment|pname]],
number [[Lua_ConstGL#Texture_Environment|value]] |
number var1, number var2, number var3 ) -> nil

'''gl.MultiTexEnv'''
( int texNum, number [[Lua_ConstGL#Texture_Environment|target]], number [[Lua_ConstGL#Texture_Environment|pname]],
number [[Lua_ConstGL#Texture_Environment|value]] |
number var1, number var2, number var3 ) -> nil

'''gl.TexGen'''
( number [[Lua_ConstGL#Texture_Generation|target]],
boolean state |
number [[Lua_ConstGL#Texture_Generation|pname]], number value |
number [[Lua_ConstGL#Texture_Generation|pname]], number var1, number var2, number var3 ) -> nil

'''gl.MultiTexGen'''
( int texNum, number [[Lua_ConstGL#Texture_Generation|target]],
boolean state |
number [[Lua_ConstGL#Texture_Generation|pname]], number value |
number [[Lua_ConstGL#Texture_Generation|pname]], number var1, number var2, number var3 ) -> nil

'''gl.CopyToTexture'''
(string texture, int xoff, int yoff, int x, int y, int w, int h
[,number target,number level])->nil

'''gl.RenderToTexture''' (needs GLEW_EXT_framebuffer_object!)
( string fbotexture, lua_func ) -> nil

'''gl.GenerateMipmap''' (needs glGenerateMipmapEXT!)
( string texture ) -> boolean

The following are primarily intended to be used in conjunction with
gl.{Unit,Feature}(objID, ..., raw=true)
gl.{Unit,Feature}Shape(defID, ..., raw=true)
and apply a model's default textures; easier than gl.Texture("$%...")

'''gl.UnitTextures'''
( number unitID, boolean enable ) -> boolean

'''gl.UnitShapeTextures'''
( number unitDefID, boolean enable ) -> boolean

'''gl.FeatureTextures'''
( number featureID, boolean enable ) -> boolean

'''gl.FeatureShapeTextures'''
( number featureDefID, boolean enable ) -> boolean

= PixelReadback =
'''gl.SaveImage'''
( number x, number y, number w, number h,
string filename [, table {alpha=boolean, yflip=boolean, grayscale16bit=boolean, readbuffer=number} ] ) -> nil | boolean success


grayscale16bit is {{new|99.0}} and allows to save single color 16bit PNG 
readbuffer is {{new|104+}} and allows to choose the attachment of MRT FBO, use GL_COLOR_ATTACHMENT0_EXT and further as index


'''gl.ReadPixels'''
( number x, number y, number w, number h [, number format = GL.RGBA ] )
-> nil
| number r,[g,[b,[a]]]
| table { { {1 = number r, 2 = number g, 3 = number b, 4 = number a}, ... }, ... }

This reads back pixels from the final rendered screen. E.g. you can make a screenshot by grabbing the whole view.


= Lights =
'''gl.Lighting'''
( boolean enable ) -> nil

'''gl.ShadeModel'''
( number [[Lua_ConstGL#ShadeModel|mode]] ) -> nil

'''gl.Light'''
( int light,
boolean enable |
number [[Lua_ConstGL#Light_Specification|pname]], number param |
number [[Lua_ConstGL#Light_Specification|pname]], number param1, number param2, number param3 ) -> nil

'''gl.Material'''
({
ambient = {number r, number g, number b[, number a]},
diffuse = {number r, number g, number b[, number a]},
ambidiff = {number r, number g, number b[, number a]},
emission = {number r, number g, number b[, number a]},
specular = {number r, number g, number b[, number a]},
shininess = number specularExponent
}) -> nil

= Hardware relevant =
'''gl.HasExtension'''
( string extname ) -> boolean

'''gl.GetNumber'''
( number ext, int count ) -> number [, number, number, ... #count ]

'''gl.GetString'''
( number ext ) -> string

= DrawGroundPrimitives =
'''gl.DrawGroundCircle'''
( number x, number y, number z, number radius, number divs [, number slope ] ) -> nil
Note: number divs is the number of sides the circle will have. the higher the smoother the circle (and more GPU intensive) 

'''gl.DrawGroundQuad''' Note: x1,z1,x2 & z2 are rounded, so don't use it for very small or moving objects. x and z are correspond to the coordinates displayed by the tooltip 
( number x1, number z1, number x2, number z2,
[ boolean useNorm, (does nothing!)
[ number tu1, number tv1, number tu2, number tv2 |
boolean useTextureCoord ] ] ) -> nil

= Queries =
'''gl.CreateQuery''' needs >=OpengGL2.0!
( ) -> nil | userdata query
'''gl.DeleteQuery''' needs >=OpengGL2.0!
( userdata query ) -> nil
'''gl.RunQuery''' needs >=OpengGL2.0!
( userdata query, function, arg1, arg2, ... ) -> nil
'''gl.GetQuery''' needs >=OpengGL2.0!
( userdata query ) -> nil | number renderedFragments

= Extended =
'''gl.ActiveTexture'''
( int texNum, function [, arg1,... ] ) -> nil

'''gl.GetGlobalTexNames'''
() -> { [1] = string texture, etc ... }

'''gl.GetGlobalTexCoords''' gets the texcoord of a 3do texture in the 3do texture atlas
( string 3doTextureName ) -> number xstart, number ystart, number xend, number yend

'''gl.UnsafeState'''
( number state [, boolean disable_state ], function, arg1, arg2, ... ) -> nil
Calls glEnable(state) or glDisable(state) (if disable_state==true) and then calls the lua_function and afterwards reverts the state.

'''gl.GetShadowMapParams'''
() -> number xmid, number ymid, number p17, number p18

'''gl.GetMatrixData'''
( GL.PROJECTION [, int i] ) -> nil | number, etc.. | number Matrix[i]
( GL.MODELVIEW [, int i] ) -> nil | number, etc.. | number Matrix[i]
( GL.TEXTURE [, int i] ) -> nil | number, etc.. | number Matrix[i]
( "shadow" ) -> nil | number, etc..
( "camera" ) -> nil | number, etc..
( "caminv" ) -> nil | number, etc..
( "camprj" ) -> nil | number, etc..
( "billboard" ) -> nil | number, etc..

'''gl.Flush'''
() -> nil

'''gl.Finish'''
() -> nil

= Shaders (GLSL) =
[[Lua_GLSL_Api]]

[[category: Lua]]

Mapdev:mapinfo.lua

2021-02-17T20:18:08Z

Beherith: /* water */

= mapinfo.lua Reference =
This file is the primary configuration file for maps, list many things including resources, attributes, ad properties.

==Source==
The engine source code which reads this file from the map is viewable here:
* {{sourcelink|file=rts/Map/MapInfo.cpp}}
* {{sourcelink|file=rts/Map/MapParser.cpp}}

== Example ==
Can be found in the [https://github.com/jk3064/Map-Blueprint/archive/master.zip map blueprint]

= File Location =
relative to the root directory of the map
: ./mapinfo.lua

= Formatting =
check [http://www.lua.org/docs.html Lua Documentation] for syntax etc.

In this wiki page, variables are organised as such:
{{tag|name=VariableName|type=type|range=[valid range]|special=Required|default=value
|description=Description}}

== Data Types ==
{{DataTypes}}

= Sections =
== mapinfo ==
<pre>local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "1.0",
--mutator = "deployment";
mapfile = "maps/mymap.smf", -- // location of smf/sm3 file
modtype = 3, --// 1=primary, 0=hidden, 3=map
depend = {"Map Helper v1"},
replace = {},

--startpic = "", --// deprecated
--StartMusic = "", --// deprecated

maphardness = 100,
notDeformable = false,
gravity = 130,
tidalStrength = 0,
maxMetal = 0.02,
extractorRadius = 500.0,
voidWater = false,
voidGround = false,
autoShowMetal = true,

smf = {
...
},

sound = {
...
},

resources = {
...
},

splats = {
...
},

atmosphere = {
...
},

grass = {
...
},

lighting = {
...
},

water = {
...
},

teams = {
...
},

terrainTypes = {
...
},

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

{{tag|name=name|type=string|special=Required|default=none
|description=Name of the map}}

{{tag|name=shortname|type=string|special=Required
|description=maps will not show in the map list without a valid shortname(not sure on its requirements)}}

{{tag|name=description|type=string|default=name
|description=The description of the map that shows in the multiplayer battleroom}}

{{tag|name=author|type=string|default=""
|description=Author of the map}}

{{tag|name=version|type=string
|description=version, appended to name}}

{{tag|name=mutator|type=string}}

{{tag|name=mapfile|type=string
|description=location of smf/sm3 file}}

{{tag|name=modtype|type=int|range=[013]|special=Required
|description=1=primary, 0=hidden, 3=map}}

{{tag|name=depend|special=Required}}

{{tag|name=replace}}

{{tag|name=maphardness|type=float|default=100.0
|description=Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)}}

{{tag|name=notDeformable|type=bool|default=false
|description=Setting it to 1 means that no explosions can deform the map.}}

{{tag|name=gravity|type=float|range=[0.001-max]|default=130.0
|description=As you would expect, affects ballistics and how far units fly after an explosion. The force of gravity in units/sec^2}}

{{tag|name=tidalStrength|type=float|range=[0.0-max]|default=0.0
|description=The amount of energy which will be given by tidal generators.}}

{{tag|name=maxMetal|type=float|range=[0.0-max]|default=0.02
|description=How much metal a map square with the maximum metal value gives.}}

{{tag|name=extractorRadius|type=float|range=[0.0-max]|default=500
|description=The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.}}

{{tag|name=voidWater|type=bool|default=false
|description=Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check [http://springrts.com/phpbb/viewtopic.php?f=13&t=20684&hilit=apophis Apophis_v2]}}. Additionally for this to work, the <code>mapinfo.water.planeColor</code> variable must not be specified in the mapinfo.lua file, delete or comment it out if it exists.

{{tag|name=voidGround|type=bool|default=false
|special=New in 92.0
|description=Allows portions of the ground to be invisible if the map was compiled with a diffuse image that has an alpha channel. The terrain still exists, its just transparent.}}.

{{tag|name=voidAlphaMin|type=float|default=0.9
|description=Controls what alpha level the transparency trigger.}}.

{{tag|name=autoShowMetal|type=bool|default=true
|description=Defines whether the metal map (F4 mode) is shown automatically when a mex is queued for placement.}}

== smf ==
<pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre>
{{tag|name=minHeight|type=float|default=0.0
|description=Overrides the minimum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=maxHeight|type=float|default=0.0
|description=Overrides the maximum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=minimapTex|type=string
|special=New in 99.0
| description=Overrides the minimap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=metalmapTex|type=string
|special=New in 99.0
| description=Overrides the metalmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=typemapTex|type=string
|special=New in 99.0
| description=Overrides the typemap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=grassmapTex|type=string
|special=New in 99.0
| description=Overrides the grassmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=smtFileName[N]|type=string}}

== sound ==
<pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

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

{{tag|name=preset|type=string|default="default"
|description=Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: [https://github.com/spring/spring/blob/master/rts/System/Sound/OpenAL/EFXPresets.cpp EFXPresets.cpp]}}

{{Tip|You can change the preset at runtime via:
* /tset UseEFX [1|0]
* /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
* /tset snd_filter %gainlf %gainhf (may " " " " " " " " )}}

=== passfilter ===
Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them.
<pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre>

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

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

=== reverb ===
Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document.
<pre>local mapinfo = {
...
sound = {
...
reverb = {
--density
--diffusion
--gain
--gainhf
--gainlf
--decaytime
--decayhflimit
--decayhfratio
--decaylfratio
--reflectionsgain
--reflectionsdelay
--reflectionspan
--latereverbgain
--latereverbdelay
--latereverbpan
--echotime
--echodepth
--modtime
--moddepth
--airabsorptiongainhf
--hfreference
--lfreference
--roomrollofffactor
},
},
...
}</pre>

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

{{tag|name=grassBladeTex|type=string
|description=Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture. More Information: [[Mapdev:grass]]}}

{{tag|name=grassShadingTex|type=string
|description=Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color. More Information: [[Mapdev:grass]]}}

{{tag|name=detailTex|type=string
|description=Specifies the detail texture for the map. More Information: [[Mapdev:detail]]}}

{{tag|name=specularTex|type=string
|description=More Information: [[Mapdev:specular]]}}

{{tag|name=splatDetailTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=splatDistrTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=skyReflectModTex|type=string
|description=More Information: [[Mapdev:skyreflectmod]]}}

{{tag|name=detailNormalTex|type=string
|description=More Information: [[Mapdev:normal]]}}

{{tag|name=lightEmissionTex|type=string
|description=More Information: [[Mapdev:lightemission]]}}

{{tag|name=parallaxHeightTex|type=string
|description=More Information: [[Mapdev:parallax]]}}

== splats ==
<pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre>
{{tag|name=texScales|type=float[4]
|default={0.2, 0.2, 0.2, 0.2}|description=Scale value for the splat texture in the RGBA channels respectively.}}

{{tag|name=texMults|type=float[4]
|default={1.0, 1.0, 1.0, 1.0}|description=Value for the splat texture in the RGBA channels respectively.}}

== atmosphere ==
<pre>local mapinfo = {
...
atmosphere = {
minWind = 5.0,
maxWind = 25.0,

fogStart = 0.1,
fogEnd = 1.0,
fogColor = {0.7, 0.7, 0.8},

sunColor = {1.0, 1.0, 1.0},
skyColor = {0.1, 0.15, 0.7},
skyDir = {0.0, 0.0, -1.0},
skyBox = "",

cloudDensity = 0.5,
cloudColor = {1.0, 1.0, 1.0},
},
...
}</pre>

{{tag|name=minWind|type=float|range=[0.0-max]|default=5.0|
description=The minimum amount of energy the wind on the map will give. is clamped to maxwind}}

{{tag|name=maxWind|type=float|range=[0.0-max]|default=25.0
|description=The maximum amount of energy the wind on the map will give}}

{{tag|name=fogStart|type=float|default=0.1
|description=The distance from the camera at which the fog will start. <code>viewRange * fogStart</code>}}

{{tag|name=fogEnd|type=float|default=1.0
|description=The distance from the camera that fog is opaque. <code>viewRange * fogEnd</code> }}}

{{tag|name=fogColor|type=rgb|default={0.7, 0.7, 0.8}
|description=The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker}}

{{tag|name=sunColor|type=rgb|default={1.0, 1.0, 1.0}
|description=The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true}}

{{tag|name=skyColor|type=rgb|default={0.1, 0.15, 0.7}
|description=The color of the sky itself. The values are in the order Red, Green, Blue}}

{{tag|name=skyDir|type=float[3]|default={0.0, 0.0, -1.0}
|description=Is normalised vector}}

{{tag|name=skyBox|type=string
|description=Specify a .dds skybox (also called skycube) for examples and resources see this [http://springrts.com/phpbb/viewtopic.php?f=56&t=11009 thread]}}

{{tag|name=cloudDensity|type=float|range=[0.0-max]|default=0.5
|description=The amount of clouds in the sky}}

{{tag|name=cloudColor|type=rgb
|default={1.0, 1.0, 1.0}|description=The color of the clouds}}

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

<pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
maxStrawsPerTurf = 150,
},
...
}</pre>
{{tag|name=bladeWaveScale|type=float|default=1.0
|description=Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation}}

{{tag|name=bladeWidth|type=float|default=0.32
|description=Specifies the width of each blade of grass}}

{{tag|name=bladeHeight|type=float|default=4.0
|description=Specifies the length of each blade of grass}}

{{tag|name=bladeAngle|type=float|default=1.57
|description=Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass}}

{{tag|name=maxStrawsPerTurf|type=int|default=150
|description=The maximum number of grass blades per 'turf', A turf is approximately 32x32 elmos. }}

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

== Lighting ==
<pre>local mapinfo = {
...
lighting = {
--// dynsun
sunStartAngle = 0.0,
sunOrbitTime = 1440.0,
sunDir = {0.0, 1.0, 2.0, 1e9},

--// unit & ground lighting
groundAmbientColor = {0.5, 0.5, 0.5},
groundDiffuseColor = {0.5, 0.5, 0.5},
groundSpecularColor = {0.1, 0.1, 0.1},
groundShadowDensity = 0.8,
unitAmbientColor = {0.4, 0.4, 0.4},
unitDiffuseColor = {0.7, 0.7, 0.7},
unitSpecularColor = {0.7, 0.7, 0.7},
unitShadowDensity = 0.8,

specularExponent = 100.0,
},
...
}</pre>
{{tag|name=sunStartAngle|type=float|default=0.0}}

{{tag|name=sunOrbitTime|type=float|default=1440.0}}

{{tag|name=sunDir|type=float[3]|default={0.0, 1.0, 2.0}
|description=The direction of the sun, which is normalized by Spring. The Y-axis is up}}

{{tag|name=groundAmbientColor|type=rgb|default={0.5, 0.5, 0.5}
|description=The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue}}

{{tag|name=groundDiffuseColor|type=rgb|default={0.5, 05, 0.5}
|description=The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue}}

{{tag|name=groundSpecularColor|type=rgb|default={0.1, 0.1, 0.1}
|description=and its effect when a specular map is present?}}

{{tag|name=groundShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go.}}

{{tag|name=unitAmbientColor|type=float|default={0.4, 0.4, 0.4}
|description=The ambient (non-sun-lit) color of units and corpses}}

{{tag|name=unitDiffuseColor|type=rgb|default={0.7, 0.7, 0.7}
|description=The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor)}}

{{tag|name=unitSpecularColor|type=rgb|default=unitDiffuseColor}}

{{tag|name=unitShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go}}

{{tag|name=specularExponent|type=float|default=100}}

== water ==
<pre>local mapinfo = {
...
water = {
damage = 0.0,

repeatX = 0.0,
repeatY = 0.0,

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

ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.0,

planeColor = {0.0, 0.4, 0.0},

surfaceColor = {0.75, 0.8, 0.85},
surfaceAlpha = 0.55,
diffuseColor = {1.0, 1.0, 1.0},
specularColor = {0.5, 0.5, 0.5},

fresnelMin = 0.2,
fresnelMax = 0.8,
fresnelPower = 4.0,

reflectionDistortion = 1.0,

blurBase = 2.0,
blurExponent = 1.5,

perlinStartFreq = 8.0,
perlinLacunarity = 3.0,
perlinAmplitude = 0.9,
windSpeed = 1.0, --// does nothing yet

shoreWaves = true,
forceRendering = false,

--// undefined == load them from resources.lua!
--texture = "",
--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},

},
...
}</pre>
{{tag|name=damage|type=float|default=0.0
|description=Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water. As of 95.0 by default damage is also applied to hovercraft units. i wonder if this can be made to give life...?}}

{{tag|name=repeatX|type=float|default=0.0
|description=effects the filing frequency of the watertexture. E.g. how many times the watertexture (default ocean.jpg) will be repeated across the size of the entire map. Only affects basic water. Sane ranges[1-32] }}

{{tag|name=repeatY|type=float|default=0.0
|description=effects the filing frequency of the watertexture. E.g. how many times the watertexture (default ocean.jpg) will be repeated across the size of the entire map. Only affects basic water. Sane ranges[1-32] }}

{{tag|name=absorb|type=rgb|default={0.0, 0.0, 0.0}
|description=How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel}}

{{tag|name=baseColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue}}

{{tag|name=minColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The smallest values the water will go down to due to WaterAbsorb}}

{{tag|name=ambientFactor|type=float|default=1.0
|description=How much ambient (undirected) light (ambientColor) the water surface has}}

{{tag|name=diffuseFactor|type=float|default=1.0
|description=How much diffuse (sun lit, diffuseColor) color will be applied to the water surface}}

{{tag|name=specularFactor|type=float|default=1.0
|description=Specifies how much light is reflected from the sun, sane range [0-5]}}

{{tag|name=specularPower|type=float|default=20.0
|description=Specifies how 'polished' the surface of the water is. Small values provide wide, large reflections of the sun (specularcolor), large values provide more pointlike reflections, sane range [1-256]}}

{{tag|name=planeColor|type=rgb|default={0.0, 0.4, 0.0}
|description=This sets the color of the groundplane under the water outside the map boundaries}}

{{tag|name=surfaceColor|type=rgb|default={0.75, 0.8, 0.85}
|description=The color of the water surface. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!}}

{{tag|name=surfaceAlpha|type=float|default=0.55
|description= Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections)}}

{{tag|name=diffuseColor|type=rgb|default=value
|description=This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid}}

{{tag|name=specularColor|type=rgb|default=lighting.groundDiffuseColor
|description=This will be the color of specular reflections coming from the sun only on the water surface}}

{{tag|name=fresnelMin|type=float|default=0.2
|description=This defines the minimum amount of light the water surface will reflect when looking vertically down on it [0-1]. Small values will make the water very transparent (non-reflective) when looking straight down on it. Large values will make the water reflect a lot even when looking straight down.}}

{{tag|name=fresnelMax|type=float|default=0.8
|description=This defines the maximum amount of light the water surface will reflect when looking horizontally (parallel to the water plane) across it [0-1]. Small values will make the water very transparent (non-reflective) even when looking straight across it. Large values will make the water reflect a lot when looking across.}}

{{tag|name=fresnelPower|type=float|default=4.0
|description=This is how quickly the water reflectivity goes from fresnelmin to fresnelmax depending on the angle of incidence across the water. [https://github.com/spring/spring/blob/a8cf33ad1d2ac775e6008cd04baa7e859d1f23ec/cont/base/springcontent/shaders/GLSL/bumpWaterFS.glsl#L288 reflColor.a = FresnelMin + FresnelMax * pow(angle, FresnelPower);]}}

{{tag|name=reflectionDistortion|type=float|default=1.0
|description=How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20}}

{{tag|name=blurBase|type=float|default=2.0
|description=Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10}}

{{tag|name=blurExponent|type=float|default=1.5
|description=How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption}}

{{tag|name=perlinStartFreq|type=float|default=8.0
|description=Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)}}

{{tag|name=perlinLacunarity|type=float|default=3.0
|description=Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)}}

{{tag|name=perlinAmplitude|type=float|default=0.9
|description=Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0}}

{{tag|name=windSpeed|type=float|default=1.0
|description=does nothing yet}}

{{tag|name=shoreWaves|type=bool|default=true}}

{{tag|name=forceRendering|type=bool|default=true}}

will have to ask about those undefined tags

== teams ==
<pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 2033, z = 852}},
[1] = {startPos = {x = 10134, z = 852}},
[2] = {startPos = {x = 0, z = 0}},
[3] = {startPos = {x = 0, z = 0}},
...
},
...
}</pre>
Holds an array of start positions

== terrainTypes ==
<pre>local mapinfo = {
...
terrainTypes = {
[0] = {
name = "Default",
hardness = 1.0,
receiveTracks = true,
moveSpeeds = {
tank = 1.0,
kbot = 1.0,
hover = 1.0,
ship = 1.0,
},
},
[1] = {
...
},
...
},
...
}</pre>
Holds an array of start types where each element contains:

{{tag|name=name|type=string
|description=A label for the terrain type}}

{{tag|name=hardness|type=float|range=[0.001-max]|default=1.0
|description=Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard}}

{{tag|name=receiveTracks|type=bool|default=true
|description= Effects whether track decals will be placed on the ground from moving vehicles}}

{{tag|name=moveSpeeds.tank|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for tanks when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.kbot|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for kbots when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.hover|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.ship|type=float|range=[0.0-max]|default=1
|description= Speed multiplier for ships when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

== custom ==
<pre>local mapinfo = {
...
custom = {
fog = {
color = {0.26, 0.30, 0.41},
height = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
fogatten = 0.003,
},
precipitation = {
density = 30000,
size = 1.5,
speed = 50,
windscale = 1.2,
texture = 'LuaGaia/effects/snowflake.png',
},

},
...
}</pre>

[[Category:Map Dev]]

Mapdev:mapinfo.lua

2021-02-17T17:38:29Z

Beherith: /* water */

= mapinfo.lua Reference =
This file is the primary configuration file for maps, list many things including resources, attributes, ad properties.

==Source==
The engine source code which reads this file from the map is viewable here:
* {{sourcelink|file=rts/Map/MapInfo.cpp}}
* {{sourcelink|file=rts/Map/MapParser.cpp}}

== Example ==
Can be found in the [https://github.com/jk3064/Map-Blueprint/archive/master.zip map blueprint]

= File Location =
relative to the root directory of the map
: ./mapinfo.lua

= Formatting =
check [http://www.lua.org/docs.html Lua Documentation] for syntax etc.

In this wiki page, variables are organised as such:
{{tag|name=VariableName|type=type|range=[valid range]|special=Required|default=value
|description=Description}}

== Data Types ==
{{DataTypes}}

= Sections =
== mapinfo ==
<pre>local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "1.0",
--mutator = "deployment";
mapfile = "maps/mymap.smf", -- // location of smf/sm3 file
modtype = 3, --// 1=primary, 0=hidden, 3=map
depend = {"Map Helper v1"},
replace = {},

--startpic = "", --// deprecated
--StartMusic = "", --// deprecated

maphardness = 100,
notDeformable = false,
gravity = 130,
tidalStrength = 0,
maxMetal = 0.02,
extractorRadius = 500.0,
voidWater = false,
voidGround = false,
autoShowMetal = true,

smf = {
...
},

sound = {
...
},

resources = {
...
},

splats = {
...
},

atmosphere = {
...
},

grass = {
...
},

lighting = {
...
},

water = {
...
},

teams = {
...
},

terrainTypes = {
...
},

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

{{tag|name=name|type=string|special=Required|default=none
|description=Name of the map}}

{{tag|name=shortname|type=string|special=Required
|description=maps will not show in the map list without a valid shortname(not sure on its requirements)}}

{{tag|name=description|type=string|default=name
|description=The description of the map that shows in the multiplayer battleroom}}

{{tag|name=author|type=string|default=""
|description=Author of the map}}

{{tag|name=version|type=string
|description=version, appended to name}}

{{tag|name=mutator|type=string}}

{{tag|name=mapfile|type=string
|description=location of smf/sm3 file}}

{{tag|name=modtype|type=int|range=[013]|special=Required
|description=1=primary, 0=hidden, 3=map}}

{{tag|name=depend|special=Required}}

{{tag|name=replace}}

{{tag|name=maphardness|type=float|default=100.0
|description=Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)}}

{{tag|name=notDeformable|type=bool|default=false
|description=Setting it to 1 means that no explosions can deform the map.}}

{{tag|name=gravity|type=float|range=[0.001-max]|default=130.0
|description=As you would expect, affects ballistics and how far units fly after an explosion. The force of gravity in units/sec^2}}

{{tag|name=tidalStrength|type=float|range=[0.0-max]|default=0.0
|description=The amount of energy which will be given by tidal generators.}}

{{tag|name=maxMetal|type=float|range=[0.0-max]|default=0.02
|description=How much metal a map square with the maximum metal value gives.}}

{{tag|name=extractorRadius|type=float|range=[0.0-max]|default=500
|description=The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.}}

{{tag|name=voidWater|type=bool|default=false
|description=Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check [http://springrts.com/phpbb/viewtopic.php?f=13&t=20684&hilit=apophis Apophis_v2]}}. Additionally for this to work, the <code>mapinfo.water.planeColor</code> variable must not be specified in the mapinfo.lua file, delete or comment it out if it exists.

{{tag|name=voidGround|type=bool|default=false
|special=New in 92.0
|description=Allows portions of the ground to be invisible if the map was compiled with a diffuse image that has an alpha channel. The terrain still exists, its just transparent.}}.

{{tag|name=voidAlphaMin|type=float|default=0.9
|description=Controls what alpha level the transparency trigger.}}.

{{tag|name=autoShowMetal|type=bool|default=true
|description=Defines whether the metal map (F4 mode) is shown automatically when a mex is queued for placement.}}

== smf ==
<pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre>
{{tag|name=minHeight|type=float|default=0.0
|description=Overrides the minimum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=maxHeight|type=float|default=0.0
|description=Overrides the maximum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=minimapTex|type=string
|special=New in 99.0
| description=Overrides the minimap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=metalmapTex|type=string
|special=New in 99.0
| description=Overrides the metalmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=typemapTex|type=string
|special=New in 99.0
| description=Overrides the typemap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=grassmapTex|type=string
|special=New in 99.0
| description=Overrides the grassmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=smtFileName[N]|type=string}}

== sound ==
<pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

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

{{tag|name=preset|type=string|default="default"
|description=Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: [https://github.com/spring/spring/blob/master/rts/System/Sound/OpenAL/EFXPresets.cpp EFXPresets.cpp]}}

{{Tip|You can change the preset at runtime via:
* /tset UseEFX [1|0]
* /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
* /tset snd_filter %gainlf %gainhf (may " " " " " " " " )}}

=== passfilter ===
Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them.
<pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre>

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

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

=== reverb ===
Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document.
<pre>local mapinfo = {
...
sound = {
...
reverb = {
--density
--diffusion
--gain
--gainhf
--gainlf
--decaytime
--decayhflimit
--decayhfratio
--decaylfratio
--reflectionsgain
--reflectionsdelay
--reflectionspan
--latereverbgain
--latereverbdelay
--latereverbpan
--echotime
--echodepth
--modtime
--moddepth
--airabsorptiongainhf
--hfreference
--lfreference
--roomrollofffactor
},
},
...
}</pre>

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

{{tag|name=grassBladeTex|type=string
|description=Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture. More Information: [[Mapdev:grass]]}}

{{tag|name=grassShadingTex|type=string
|description=Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color. More Information: [[Mapdev:grass]]}}

{{tag|name=detailTex|type=string
|description=Specifies the detail texture for the map. More Information: [[Mapdev:detail]]}}

{{tag|name=specularTex|type=string
|description=More Information: [[Mapdev:specular]]}}

{{tag|name=splatDetailTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=splatDistrTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=skyReflectModTex|type=string
|description=More Information: [[Mapdev:skyreflectmod]]}}

{{tag|name=detailNormalTex|type=string
|description=More Information: [[Mapdev:normal]]}}

{{tag|name=lightEmissionTex|type=string
|description=More Information: [[Mapdev:lightemission]]}}

{{tag|name=parallaxHeightTex|type=string
|description=More Information: [[Mapdev:parallax]]}}

== splats ==
<pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre>
{{tag|name=texScales|type=float[4]
|default={0.2, 0.2, 0.2, 0.2}|description=Scale value for the splat texture in the RGBA channels respectively.}}

{{tag|name=texMults|type=float[4]
|default={1.0, 1.0, 1.0, 1.0}|description=Value for the splat texture in the RGBA channels respectively.}}

== atmosphere ==
<pre>local mapinfo = {
...
atmosphere = {
minWind = 5.0,
maxWind = 25.0,

fogStart = 0.1,
fogEnd = 1.0,
fogColor = {0.7, 0.7, 0.8},

sunColor = {1.0, 1.0, 1.0},
skyColor = {0.1, 0.15, 0.7},
skyDir = {0.0, 0.0, -1.0},
skyBox = "",

cloudDensity = 0.5,
cloudColor = {1.0, 1.0, 1.0},
},
...
}</pre>

{{tag|name=minWind|type=float|range=[0.0-max]|default=5.0|
description=The minimum amount of energy the wind on the map will give. is clamped to maxwind}}

{{tag|name=maxWind|type=float|range=[0.0-max]|default=25.0
|description=The maximum amount of energy the wind on the map will give}}

{{tag|name=fogStart|type=float|default=0.1
|description=The distance from the camera at which the fog will start. <code>viewRange * fogStart</code>}}

{{tag|name=fogEnd|type=float|default=1.0
|description=The distance from the camera that fog is opaque. <code>viewRange * fogEnd</code> }}}

{{tag|name=fogColor|type=rgb|default={0.7, 0.7, 0.8}
|description=The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker}}

{{tag|name=sunColor|type=rgb|default={1.0, 1.0, 1.0}
|description=The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true}}

{{tag|name=skyColor|type=rgb|default={0.1, 0.15, 0.7}
|description=The color of the sky itself. The values are in the order Red, Green, Blue}}

{{tag|name=skyDir|type=float[3]|default={0.0, 0.0, -1.0}
|description=Is normalised vector}}

{{tag|name=skyBox|type=string
|description=Specify a .dds skybox (also called skycube) for examples and resources see this [http://springrts.com/phpbb/viewtopic.php?f=56&t=11009 thread]}}

{{tag|name=cloudDensity|type=float|range=[0.0-max]|default=0.5
|description=The amount of clouds in the sky}}

{{tag|name=cloudColor|type=rgb
|default={1.0, 1.0, 1.0}|description=The color of the clouds}}

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

<pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
maxStrawsPerTurf = 150,
},
...
}</pre>
{{tag|name=bladeWaveScale|type=float|default=1.0
|description=Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation}}

{{tag|name=bladeWidth|type=float|default=0.32
|description=Specifies the width of each blade of grass}}

{{tag|name=bladeHeight|type=float|default=4.0
|description=Specifies the length of each blade of grass}}

{{tag|name=bladeAngle|type=float|default=1.57
|description=Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass}}

{{tag|name=maxStrawsPerTurf|type=int|default=150
|description=The maximum number of grass blades per 'turf', A turf is approximately 32x32 elmos. }}

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

== Lighting ==
<pre>local mapinfo = {
...
lighting = {
--// dynsun
sunStartAngle = 0.0,
sunOrbitTime = 1440.0,
sunDir = {0.0, 1.0, 2.0, 1e9},

--// unit & ground lighting
groundAmbientColor = {0.5, 0.5, 0.5},
groundDiffuseColor = {0.5, 0.5, 0.5},
groundSpecularColor = {0.1, 0.1, 0.1},
groundShadowDensity = 0.8,
unitAmbientColor = {0.4, 0.4, 0.4},
unitDiffuseColor = {0.7, 0.7, 0.7},
unitSpecularColor = {0.7, 0.7, 0.7},
unitShadowDensity = 0.8,

specularExponent = 100.0,
},
...
}</pre>
{{tag|name=sunStartAngle|type=float|default=0.0}}

{{tag|name=sunOrbitTime|type=float|default=1440.0}}

{{tag|name=sunDir|type=float[3]|default={0.0, 1.0, 2.0}
|description=The direction of the sun, which is normalized by Spring. The Y-axis is up}}

{{tag|name=groundAmbientColor|type=rgb|default={0.5, 0.5, 0.5}
|description=The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue}}

{{tag|name=groundDiffuseColor|type=rgb|default={0.5, 05, 0.5}
|description=The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue}}

{{tag|name=groundSpecularColor|type=rgb|default={0.1, 0.1, 0.1}
|description=and its effect when a specular map is present?}}

{{tag|name=groundShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go.}}

{{tag|name=unitAmbientColor|type=float|default={0.4, 0.4, 0.4}
|description=The ambient (non-sun-lit) color of units and corpses}}

{{tag|name=unitDiffuseColor|type=rgb|default={0.7, 0.7, 0.7}
|description=The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor)}}

{{tag|name=unitSpecularColor|type=rgb|default=unitDiffuseColor}}

{{tag|name=unitShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go}}

{{tag|name=specularExponent|type=float|default=100}}

== water ==
<pre>local mapinfo = {
...
water = {
damage = 0.0,

repeatX = 0.0,
repeatY = 0.0,

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

ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.0,

planeColor = {0.0, 0.4, 0.0},

surfaceColor = {0.75, 0.8, 0.85},
surfaceAlpha = 0.55,
diffuseColor = {1.0, 1.0, 1.0},
specularColor = {0.5, 0.5, 0.5},

fresnelMin = 0.2,
fresnelMax = 0.8,
fresnelPower = 4.0,

reflectionDistortion = 1.0,

blurBase = 2.0,
blurExponent = 1.5,

perlinStartFreq = 8.0,
perlinLacunarity = 3.0,
perlinAmplitude = 0.9,
windSpeed = 1.0, --// does nothing yet

shoreWaves = true,
forceRendering = false,

--// undefined == load them from resources.lua!
--texture = "",
--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},

},
...
}</pre>
{{tag|name=damage|type=float|default=0.0
|description=Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water. As of 95.0 by default damage is also applied to hovercraft units. i wonder if this can be made to give life...?}}

{{tag|name=repeatX|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=repeatY|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=absorb|type=rgb|default={0.0, 0.0, 0.0}
|description=How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel}}

{{tag|name=baseColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue}}

{{tag|name=minColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The smallest values the water will go down to due to WaterAbsorb}}

{{tag|name=ambientFactor|type=float|default=1.0}}

{{tag|name=diffuseFactor|type=float|default=1.0}}

{{tag|name=specularFactor|type=float|default=1.0}}

{{tag|name=specularPower|type=float|default=20.0}}

{{tag|name=planeColor|type=rgb|default={0.0, 0.4, 0.0}
|description=This sets the color of the groundplane under the water outside the map boundaries}}

{{tag|name=surfaceColor|type=rgb|default={0.75, 0.8, 0.85}
|description=The color of the water surface. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!}}

{{tag|name=surfaceAlpha|type=float|default=0.55
|description= Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections)}}

{{tag|name=diffuseColor|type=rgb|default=value
|description=This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid}}

{{tag|name=specularColor|type=rgb|default=lighting.groundDiffuseColor}}

{{tag|name=fresnelMin|type=float|default=0.2
|description=This defines the minimum amount of light the water surface will reflect when looking vertically down on it [0-1]. Small values will make the water very transparent (non-reflective) when looking straight down on it. Large values will make the water reflect a lot even when looking straight down.}}

{{tag|name=fresnelMax|type=float|default=0.8
|description=This defines the maximum amount of light the water surface will reflect when looking horizontally (parallel to the water plane) across it [0-1]. Small values will make the water very transparent (non-reflective) even when looking straight across it. Large values will make the water reflect a lot when looking across.}}

{{tag|name=fresnelPower|type=float|default=4.0
|description=This is how quickly the water reflectivity goes from fresnelmin to fresnelmax depending on the angle of incidence across the water. [https://github.com/spring/spring/blob/a8cf33ad1d2ac775e6008cd04baa7e859d1f23ec/cont/base/springcontent/shaders/GLSL/bumpWaterFS.glsl#L288 reflColor.a = FresnelMin + FresnelMax * pow(angle, FresnelPower);]}}

{{tag|name=reflectionDistortion|type=float|default=1.0
|description=How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20}}

{{tag|name=blurBase|type=float|default=2.0
|description=Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10}}

{{tag|name=blurExponent|type=float|default=1.5
|description=How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption}}

{{tag|name=perlinStartFreq|type=float|default=8.0
|description=Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)}}

{{tag|name=perlinLacunarity|type=float|default=3.0
|description=Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)}}

{{tag|name=perlinAmplitude|type=float|default=0.9
|description=Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0}}

{{tag|name=windSpeed|type=float|default=1.0
|description=does nothing yet}}

{{tag|name=shoreWaves|type=bool|default=true}}

{{tag|name=forceRendering|type=bool|default=true}}

will have to ask about those undefined tags

== teams ==
<pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 2033, z = 852}},
[1] = {startPos = {x = 10134, z = 852}},
[2] = {startPos = {x = 0, z = 0}},
[3] = {startPos = {x = 0, z = 0}},
...
},
...
}</pre>
Holds an array of start positions

== terrainTypes ==
<pre>local mapinfo = {
...
terrainTypes = {
[0] = {
name = "Default",
hardness = 1.0,
receiveTracks = true,
moveSpeeds = {
tank = 1.0,
kbot = 1.0,
hover = 1.0,
ship = 1.0,
},
},
[1] = {
...
},
...
},
...
}</pre>
Holds an array of start types where each element contains:

{{tag|name=name|type=string
|description=A label for the terrain type}}

{{tag|name=hardness|type=float|range=[0.001-max]|default=1.0
|description=Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard}}

{{tag|name=receiveTracks|type=bool|default=true
|description= Effects whether track decals will be placed on the ground from moving vehicles}}

{{tag|name=moveSpeeds.tank|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for tanks when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.kbot|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for kbots when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.hover|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.ship|type=float|range=[0.0-max]|default=1
|description= Speed multiplier for ships when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

== custom ==
<pre>local mapinfo = {
...
custom = {
fog = {
color = {0.26, 0.30, 0.41},
height = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
fogatten = 0.003,
},
precipitation = {
density = 30000,
size = 1.5,
speed = 50,
windscale = 1.2,
texture = 'LuaGaia/effects/snowflake.png',
},

},
...
}</pre>

[[Category:Map Dev]]

MapConv

2021-02-11T20:37:27Z

Beherith:

'''Linux users, use:''' [[MapConvNG]]

Some Mapconv Information [http://springrts.com/phpbb/viewtopic.php?f=13&t=20849 1],[http://springrts.com/phpbb/viewtopic.php?f=13&t=13655 2]

map decompiler [http://springrts.com/phpbb/viewtopic.php?f=13&t=18562 1]

= Mapconv =
A cross platform map compiler for spring
* [http://springrts.com/phpbb/viewtopic.php?f=56&t=21458 Forum thread] for news and releases

= Windows download =
* In 2021, on windows, use the GUI version here: [https://github.com/Beherith/springrts_smf_compiler PyMapConv]
- Beherith
= Source Code =
'''[http://github.com/spring/MapConv MapConv] at github'''
== Getting the Source ==
<code><pre>git clone git://github.com/spring/MapConv.git</pre></code>

= Documentation =
== Example Usage ==
'''Fastest compile, lowest quality:'''

MapConv -i -c 0 -x 250 -n 25 -o Zion_v1.smf -t t.bmp -a h.raw -m m.bmp -f f.bmp -z "nvdxt.exe -dxt1a -nmips 4 -quick -file"

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

MapConv -i -c 0 -x 250 -n 25 -o Zion_v1.smf -t t.bmp -a h.raw -m m.bmp -f f.bmp -q

'''Slow, great quality:'''

MapConv -i -c 0 -x 250 -n 25 -o Zion_v1.smf -t t.bmp -a h.raw -m m.bmp -f f.bmp

'''Slower, best possible quality:'''

MapConv -i -c 0 -x 250 -n 25 -o Zion_v1.smf -t t.bmp -a h.raw -m m.bmp -f f.bmp -z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file"

== --help output ==
<code><pre>
$ mapconv -h

USAGE:

mapconv [-j <feature list file>] [-f <featuremap image>] [-l] [-i] [-z
<texcompress program>] [-c <compression>] -x <max height> -n
<min height> [-o <output .smf>] [-e <tile file>] [-g <Geovent
image>] [-y <typemap image>] -m <metalmap image> -a <heightmap
file> -t <texturemap file> [--] [-v] [-h]

Where:

-j <feature list file>, --featurelist <feature list file>
(value required) A file with the name of one feature on each line.
(Default: fs.txt). See README.txt for details.

-f <featuremap image>, --featuremap <featuremap image>
(value required) Feature placement file, xsize by ysize. See
README.txt for details.

-l, --lowpass
Lowpass filters the heightmap

-i, --invert
Flip the height map image upside-down on reading.

-z <texcompress program>, --texcompress <texcompress program>
(value required) Name of companion program texcompress from current
working directory.

-c <compression>, --compress <compression>
(value required) How much we should try to compress the texture map.
Default 0.8, lower -> higher quality, larger files.

-x <max height>, --maxheight <max height>
(required) (value required) What altitude in spring the max(0xff or
0xffff) level of the height map represents.

-n <min height>, --minheight <min height>
(required) (value required) What altitude in spring the min(0) level
of the height map represents.

-o <output .smf>, --outfile <output .smf>
(value required) The name of the created map file. Should end in
.smf. A tilefile (extension .smt) is also created.

-e <tile file>, --externaltilefile <tile file>
(value required) External tile file that will be used for finding
tiles. Tiles not found in this will be saved in a new tile file.

-g <Geovent image>, --geoventfile <Geovent image>
(value required) The decal for geothermal vents; appears on the
compiled map at each vent. (Default: geovent.bmp).

-y <typemap image>, --typemap <typemap image>
(value required) Type map to use, uses the red channel to decide
type. types are defined in the .smd, if this argument is skipped the
map will be all type 0

-m <metalmap image>, --metalmap <metalmap image>
(required) (value required) Metal map to use, red channel is amount
of metal. Resized to xsize / 2 by ysize / 2.

-a <heightmap file>, --heightmap <heightmap file>
(required) (value required) Input heightmap to use for the map, this
should be in 16 bit raw format (.raw extension) or an image file. Must
be xsize*64+1 by ysize*64+1.

-t <texturemap file>, --intex <texturemap file>
(required) (value required) Input bitmap to use for the map. Sides
must be multiple of 1024 long. xsize, ysize determined from this file:
xsize = intex width / 8, ysize = height / 8.

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

-v, --version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Converts a series of image files to a Spring map. This just creates the
.smf and .smt files. You also need to write a .smd file using a text
editor.
</pre></code>

= Links =
* http://code.google.com/p/mapc/
* http://springrts.com/phpbb/viewtopic.php?f=13&t=18533

=== MapConv Parameters Explained ===

<code>'''MapConv'''</code> - Invoking the MapConv program (MapConv.exe)

<code>'''-i'''</code> - Inverts the heightmap (Always use -i, otherwise your heightmap will be flipped producing undesierable results)

<code>'''-l'''</code> - Lowpass option. Lowpass applies a blurring to the heightmap to smooth out rough edges and make pathing easier. If you are using a 16bit heightmap you will probably not want to use lowpass, however, many experienced mappers still use lowpass even on 16bit heightmaps due to the fact that lowpass smoothing will, in most cases, make it easier for the pathfinder to do it's job.

<code>'''-c # (-c 0)'''</code> - Compression level. '''Deprecated, never use any other value than 0.'''

 <code>'''-x # (-x 101)'''</code> - Map maximum height. '''Deprecated. Map levels can be set in the map's parameters via LUA which is a much better method.'''

 <code>'''-n # (-n 100)'''</code> - Map minimum height. '''Deprecated. Map levels can be set in the map's parameters via LUA which is a much better method.'''

 '''<code>-o <Mapname> (-o EvoRTS-Craggy_Creek-v01.smf</code>''<code>)</code> '''''- -o stands for "Output Filename". Generally this is the name of your map, but realistically it can be anything as you can change the name of the map via the Map's LUA parameters. '''Once compiled, NEVER rename the .smt file!'''

 '''<code>-t <Filename> (t terrain.png)</code> '''- Name of the Texture map file. '''Must be in the same directory as MapConv!'''

<code>'''-a <Filename> (-a height6.png)'''</code> - Name of the Height map file. '''Must be in the same directory as MapConv!'''

<code>'''-m <Filename> (-m metal.png)'''</code> - Name of the Metal map file. '''Must be in the same directory as MapConv!'''

<code>'''-f <Filename> (-f feature.png)'''</code> - Name of the Feature map file. '''Must be in the same directory as MapConv!'''

<code>'''-z <Parameters> (-z "nvdxt.exe -dxt1a -nmips 4 -Sinc -quality_highest -file")'''</code>- -z invokes nvdxt.exe which is a helper program that breaks the texture map into DDS tiles. The parameters listed tell nvdxt.exe how much to compress the tiles or how high of quality to strive for. There is never any reason to change the parameters from the example.

[[Category:Map Tools]]

Chili

2021-02-07T11:32:01Z

Beherith:

[[Main_Page|Wiki]] < {{FULLPAGENAME}}

== Chili UI ==

Chili is Springs very own GUI framework. It's a flexible, class based framework which allows you to create great looking GUIs very quickly. See [[Chili:ScreenShots| Screenshots]].

=== Learning Chili ===

* [[Chili:Tutorial| Chili Tutorial]]
* [[Chili:Examples| Examples of Chili widgets]]

Before working with Chili, it is strongly recommended to be familiar with using [[Lua_Scripting| Lua in Spring]], in particular with writing simple widgets.

=== Including Chili ===

* [[Chili:Adding_To_Game|Adding Chili to a game]]
* [[Chili:Hiding_The_Default_GUI|Hiding Springs default GUI]]

== Documentation: Chili Component Hierarchy ==

The Chili framework is object orientated, and each different component is a class. The hierarchy of components, which is documented [https://gajop.github.io/chiliui/index.html here], is as follows:

[https://gajop.github.io/chiliui/modules/controls.object.html Object]
|_ [https://gajop.github.io/chiliui/modules/controls.screen.html Screen]
|_ [https://gajop.github.io/chiliui/modules/controls.control.html Control]
|_ [https://gajop.github.io/chiliui/modules/controls.button.html Button]
|_ [https://gajop.github.io/chiliui/modules/controls.checkbox.html Checkbox]
|_ [https://gajop.github.io/chiliui/modules/controls.checkbox.html ColorBars]
|_ [https://gajop.github.io/chiliui/modules/controls.combobox.html ComboBox]
|_ [https://gajop.github.io/chiliui/modules/controls.editbox.html EditBox]
|_ [https://gajop.github.io/chiliui/modules/controls.font.html Font]
|_ [https://gajop.github.io/chiliui/modules/controls.label.html Label]
|_ [https://gajop.github.io/chiliui/modules/controls.layoutpanel.html LayoutPanel]
|_ [https://gajop.github.io/chiliui/modules/controls.imagelistview.html ImageListView]
|_ [https://gajop.github.io/chiliui/modules/controls.grid.html Grid]
|_ [https://gajop.github.io/chiliui/modules/controls.stackpanel.html StackPanel]
|_ [https://gajop.github.io/chiliui/modules/controls.tabpanel.html TabPanel]
|_ [https://gajop.github.io/chiliui/modules/controls.line.html Line]
|_ [https://gajop.github.io/chiliui/modules/controls.image.html Image]
|_ [https://gajop.github.io/chiliui/modules/controls.multiprogressbar.html MultiProgressBar]
|_ [https://gajop.github.io/chiliui/modules/controls.panel.html Panel]
|_ [https://gajop.github.io/chiliui/modules/controls.progressbar.html ProgressBar]
|_ [https://gajop.github.io/chiliui/modules/controls.scale.html Scale]
|_ [https://gajop.github.io/chiliui/modules/controls.scrollpanel.html ScrollPanel]
|_ [https://gajop.github.io/chiliui/modules/controls.textbox.html TextBox]
|_ [https://gajop.github.io/chiliui/modules/controls.trackbar.html TrackBar]
|_ [https://gajop.github.io/chiliui/modules/controls.treeview.html TreeView]
|_ TreeViewNode
|_ [https://gajop.github.io/chiliui/modules/controls.window.html Window]

Viewing the diagram as a tree, each component inherits from its parent in the tree. In practice, this means each component has the properties/functionality of its own type, and also of all components found upwards from it in the tree. For example, a Grid has it's own properties, but also has those of a LayoutPanel, Control and Object.

== Skinning Chili ==
Start with your desired <code>skin.lua</code>.

An example button skin will look like this:

<syntaxhighlight lang="lua">
skin.positive_button = {
clone = "window";

TileImageBK = ":cl:tech_button_bright_small_bk.png",
TileImageFG = ":cl:tech_button_bright_small_fg.png",

tiles = {40, 40, 40, 40}, --// tile widths: left,top,right,bottom
padding = {10, 10, 10, 10},

backgroundColor = {0.50, 0.50, 0.50, 0.65},
focusColor = {0.50, 0.50, 0.50, 0.9},
borderColor = {0.50, 0.50, 0.50, 0.15},

DrawControl = DrawButton,
}
</syntaxhighlight>

* <code>TileImageBK</code> - This image will be the background of your control. Alpha values indicate transparency, and color values you will be multiplied with <code>backgroundColor</code>

* <code>TileImageFG</code> - This image will be the foreground (drawn over background) of your control. Alpha values indicate transparency, and color values you will be multiplied with <code>borderColor</code>

* <code>tiles</code> - This image will be the background of your control. Alpha values indicate transparency, and color values you will be multiplied with <code>backgroundColor</code>

* <code>padding</code> - This image will be the background of your control. Alpha values indicate transparency, and color values you will be multiplied with <code>backgroundColor</code>

* <code>backgroundColor</code> - This image will be the background of your control. Alpha values indicate transparency, and color values you will be multiplied with <code>backgroundColor</code>

* <code>focusColor</code> - This image will be the background of your control. Alpha values indicate transparency, and color values you will be multiplied with <code>backgroundColor</code>

* <code>borderColor</code> - This image will be the background of your control. Alpha values indicate transparency, and color values you will be multiplied with <code>backgroundColor</code>

[[Category:Libraries]]

Building Spring on Windows

2020-06-22T13:23:23Z

Beherith: /* Installing MinGW-w64 */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}
{{#css:
code * {margin:inherit;}
}}

If you only want to produce your own Spring game and not contribute to the core engine, compilation is not necessary. Check out [[Gamedev:Main]].

Warning: Compiling Spring on Windows often causes problems, it is heavily recommended to use [[Building_Spring_on_Linux|Linux]] for developing the Spring RTS Engine if possible.

Some reasons for this:
* Of the active developers nobody uses windows for developing. So they might not be able to help as effectively as on Linux.
* Setting up a build environment takes a lot more time on windows
* Compiling is often slower on windows
* Compiling on windows is poorly tested (which possibly leads to some random / unknown / weird errors)

That said, if you do wish to use Windows, the best place to get real-time help is the #sy lobby channel, or #sy on [[IRC]].

=Compiling with MinGW=

== Requirements ==
Install [http://www.cmake.org/ CMake] and [http://msysgit.github.io/ msysGit] and MinGW-w64:

When installing msysGit you should select the option to "Run Git from the Windows Command Prompt":

[[File:Msysgit6.png|400px]]

This is in order to automatically add Git to PATH making it easy for CMake to find.

== Installing MinGW-w64 ==

Download and run the "Mingw-builds project - native toolchains using trunk" installer from [http://mingw-w64.org/doku.php/download/mingw-builds], more specifically from here: [https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win32/Personal%20Builds/mingw-builds/installer/mingw-w64-install.exe/download]

Select the following options:

[[File:InstallingMinGW-w64.png|400px]]

* '''Version:''' Any version above 4.8.x should work, 4.9.x+ may not have been tested as thoroughly. In 2020, version 8.1.0 works fine!
* '''Architecture:''' i686
* '''Threads:''' posix
* '''Exception:''' sjlj This is the only setting which needs to be changed from the default
* '''Build Revision:''' The latest one

== Adding to PATH ==

Once installed, you should add the MinGW directory to your PATH variable so that Cmake can find the relevant binaries.

* Go to System properties (either via Control Panel\System and Security\System or by right clicking 'Computer' on the desktop), then click 'Advanced System Settings'.
* Click the 'Environment Variables' button at the bottom.
* Find Path in the 'System Variables' scrollbox, add an extra <code>;</code> to the end and then copy-paste in the MinGW directory (e.g. default is <code>C:\Program Files (x86)\mingw-w64\i686-4.9.1-posix-sjlj-rt_v3-rev0\mingw32\bin</code>).
* Alternative instructions with images are easy to find online, for example [http://geekswithblogs.net/renso/archive/2009/10/21/how-to-set-the-windows-path-in-windows-7.aspx here].

= Get the Source Code =

* use git's bash (you find it in the right click context menu when clicking the folder), <code>cd</code> into your spring source dir

<code><pre>
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone https://github.com/spring/mingwlibs
</pre></code>

* update it from time to time with: <code>git pull --rebase</code>

* Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
** */spring/
** */spring/...
** */spring/mingwlibs
** */spring/rts

* Note: if you install the package somewhere else (preferably outside of the source tree), and pass its location with the ''MINGDIR'' option to CMake in the configure step (see further down, in the quick instructions).

== configure using CMake ==

Note, as of 2020, cmake-3.10.1-win64-x64.msi from https://cmake.org/files/v3.10/ works, 3.18 has issues detecting zlib.

* run the ''cmake-gui'' and select a source and a build directory
* press '''Configure''' and follow the instructions
* specify native compilers by entering the paths to gcc.exe and g++.exe from your mingw64-builds directory
* if you wish to build the full portable version (install-spring), then make sure to set the CMAKE_INSTALL_PREFIX as well
* In case of configuration errors make sure AI_TYPES variable is set to NONE (default is ALL). This should remedy the issues press '''Configure''' again (Remark: Setting NATIVE works as well (tested in commit 9108cae116))
* This is where you can specify the build type, REL for release, DEBUG for debug build, and RELWITHDEBINFO for a mix
* press '''Generate'''
* open a console (''cmd.exe''), ''cd'' into your '''build''' directory
* ''optional:'' for multi-threaded compilation, the ''mingw32-make'' part may differ on your system: <code>''<pre>set MAKE_COMMAND=mingw32-make -j2</pre>''</code> (use -j4 for 4 threads). For codeblocks configure CMAKE_CODEBLOCKS_MAKE_ARGUMENTS as -j4
* compile with: <code>''<pre>mingw32-make install-spring</pre>''</code>
* compile just the engine (spring.exe) with: <code>''<pre>mingw32-make engine-legacy</pre>''</code>

===Generating the AI Sources/Wrappers===

you can either build the wrapper:

<code>make Cpp-AIWrapper</code>

or generate all sources, in case you don't need the binary:

<code>make generateSources</code>

===Possible Problems===
* If you get undefined reference to `_Unwind_Resume' linking errors, deinstall ''whole'' MinGW and reinstall it with ''sjlj''.

* When you installed an old version of MinGW/TDM and forgot to deinstall it correctly, <code>gcc.exe</code> & <code>g++.exe</code> will be named <code>gcc-dw2.exe</code>/<code>g++-dw2.exe</code>. CMake will then fail to find the correct one, first try to deinstall anything mingw related and reinstall everything. If that didn't helped just rename the files. If even that doesn't help open cmake-gui and click the advanced button and set the paths to the correct files yourself (<code>CMAKE_C_COMPILER</code> & <code>CMAKE_CXX_COMPILER</code>).

=== Notes ===

You can still use Visual Studio 2012 as described below to edit the code. This is very useful because it allows excellent code navigation, and it highlights syntax errors and trivial mistakes before compiling.

For debugging mingw builds, you can aquire a windows build of gdb from http://www.equation.com/servlet/equation.cmd?fa=gdb

To start debugging, copy ''gdb.exe'' to your build output directory, and launch it with ''gdb spring.exe''. You can supply command line arguments to ''spring.exe'' with ''gdb --args spring.exe myreplayfile.sdf''

=Compiling with Visual Studio (not officially supported!)=
Currently Visual Studio lacks some c++ features it doesn't compile spring!

==General Visual Studio Notes==
When developing using Visual Studio keep in mind:
*It's experimental and not proved to compile or run!
*Your VS build won't sync with GCC builds in multiplayer mode
*AIs built with Visual Studio will work with the mingw32 release builds thanks to the C AI Interface, however this interface may change when newer releases are made
*Running any non-LUA AI on VS built Spring will crash it

===2012 (v11)===

Install [http://www.microsoft.com/visualstudio/eng/downloads#d-express-windows-desktop Visual Studio 2012 Express for Windows Desktop], [http://www.microsoft.com/en-us/download/confirmation.aspx?id=35515 Visual C++ Compiler November 2012 CTP], [http://www.cmake.org/ cmake], [http://www.7-zip.org 7-zip] and [http://msysgit.github.io/ msysgit].

From the Startmenu run "VS2012 x86 Native Tools Command Prompt" and type:

<code><pre>
set PATH=%PATH%;%PROGRAMFILES%\git\bin;%PROGRAMFILES%\cmake 2.8\bin\
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone git://github.com/spring/vclibs11.git vclibs
cmake -G "Visual Studio 11" .
</pre></code>

Now start visual studio & open Spring.sln. Select "engine-legacy" as default project, as AIs and ofter stuff are known to fail to compile on visual studio.

In the Project Properties, make sure to [http://stackoverflow.com/questions/13238408/variadic-template-in-vs-2012-visual-c-november-2012-ctp select the Microsoft Visual C++ Compiler Nov 2012 CTP].

Note: Visual Studio 2012 Express for Windows Desktop is for free, but requires a registration after 30 days (to get a free license).

[[Category:Compiling]]

Building Spring on Windows

2020-06-22T13:21:52Z

Beherith: /* configure using CMake */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}
{{#css:
code * {margin:inherit;}
}}

If you only want to produce your own Spring game and not contribute to the core engine, compilation is not necessary. Check out [[Gamedev:Main]].

Warning: Compiling Spring on Windows often causes problems, it is heavily recommended to use [[Building_Spring_on_Linux|Linux]] for developing the Spring RTS Engine if possible.

Some reasons for this:
* Of the active developers nobody uses windows for developing. So they might not be able to help as effectively as on Linux.
* Setting up a build environment takes a lot more time on windows
* Compiling is often slower on windows
* Compiling on windows is poorly tested (which possibly leads to some random / unknown / weird errors)

That said, if you do wish to use Windows, the best place to get real-time help is the #sy lobby channel, or #sy on [[IRC]].

=Compiling with MinGW=

== Requirements ==
Install [http://www.cmake.org/ CMake] and [http://msysgit.github.io/ msysGit] and MinGW-w64:

When installing msysGit you should select the option to "Run Git from the Windows Command Prompt":

[[File:Msysgit6.png|400px]]

This is in order to automatically add Git to PATH making it easy for CMake to find.

== Installing MinGW-w64 ==

Download and run the "Mingw-builds project - native toolchains using trunk" installer from [http://mingw-w64.org/doku.php/download/mingw-builds].

Select the following options:

[[File:InstallingMinGW-w64.png|400px]]

* '''Version:''' Any version above 4.8.x should work, 4.9.x+ may not have been tested as thoroughly. In 2020, version 8.1.0 works fine!
* '''Architecture:''' i686
* '''Threads:''' posix
* '''Exception:''' sjlj This is the only setting which needs to be changed from the default
* '''Build Revision:''' The latest one

== Adding to PATH ==

Once installed, you should add the MinGW directory to your PATH variable so that Cmake can find the relevant binaries.

* Go to System properties (either via Control Panel\System and Security\System or by right clicking 'Computer' on the desktop), then click 'Advanced System Settings'.
* Click the 'Environment Variables' button at the bottom.
* Find Path in the 'System Variables' scrollbox, add an extra <code>;</code> to the end and then copy-paste in the MinGW directory (e.g. default is <code>C:\Program Files (x86)\mingw-w64\i686-4.9.1-posix-sjlj-rt_v3-rev0\mingw32\bin</code>).
* Alternative instructions with images are easy to find online, for example [http://geekswithblogs.net/renso/archive/2009/10/21/how-to-set-the-windows-path-in-windows-7.aspx here].

= Get the Source Code =

* use git's bash (you find it in the right click context menu when clicking the folder), <code>cd</code> into your spring source dir

<code><pre>
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone https://github.com/spring/mingwlibs
</pre></code>

* update it from time to time with: <code>git pull --rebase</code>

* Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
** */spring/
** */spring/...
** */spring/mingwlibs
** */spring/rts

* Note: if you install the package somewhere else (preferably outside of the source tree), and pass its location with the ''MINGDIR'' option to CMake in the configure step (see further down, in the quick instructions).

== configure using CMake ==

Note, as of 2020, cmake-3.10.1-win64-x64.msi from https://cmake.org/files/v3.10/ works, 3.18 has issues detecting zlib.

* run the ''cmake-gui'' and select a source and a build directory
* press '''Configure''' and follow the instructions
* specify native compilers by entering the paths to gcc.exe and g++.exe from your mingw64-builds directory
* if you wish to build the full portable version (install-spring), then make sure to set the CMAKE_INSTALL_PREFIX as well
* In case of configuration errors make sure AI_TYPES variable is set to NONE (default is ALL). This should remedy the issues press '''Configure''' again (Remark: Setting NATIVE works as well (tested in commit 9108cae116))
* This is where you can specify the build type, REL for release, DEBUG for debug build, and RELWITHDEBINFO for a mix
* press '''Generate'''
* open a console (''cmd.exe''), ''cd'' into your '''build''' directory
* ''optional:'' for multi-threaded compilation, the ''mingw32-make'' part may differ on your system: <code>''<pre>set MAKE_COMMAND=mingw32-make -j2</pre>''</code> (use -j4 for 4 threads). For codeblocks configure CMAKE_CODEBLOCKS_MAKE_ARGUMENTS as -j4
* compile with: <code>''<pre>mingw32-make install-spring</pre>''</code>
* compile just the engine (spring.exe) with: <code>''<pre>mingw32-make engine-legacy</pre>''</code>

===Generating the AI Sources/Wrappers===

you can either build the wrapper:

<code>make Cpp-AIWrapper</code>

or generate all sources, in case you don't need the binary:

<code>make generateSources</code>

===Possible Problems===
* If you get undefined reference to `_Unwind_Resume' linking errors, deinstall ''whole'' MinGW and reinstall it with ''sjlj''.

* When you installed an old version of MinGW/TDM and forgot to deinstall it correctly, <code>gcc.exe</code> & <code>g++.exe</code> will be named <code>gcc-dw2.exe</code>/<code>g++-dw2.exe</code>. CMake will then fail to find the correct one, first try to deinstall anything mingw related and reinstall everything. If that didn't helped just rename the files. If even that doesn't help open cmake-gui and click the advanced button and set the paths to the correct files yourself (<code>CMAKE_C_COMPILER</code> & <code>CMAKE_CXX_COMPILER</code>).

=== Notes ===

You can still use Visual Studio 2012 as described below to edit the code. This is very useful because it allows excellent code navigation, and it highlights syntax errors and trivial mistakes before compiling.

For debugging mingw builds, you can aquire a windows build of gdb from http://www.equation.com/servlet/equation.cmd?fa=gdb

To start debugging, copy ''gdb.exe'' to your build output directory, and launch it with ''gdb spring.exe''. You can supply command line arguments to ''spring.exe'' with ''gdb --args spring.exe myreplayfile.sdf''

=Compiling with Visual Studio (not officially supported!)=
Currently Visual Studio lacks some c++ features it doesn't compile spring!

==General Visual Studio Notes==
When developing using Visual Studio keep in mind:
*It's experimental and not proved to compile or run!
*Your VS build won't sync with GCC builds in multiplayer mode
*AIs built with Visual Studio will work with the mingw32 release builds thanks to the C AI Interface, however this interface may change when newer releases are made
*Running any non-LUA AI on VS built Spring will crash it

===2012 (v11)===

Install [http://www.microsoft.com/visualstudio/eng/downloads#d-express-windows-desktop Visual Studio 2012 Express for Windows Desktop], [http://www.microsoft.com/en-us/download/confirmation.aspx?id=35515 Visual C++ Compiler November 2012 CTP], [http://www.cmake.org/ cmake], [http://www.7-zip.org 7-zip] and [http://msysgit.github.io/ msysgit].

From the Startmenu run "VS2012 x86 Native Tools Command Prompt" and type:

<code><pre>
set PATH=%PATH%;%PROGRAMFILES%\git\bin;%PROGRAMFILES%\cmake 2.8\bin\
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone git://github.com/spring/vclibs11.git vclibs
cmake -G "Visual Studio 11" .
</pre></code>

Now start visual studio & open Spring.sln. Select "engine-legacy" as default project, as AIs and ofter stuff are known to fail to compile on visual studio.

In the Project Properties, make sure to [http://stackoverflow.com/questions/13238408/variadic-template-in-vs-2012-visual-c-november-2012-ctp select the Microsoft Visual C++ Compiler Nov 2012 CTP].

Note: Visual Studio 2012 Express for Windows Desktop is for free, but requires a registration after 30 days (to get a free license).

[[Category:Compiling]]

Building Spring on Windows

2020-06-22T12:24:07Z

Beherith: /* configure using CMake */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}
{{#css:
code * {margin:inherit;}
}}

If you only want to produce your own Spring game and not contribute to the core engine, compilation is not necessary. Check out [[Gamedev:Main]].

Warning: Compiling Spring on Windows often causes problems, it is heavily recommended to use [[Building_Spring_on_Linux|Linux]] for developing the Spring RTS Engine if possible.

Some reasons for this:
* Of the active developers nobody uses windows for developing. So they might not be able to help as effectively as on Linux.
* Setting up a build environment takes a lot more time on windows
* Compiling is often slower on windows
* Compiling on windows is poorly tested (which possibly leads to some random / unknown / weird errors)

That said, if you do wish to use Windows, the best place to get real-time help is the #sy lobby channel, or #sy on [[IRC]].

=Compiling with MinGW=

== Requirements ==
Install [http://www.cmake.org/ CMake] and [http://msysgit.github.io/ msysGit] and MinGW-w64:

When installing msysGit you should select the option to "Run Git from the Windows Command Prompt":

[[File:Msysgit6.png|400px]]

This is in order to automatically add Git to PATH making it easy for CMake to find.

== Installing MinGW-w64 ==

Download and run the "Mingw-builds project - native toolchains using trunk" installer from [http://mingw-w64.org/doku.php/download/mingw-builds].

Select the following options:

[[File:InstallingMinGW-w64.png|400px]]

* '''Version:''' Any version above 4.8.x should work, 4.9.x+ may not have been tested as thoroughly. In 2020, version 8.1.0 works fine!
* '''Architecture:''' i686
* '''Threads:''' posix
* '''Exception:''' sjlj This is the only setting which needs to be changed from the default
* '''Build Revision:''' The latest one

== Adding to PATH ==

Once installed, you should add the MinGW directory to your PATH variable so that Cmake can find the relevant binaries.

* Go to System properties (either via Control Panel\System and Security\System or by right clicking 'Computer' on the desktop), then click 'Advanced System Settings'.
* Click the 'Environment Variables' button at the bottom.
* Find Path in the 'System Variables' scrollbox, add an extra <code>;</code> to the end and then copy-paste in the MinGW directory (e.g. default is <code>C:\Program Files (x86)\mingw-w64\i686-4.9.1-posix-sjlj-rt_v3-rev0\mingw32\bin</code>).
* Alternative instructions with images are easy to find online, for example [http://geekswithblogs.net/renso/archive/2009/10/21/how-to-set-the-windows-path-in-windows-7.aspx here].

= Get the Source Code =

* use git's bash (you find it in the right click context menu when clicking the folder), <code>cd</code> into your spring source dir

<code><pre>
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone https://github.com/spring/mingwlibs
</pre></code>

* update it from time to time with: <code>git pull --rebase</code>

* Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
** */spring/
** */spring/...
** */spring/mingwlibs
** */spring/rts

* Note: if you install the package somewhere else (preferably outside of the source tree), and pass its location with the ''MINGDIR'' option to CMake in the configure step (see further down, in the quick instructions).

== configure using CMake ==

Note, as of 2020, cmake-3.10.1-win64-x64.msi from https://cmake.org/files/v3.10/ works, 3.18 has issues detecting zlib.

* run the ''cmake-gui'' and select a source and a build directory
* press '''Configure''' and follow the instructions
* specify native compilers by entering the paths to gcc.exe and g++.exe from your mingw64-builds directory
* In case of configuration errors make sure AI_TYPES variable is set to NONE (default is ALL). This should remedy the issues press '''Configure''' again (Remark: Setting NATIVE works as well (tested in commit 9108cae116))
* This is where you can specify the build type, REL for release, DEBUG for debug build, and RELWITHDEBINFO for a mix
* press '''Generate'''
* open a console (''cmd.exe''), ''cd'' into your '''build''' directory
* ''optional:'' for multi-threaded compilation, the ''mingw32-make'' part may differ on your system: <code>''<pre>set MAKE_COMMAND=mingw32-make -j2</pre>''</code> (use -j4 for 4 threads). For codeblocks configure CMAKE_CODEBLOCKS_MAKE_ARGUMENTS as -j4
* compile with: <code>''<pre>mingw32-make install-spring</pre>''</code>
* compile just the engine (spring.exe) with: <code>''<pre>mingw32-make engine-legacy</pre>''</code>

===Generating the AI Sources/Wrappers===

you can either build the wrapper:

<code>make Cpp-AIWrapper</code>

or generate all sources, in case you don't need the binary:

<code>make generateSources</code>

===Possible Problems===
* If you get undefined reference to `_Unwind_Resume' linking errors, deinstall ''whole'' MinGW and reinstall it with ''sjlj''.

* When you installed an old version of MinGW/TDM and forgot to deinstall it correctly, <code>gcc.exe</code> & <code>g++.exe</code> will be named <code>gcc-dw2.exe</code>/<code>g++-dw2.exe</code>. CMake will then fail to find the correct one, first try to deinstall anything mingw related and reinstall everything. If that didn't helped just rename the files. If even that doesn't help open cmake-gui and click the advanced button and set the paths to the correct files yourself (<code>CMAKE_C_COMPILER</code> & <code>CMAKE_CXX_COMPILER</code>).

=== Notes ===

You can still use Visual Studio 2012 as described below to edit the code. This is very useful because it allows excellent code navigation, and it highlights syntax errors and trivial mistakes before compiling.

For debugging mingw builds, you can aquire a windows build of gdb from http://www.equation.com/servlet/equation.cmd?fa=gdb

To start debugging, copy ''gdb.exe'' to your build output directory, and launch it with ''gdb spring.exe''. You can supply command line arguments to ''spring.exe'' with ''gdb --args spring.exe myreplayfile.sdf''

=Compiling with Visual Studio (not officially supported!)=
Currently Visual Studio lacks some c++ features it doesn't compile spring!

==General Visual Studio Notes==
When developing using Visual Studio keep in mind:
*It's experimental and not proved to compile or run!
*Your VS build won't sync with GCC builds in multiplayer mode
*AIs built with Visual Studio will work with the mingw32 release builds thanks to the C AI Interface, however this interface may change when newer releases are made
*Running any non-LUA AI on VS built Spring will crash it

===2012 (v11)===

Install [http://www.microsoft.com/visualstudio/eng/downloads#d-express-windows-desktop Visual Studio 2012 Express for Windows Desktop], [http://www.microsoft.com/en-us/download/confirmation.aspx?id=35515 Visual C++ Compiler November 2012 CTP], [http://www.cmake.org/ cmake], [http://www.7-zip.org 7-zip] and [http://msysgit.github.io/ msysgit].

From the Startmenu run "VS2012 x86 Native Tools Command Prompt" and type:

<code><pre>
set PATH=%PATH%;%PROGRAMFILES%\git\bin;%PROGRAMFILES%\cmake 2.8\bin\
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone git://github.com/spring/vclibs11.git vclibs
cmake -G "Visual Studio 11" .
</pre></code>

Now start visual studio & open Spring.sln. Select "engine-legacy" as default project, as AIs and ofter stuff are known to fail to compile on visual studio.

In the Project Properties, make sure to [http://stackoverflow.com/questions/13238408/variadic-template-in-vs-2012-visual-c-november-2012-ctp select the Microsoft Visual C++ Compiler Nov 2012 CTP].

Note: Visual Studio 2012 Express for Windows Desktop is for free, but requires a registration after 30 days (to get a free license).

[[Category:Compiling]]

Mapdev:grass

2020-04-07T12:29:53Z

Beherith: /* Blade Texture */

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

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

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

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

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

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

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

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

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

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

[[Category:Map Dev]]

File:Grass blade tex ingame.PNG

2020-04-07T12:29:28Z

Beherith: Grass_blade_tex_ingame

== Summary ==
Grass_blade_tex_ingame

File:Grass blade tex testing.png

2020-04-07T12:26:00Z

Beherith: Grass_blade_tex_testing

== Summary ==
Grass_blade_tex_testing

Mapdev:grass

2020-04-07T12:24:35Z

Beherith: /* Blade Texture */

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

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

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

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

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

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

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

== Blade Texture ==
{{FIXME}} need more info.
{| class="wikitable" width="100%"
! width="15%" | File Location
| ./maps/
|-
! File Format
| PNG, TGA
|-
! Colour Depth
| 8bpp
|-
! Channels
| RGB (alpha does nothing here)
|-
! Resolution
| Any
|}

<center>
{| class="wikitable" style="text-align: center;"
| {{FIXME}} || {{FIXME}}
|-
! Example [[File:Example.jpg]] !! Result
|}</center>

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

[[Category:Map Dev]]

Building Spring on Windows

2020-03-26T15:20:09Z

Beherith: /* Installing MinGW-w64 */

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}
{{#css:
code * {margin:inherit;}
}}

If you only want to produce your own Spring game and not contribute to the core engine, compilation is not necessary. Check out [[Gamedev:Main]].

Warning: Compiling Spring on Windows often causes problems, it is heavily recommended to use [[Building_Spring_on_Linux|Linux]] for developing the Spring RTS Engine if possible.

Some reasons for this:
* Of the active developers nobody uses windows for developing. So they might not be able to help as effectively as on Linux.
* Setting up a build environment takes a lot more time on windows
* Compiling is often slower on windows
* Compiling on windows is poorly tested (which possibly leads to some random / unknown / weird errors)

That said, if you do wish to use Windows, the best place to get real-time help is the #sy lobby channel, or #sy on [[IRC]].

=Compiling with MinGW=

== Requirements ==
Install [http://www.cmake.org/ CMake] and [http://msysgit.github.io/ msysGit] and MinGW-w64:

When installing msysGit you should select the option to "Run Git from the Windows Command Prompt":

[[File:Msysgit6.png|400px]]

This is in order to automatically add Git to PATH making it easy for CMake to find.

== Installing MinGW-w64 ==

Download and run the "Mingw-builds project - native toolchains using trunk" installer from [http://mingw-w64.org/doku.php/download/mingw-builds].

Select the following options:

[[File:InstallingMinGW-w64.png|400px]]

* '''Version:''' Any version above 4.8.x should work, 4.9.x+ may not have been tested as thoroughly. In 2020, version 8.1.0 works fine!
* '''Architecture:''' i686
* '''Threads:''' posix
* '''Exception:''' sjlj This is the only setting which needs to be changed from the default
* '''Build Revision:''' The latest one

== Adding to PATH ==

Once installed, you should add the MinGW directory to your PATH variable so that Cmake can find the relevant binaries.

* Go to System properties (either via Control Panel\System and Security\System or by right clicking 'Computer' on the desktop), then click 'Advanced System Settings'.
* Click the 'Environment Variables' button at the bottom.
* Find Path in the 'System Variables' scrollbox, add an extra <code>;</code> to the end and then copy-paste in the MinGW directory (e.g. default is <code>C:\Program Files (x86)\mingw-w64\i686-4.9.1-posix-sjlj-rt_v3-rev0\mingw32\bin</code>).
* Alternative instructions with images are easy to find online, for example [http://geekswithblogs.net/renso/archive/2009/10/21/how-to-set-the-windows-path-in-windows-7.aspx here].

= Get the Source Code =

* use git's bash (you find it in the right click context menu when clicking the folder), <code>cd</code> into your spring source dir

<code><pre>
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone https://github.com/spring/mingwlibs
</pre></code>

* update it from time to time with: <code>git pull --rebase</code>

* Make sure you install the package in the checkout directory, so the path is: /spring/mingwlibs. If done right, it will look like:
** */spring/
** */spring/...
** */spring/mingwlibs
** */spring/rts

* Note: if you install the package somewhere else (preferably outside of the source tree), and pass its location with the ''MINGDIR'' option to CMake in the configure step (see further down, in the quick instructions).

== configure using CMake ==

* run the ''cmake-gui'' and select a source and a build directory
* press '''Configure''' and follow the instructions
* In case of configuration errors make sure AI_TYPES variable is set to NONE (default is ALL). This should remedy the issues press '''Configure''' again
* press '''Generate'''
* open a console (''cmd.exe''), ''cd'' into your '''build''' directory
* ''optional:'' for multi-threaded compilation, the ''mingw32-make'' part may differ on your system: <code>''<pre>set MAKE_COMMAND=mingw32-make -j2</pre>''</code> (use -j4 for 4 threads)
* compile with: <code>''<pre>mingw32-make install-spring</pre>''</code>
* compile just the engine (spring.exe) with: <code>''<pre>mingw32-make engine-legacy</pre>''</code>

===Generating the AI Sources/Wrappers===

you can either build the wrapper:

<code>make Cpp-AIWrapper</code>

or generate all sources, in case you don't need the binary:

<code>make generateSources</code>

===Possible Problems===
* If you get undefined reference to `_Unwind_Resume' linking errors, deinstall ''whole'' MinGW and reinstall it with ''sjlj''.

* When you installed an old version of MinGW/TDM and forgot to deinstall it correctly, <code>gcc.exe</code> & <code>g++.exe</code> will be named <code>gcc-dw2.exe</code>/<code>g++-dw2.exe</code>. CMake will then fail to find the correct one, first try to deinstall anything mingw related and reinstall everything. If that didn't helped just rename the files. If even that doesn't help open cmake-gui and click the advanced button and set the paths to the correct files yourself (<code>CMAKE_C_COMPILER</code> & <code>CMAKE_CXX_COMPILER</code>).

=== Notes ===

You can still use Visual Studio 2012 as described below to edit the code. This is very useful because it allows excellent code navigation, and it highlights syntax errors and trivial mistakes before compiling.

For debugging mingw builds, you can aquire a windows build of gdb from http://www.equation.com/servlet/equation.cmd?fa=gdb

To start debugging, copy ''gdb.exe'' to your build output directory, and launch it with ''gdb spring.exe''. You can supply command line arguments to ''spring.exe'' with ''gdb --args spring.exe myreplayfile.sdf''

=Compiling with Visual Studio (not officially supported!)=
Currently Visual Studio lacks some c++ features it doesn't compile spring!

==General Visual Studio Notes==
When developing using Visual Studio keep in mind:
*It's experimental and not proved to compile or run!
*Your VS build won't sync with GCC builds in multiplayer mode
*AIs built with Visual Studio will work with the mingw32 release builds thanks to the C AI Interface, however this interface may change when newer releases are made
*Running any non-LUA AI on VS built Spring will crash it

===2012 (v11)===

Install [http://www.microsoft.com/visualstudio/eng/downloads#d-express-windows-desktop Visual Studio 2012 Express for Windows Desktop], [http://www.microsoft.com/en-us/download/confirmation.aspx?id=35515 Visual C++ Compiler November 2012 CTP], [http://www.cmake.org/ cmake], [http://www.7-zip.org 7-zip] and [http://msysgit.github.io/ msysgit].

From the Startmenu run "VS2012 x86 Native Tools Command Prompt" and type:

<code><pre>
set PATH=%PATH%;%PROGRAMFILES%\git\bin;%PROGRAMFILES%\cmake 2.8\bin\
git clone --recursive git://github.com/spring/spring.git -b develop
cd spring
git clone git://github.com/spring/vclibs11.git vclibs
cmake -G "Visual Studio 11" .
</pre></code>

Now start visual studio & open Spring.sln. Select "engine-legacy" as default project, as AIs and ofter stuff are known to fail to compile on visual studio.

In the Project Properties, make sure to [http://stackoverflow.com/questions/13238408/variadic-template-in-vs-2012-visual-c-november-2012-ctp select the Microsoft Visual C++ Compiler Nov 2012 CTP].

Note: Visual Studio 2012 Express for Windows Desktop is for free, but requires a registration after 30 days (to get a free license).

[[Category:Compiling]]

Mapdev:splatdetailnormals

2019-11-18T11:57:32Z

Beherith: /* Detail Normal Texture Splatting (DNTS) */

= Detail Normal Texture Splatting (DNTS) =

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

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

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

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

Beherith recommends using a high-pass filter on the luminance diffuse (alpha) channel, to avoid visible banding when zoomed out. When using PBR materials as DNTS sources, he also recommends mixing the diffuse and ambient occlusion parts of the textures into the diffuse alpha, as well as keeping the alpha channel centered around 50% greyscale, and with preferably a low spread to make sure that diffuse doesnt overpower the nice normals you have added.

The system uses the same splatDistributionTexture as regular SSMF.

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

Example result:

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

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

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

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

= Specification =

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

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

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

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

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

[[Category:Map Dev]]

Mapdev:mapinfo.lua

2019-11-11T15:58:45Z

Beherith: /* grass */

= mapinfo.lua Reference =
This file is the primary configuration file for maps, list many things including resources, attributes, ad properties.

==Source==
The engine source code which reads this file from the map is viewable here:
* {{sourcelink|file=rts/Map/MapInfo.cpp}}
* {{sourcelink|file=rts/Map/MapParser.cpp}}

== Example ==
Can be found in the [https://github.com/jk3064/Map-Blueprint/archive/master.zip map blueprint]

= File Location =
relative to the root directory of the map
: ./mapinfo.lua

= Formatting =
check [http://www.lua.org/docs.html Lua Documentation] for syntax etc.

In this wiki page, variables are organised as such:
{{tag|name=VariableName|type=type|range=[valid range]|special=Required|default=value
|description=Description}}

== Data Types ==
{{DataTypes}}

= Sections =
== mapinfo ==
<code><pre>local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "1.0",
--mutator = "deployment";
mapfile = "maps/mymap.smf", -- // location of smf/sm3 file
modtype = 3, --// 1=primary, 0=hidden, 3=map
depend = {"Map Helper v1"},
replace = {},

--startpic = "", --// deprecated
--StartMusic = "", --// deprecated

maphardness = 100,
notDeformable = false,
gravity = 130,
tidalStrength = 0,
maxMetal = 0.02,
extractorRadius = 500.0,
voidWater = false,
voidGround = false,
autoShowMetal = true,

smf = {
...
},

sound = {
...
},

resources = {
...
},

splats = {
...
},

atmosphere = {
...
},

grass = {
...
},

lighting = {
...
},

water = {
...
},

teams = {
...
},

terrainTypes = {
...
},

custom = {
...
},
}</pre></code>

{{tag|name=name|type=string|special=Required|default=none
|description=Name of the map}}

{{tag|name=shortname|type=string|special=Required
|description=maps will not show in the map list without a valid shortname(not sure on its requirements)}}

{{tag|name=description|type=string|default=name
|description=The description of the map that shows in the multiplayer battleroom}}

{{tag|name=author|type=string|default=""
|description=Author of the map}}

{{tag|name=version|type=string
|description=version, appended to name}}

{{tag|name=mutator|type=string}}

{{tag|name=mapfile|type=string
|description=location of smf/sm3 file}}

{{tag|name=modtype|type=int|range=[013]|special=Required
|description=1=primary, 0=hidden, 3=map}}

{{tag|name=depend|special=Required}}

{{tag|name=replace}}

{{tag|name=maphardness|type=float|default=100.0
|description=Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)}}

{{tag|name=notDeformable|type=bool|default=false
|description=Setting it to 1 means that no explosions can deform the map.}}

{{tag|name=gravity|type=float|range=[0.001-max]|default=130.0
|description=As you would expect, affects ballistics and how far units fly after an explosion. The force of gravity in units/sec^2}}

{{tag|name=tidalStrength|type=float|range=[0.0-max]|default=0.0
|description=The amount of energy which will be given by tidal generators.}}

{{tag|name=maxMetal|type=float|range=[0.0-max]|default=0.02
|description=How much metal a map square with the maximum metal value gives.}}

{{tag|name=extractorRadius|type=float|range=[0.0-max]|default=500
|description=The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.}}

{{tag|name=voidWater|type=bool|default=false
|description=Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check [http://springrts.com/phpbb/viewtopic.php?f=13&t=20684&hilit=apophis Apophis_v2]}}. Additionally for this to work, the <code>mapinfo.water.planeColor</code> variable must not be specified in the mapinfo.lua file, delete or comment it out if it exists.

{{tag|name=voidGround|type=bool|default=false
|special=New in 92.0
|description=Allows portions of the ground to be invisible if the map was compiled with a diffuse image that has an alpha channel. The terrain still exists, its just transparent.}}.

{{tag|name=voidAlphaMin|type=float|default=0.9
|description=Controls what alpha level the transparency trigger.}}.

{{tag|name=autoShowMetal|type=bool|default=true
|description=Defines whether the metal map (F4 mode) is shown automatically when a mex is queued for placement.}}

== smf ==
<code><pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre></code>
{{tag|name=minHeight|type=float|default=0.0
|description=Overrides the minimum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=maxHeight|type=float|default=0.0
|description=Overrides the maximum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=minimapTex|type=string
|special=New in 99.0
| description=Overrides the minimap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=metalmapTex|type=string
|special=New in 99.0
| description=Overrides the metalmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=typemapTex|type=string
|special=New in 99.0
| description=Overrides the typemap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=grassmapTex|type=string
|special=New in 99.0
| description=Overrides the grassmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=smtFileName[N]|type=string}}

== sound ==
<code><pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

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

{{tag|name=preset|type=string|default="default"
|description=Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: [https://github.com/spring/spring/blob/master/rts/System/Sound/OpenAL/EFXPresets.cpp EFXPresets.cpp]}}

{{Tip|You can change the preset at runtime via:
* /tset UseEFX [1|0]
* /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
* /tset snd_filter %gainlf %gainhf (may " " " " " " " " )}}

=== passfilter ===
Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them.
<code><pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre></code>

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

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

=== reverb ===
Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document.
<code><pre>local mapinfo = {
...
sound = {
...
reverb = {
--density
--diffusion
--gain
--gainhf
--gainlf
--decaytime
--decayhflimit
--decayhfratio
--decaylfratio
--reflectionsgain
--reflectionsdelay
--reflectionspan
--latereverbgain
--latereverbdelay
--latereverbpan
--echotime
--echodepth
--modtime
--moddepth
--airabsorptiongainhf
--hfreference
--lfreference
--roomrollofffactor
},
},
...
}</pre></code>

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

{{tag|name=grassBladeTex|type=string
|description=Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture. More Information: [[Mapdev:grass]]}}

{{tag|name=grassShadingTex|type=string
|description=Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color. More Information: [[Mapdev:grass]]}}

{{tag|name=detailTex|type=string
|description=Specifies the detail texture for the map. More Information: [[Mapdev:detail]]}}

{{tag|name=specularTex|type=string
|description=More Information: [[Mapdev:specular]]}}

{{tag|name=splatDetailTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=splatDistrTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=skyReflectModTex|type=string
|description=More Information: [[Mapdev:skyreflectmod]]}}

{{tag|name=detailNormalTex|type=string
|description=More Information: [[Mapdev:normal]]}}

{{tag|name=lightEmissionTex|type=string
|description=More Information: [[Mapdev:lightemission]]}}

{{tag|name=parallaxHeightTex|type=string
|description=More Information: [[Mapdev:parallax]]}}

== splats ==
<code><pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre></code>
{{tag|name=texScales|type=float[4]
|default={0.2, 0.2, 0.2, 0.2}|description=Scale value for the splat texture in the RGBA channels respectively.}}

{{tag|name=texMults|type=float[4]
|default={1.0, 1.0, 1.0, 1.0}|description=Value for the splat texture in the RGBA channels respectively.}}

== atmosphere ==
<code><pre>local mapinfo = {
...
atmosphere = {
minWind = 5.0,
maxWind = 25.0,

fogStart = 0.1,
fogEnd = 1.0,
fogColor = {0.7, 0.7, 0.8},

sunColor = {1.0, 1.0, 1.0},
skyColor = {0.1, 0.15, 0.7},
skyDir = {0.0, 0.0, -1.0},
skyBox = "",

cloudDensity = 0.5,
cloudColor = {1.0, 1.0, 1.0},
},
...
}</pre></code>

{{tag|name=minWind|type=float|range=[0.0-max]|default=5.0|
description=The minimum amount of energy the wind on the map will give. is clamped to maxwind}}

{{tag|name=maxWind|type=float|range=[0.0-max]|default=25.0
|description=The maximum amount of energy the wind on the map will give}}

{{tag|name=fogStart|type=float|default=0.1
|description=The distance from the camera at which the fog will start. <code>viewRange * fogStart</code>}}

{{tag|name=fogEnd|type=float|default=1.0
|description=The distance from the camera that fog is opaque. <code>viewRange * fogEnd</code> }}}

{{tag|name=fogColor|type=rgb|default={0.7, 0.7, 0.8}
|description=The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker}}

{{tag|name=sunColor|type=rgb|default={1.0, 1.0, 1.0}
|description=The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true}}

{{tag|name=skyColor|type=rgb|default={0.1, 0.15, 0.7}
|description=The color of the sky itself. The values are in the order Red, Green, Blue}}

{{tag|name=skyDir|type=float[3]|default={0.0, 0.0, -1.0}
|description=Is normalised vector}}

{{tag|name=skyBox|type=string
|description=Specify a .dds skybox (also called skycube) for examples and resources see this [http://springrts.com/phpbb/viewtopic.php?f=56&t=11009 thread]}}

{{tag|name=cloudDensity|type=float|range=[0.0-max]|default=0.5
|description=The amount of clouds in the sky}}

{{tag|name=cloudColor|type=rgb
|default={1.0, 1.0, 1.0}|description=The color of the clouds}}

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

<code><pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
maxStrawsPerTurf = 150,
},
...
}</pre></code>
{{tag|name=bladeWaveScale|type=float|default=1.0
|description=Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation}}

{{tag|name=bladeWidth|type=float|default=0.32
|description=Specifies the width of each blade of grass}}

{{tag|name=bladeHeight|type=float|default=4.0
|description=Specifies the length of each blade of grass}}

{{tag|name=bladeAngle|type=float|default=1.57
|description=Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass}}

{{tag|name=maxStrawsPerTurf|type=int|default=150
|description=The maximum number of grass blades per 'turf', A turf is approximately 32x32 elmos. }}

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

== Lighting ==
<code><pre>local mapinfo = {
...
lighting = {
--// dynsun
sunStartAngle = 0.0,
sunOrbitTime = 1440.0,
sunDir = {0.0, 1.0, 2.0, 1e9},

--// unit & ground lighting
groundAmbientColor = {0.5, 0.5, 0.5},
groundDiffuseColor = {0.5, 0.5, 0.5},
groundSpecularColor = {0.1, 0.1, 0.1},
groundShadowDensity = 0.8,
unitAmbientColor = {0.4, 0.4, 0.4},
unitDiffuseColor = {0.7, 0.7, 0.7},
unitSpecularColor = {0.7, 0.7, 0.7},
unitShadowDensity = 0.8,

specularExponent = 100.0,
},
...
}</pre></code>
{{tag|name=sunStartAngle|type=float|default=0.0}}

{{tag|name=sunOrbitTime|type=float|default=1440.0}}

{{tag|name=sunDir|type=float[3]|default={0.0, 1.0, 2.0}
|description=The direction of the sun, which is normalized by Spring. The Y-axis is up}}

{{tag|name=groundAmbientColor|type=rgb|default={0.5, 0.5, 0.5}
|description=The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue}}

{{tag|name=groundDiffuseColor|type=rgb|default={0.5, 05, 0.5}
|description=The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue}}

{{tag|name=groundSpecularColor|type=rgb|default={0.1, 0.1, 0.1}
|description=and its effect when a specular map is present?}}

{{tag|name=groundShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go.}}

{{tag|name=unitAmbientColor|type=float|default={0.4, 0.4, 0.4}
|description=The ambient (non-sun-lit) color of units and corpses}}

{{tag|name=unitDiffuseColor|type=rgb|default={0.7, 0.7, 0.7}
|description=The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor)}}

{{tag|name=unitSpecularColor|type=rgb|default=unitDiffuseColor}}

{{tag|name=unitShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go}}

{{tag|name=specularExponent|type=float|default=100}}

== water ==
<code><pre>local mapinfo = {
...
water = {
damage = 0.0,

repeatX = 0.0,
repeatY = 0.0,

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

ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.0,

planeColor = {0.0, 0.4, 0.0},

surfaceColor = {0.75, 0.8, 0.85},
surfaceAlpha = 0.55,
diffuseColor = {1.0, 1.0, 1.0},
specularColor = {0.5, 0.5, 0.5},

fresnelMin = 0.2,
fresnelMax = 0.8,
fresnelPower = 4.0,

reflectionDistortion = 1.0,

blurBase = 2.0,
blurExponent = 1.5,

perlinStartFreq = 8.0,
perlinLacunarity = 3.0,
perlinAmplitude = 0.9,
windSpeed = 1.0, --// does nothing yet

shoreWaves = true,
forceRendering = false,

--// undefined == load them from resources.lua!
--texture = "",
--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},

},
...
}</pre></code>
{{tag|name=damage|type=float|default=0.0
|description=Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water. As of 95.0 by default damage is also applied to hovercraft units. i wonder if this can be made to give life...?}}

{{tag|name=repeatX|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=repeatY|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=absorb|type=rgb|default={0.0, 0.0, 0.0}
|description=How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel}}

{{tag|name=baseColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue}}

{{tag|name=minColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The smallest values the water will go down to due to WaterAbsorb}}

{{tag|name=ambientFactor|type=float|default=1.0}}

{{tag|name=diffuseFactor|type=float|default=1.0}}

{{tag|name=specularFactor|type=float|default=1.0}}

{{tag|name=specularPower|type=float|default=20.0}}

{{tag|name=planeColor|type=rgb|default={0.0, 0.4, 0.0}
|description=This sets the color of the groundplane under the water outside the map boundaries}}

{{tag|name=surfaceColor|type=rgb|default={0.75, 0.8, 0.85}
|description=The color of the water surface. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!}}

{{tag|name=surfaceAlpha|type=float|default=0.55
|description= Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections)}}

{{tag|name=diffuseColor|type=rgb|default=value
|description=This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid}}

{{tag|name=specularColor|type=rgb|default=lighting.groundDiffuseColor}}

{{tag|name=fresnelMin|type=float|default=0.2}}

{{tag|name=fresnelMax|type=float|default=0.8}}

{{tag|name=fresnelPower|type=float|default=4.0}}

{{tag|name=reflectionDistortion|type=float|default=1.0
|description=How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20}}

{{tag|name=blurBase|type=float|default=2.0
|description=Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10}}

{{tag|name=blurExponent|type=float|default=1.5
|description=How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption}}

{{tag|name=perlinStartFreq|type=float|default=8.0
|description=Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)}}

{{tag|name=perlinLacunarity|type=float|default=3.0
|description=Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)}}

{{tag|name=perlinAmplitude|type=float|default=0.9
|description=Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0}}

{{tag|name=windSpeed|type=float|default=1.0
|description=does nothing yet}}

{{tag|name=shoreWaves|type=bool|default=true}}

{{tag|name=forceRendering|type=bool|default=true}}

will have to ask about those undefined tags

== teams ==
<code><pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 2033, z = 852}},
[1] = {startPos = {x = 10134, z = 852}},
[2] = {startPos = {x = 0, z = 0}},
[3] = {startPos = {x = 0, z = 0}},
...
},
...
}</pre></code>
Holds an array of start positions

== terrainTypes ==
<code><pre>local mapinfo = {
...
terrainTypes = {
[0] = {
name = "Default",
hardness = 1.0,
receiveTracks = true,
moveSpeeds = {
tank = 1.0,
kbot = 1.0,
hover = 1.0,
ship = 1.0,
},
},
[1] = {
...
},
...
},
...
}</pre></code>
Holds an array of start types where each element contains:

{{tag|name=name|type=string
|description=A label for the terrain type}}

{{tag|name=hardness|type=float|range=[0.001-max]|default=1.0
|description=Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard}}

{{tag|name=receiveTracks|type=bool|default=true
|description= Effects whether track decals will be placed on the ground from moving vehicles}}

{{tag|name=moveSpeeds.tank|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for tanks when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.kbot|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for kbots when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.hover|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.ship|type=float|range=[0.0-max]|default=1
|description= Speed multiplier for ships when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

== custom ==
<code><pre>local mapinfo = {
...
custom = {
fog = {
color = {0.26, 0.30, 0.41},
height = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
fogatten = 0.003,
},
precipitation = {
density = 30000,
size = 1.5,
speed = 50,
windscale = 1.2,
texture = 'LuaGaia/effects/snowflake.png',
},

},
...
}</pre></code>

[[Category:Map Dev]]

Mapdev:mapinfo.lua

2019-11-11T13:03:37Z

Beherith: /* grass */

= mapinfo.lua Reference =
This file is the primary configuration file for maps, list many things including resources, attributes, ad properties.

==Source==
The engine source code which reads this file from the map is viewable here:
* {{sourcelink|file=rts/Map/MapInfo.cpp}}
* {{sourcelink|file=rts/Map/MapParser.cpp}}

== Example ==
Can be found in the [https://github.com/jk3064/Map-Blueprint/archive/master.zip map blueprint]

= File Location =
relative to the root directory of the map
: ./mapinfo.lua

= Formatting =
check [http://www.lua.org/docs.html Lua Documentation] for syntax etc.

In this wiki page, variables are organised as such:
{{tag|name=VariableName|type=type|range=[valid range]|special=Required|default=value
|description=Description}}

== Data Types ==
{{DataTypes}}

= Sections =
== mapinfo ==
<code><pre>local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "1.0",
--mutator = "deployment";
mapfile = "maps/mymap.smf", -- // location of smf/sm3 file
modtype = 3, --// 1=primary, 0=hidden, 3=map
depend = {"Map Helper v1"},
replace = {},

--startpic = "", --// deprecated
--StartMusic = "", --// deprecated

maphardness = 100,
notDeformable = false,
gravity = 130,
tidalStrength = 0,
maxMetal = 0.02,
extractorRadius = 500.0,
voidWater = false,
voidGround = false,
autoShowMetal = true,

smf = {
...
},

sound = {
...
},

resources = {
...
},

splats = {
...
},

atmosphere = {
...
},

grass = {
...
},

lighting = {
...
},

water = {
...
},

teams = {
...
},

terrainTypes = {
...
},

custom = {
...
},
}</pre></code>

{{tag|name=name|type=string|special=Required|default=none
|description=Name of the map}}

{{tag|name=shortname|type=string|special=Required
|description=maps will not show in the map list without a valid shortname(not sure on its requirements)}}

{{tag|name=description|type=string|default=name
|description=The description of the map that shows in the multiplayer battleroom}}

{{tag|name=author|type=string|default=""
|description=Author of the map}}

{{tag|name=version|type=string
|description=version, appended to name}}

{{tag|name=mutator|type=string}}

{{tag|name=mapfile|type=string
|description=location of smf/sm3 file}}

{{tag|name=modtype|type=int|range=[013]|special=Required
|description=1=primary, 0=hidden, 3=map}}

{{tag|name=depend|special=Required}}

{{tag|name=replace}}

{{tag|name=maphardness|type=float|default=100.0
|description=Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)}}

{{tag|name=notDeformable|type=bool|default=false
|description=Setting it to 1 means that no explosions can deform the map.}}

{{tag|name=gravity|type=float|range=[0.001-max]|default=130.0
|description=As you would expect, affects ballistics and how far units fly after an explosion. The force of gravity in units/sec^2}}

{{tag|name=tidalStrength|type=float|range=[0.0-max]|default=0.0
|description=The amount of energy which will be given by tidal generators.}}

{{tag|name=maxMetal|type=float|range=[0.0-max]|default=0.02
|description=How much metal a map square with the maximum metal value gives.}}

{{tag|name=extractorRadius|type=float|range=[0.0-max]|default=500
|description=The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.}}

{{tag|name=voidWater|type=bool|default=false
|description=Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check [http://springrts.com/phpbb/viewtopic.php?f=13&t=20684&hilit=apophis Apophis_v2]}}. Additionally for this to work, the <code>mapinfo.water.planeColor</code> variable must not be specified in the mapinfo.lua file, delete or comment it out if it exists.

{{tag|name=voidGround|type=bool|default=false
|special=New in 92.0
|description=Allows portions of the ground to be invisible if the map was compiled with a diffuse image that has an alpha channel. The terrain still exists, its just transparent.}}.

{{tag|name=voidAlphaMin|type=float|default=0.9
|description=Controls what alpha level the transparency trigger.}}.

{{tag|name=autoShowMetal|type=bool|default=true
|description=Defines whether the metal map (F4 mode) is shown automatically when a mex is queued for placement.}}

== smf ==
<code><pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre></code>
{{tag|name=minHeight|type=float|default=0.0
|description=Overrides the minimum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=maxHeight|type=float|default=0.0
|description=Overrides the maximum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=minimapTex|type=string
|special=New in 99.0
| description=Overrides the minimap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=metalmapTex|type=string
|special=New in 99.0
| description=Overrides the metalmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=typemapTex|type=string
|special=New in 99.0
| description=Overrides the typemap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=grassmapTex|type=string
|special=New in 99.0
| description=Overrides the grassmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=smtFileName[N]|type=string}}

== sound ==
<code><pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

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

{{tag|name=preset|type=string|default="default"
|description=Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: [https://github.com/spring/spring/blob/master/rts/System/Sound/OpenAL/EFXPresets.cpp EFXPresets.cpp]}}

{{Tip|You can change the preset at runtime via:
* /tset UseEFX [1|0]
* /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
* /tset snd_filter %gainlf %gainhf (may " " " " " " " " )}}

=== passfilter ===
Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them.
<code><pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre></code>

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

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

=== reverb ===
Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document.
<code><pre>local mapinfo = {
...
sound = {
...
reverb = {
--density
--diffusion
--gain
--gainhf
--gainlf
--decaytime
--decayhflimit
--decayhfratio
--decaylfratio
--reflectionsgain
--reflectionsdelay
--reflectionspan
--latereverbgain
--latereverbdelay
--latereverbpan
--echotime
--echodepth
--modtime
--moddepth
--airabsorptiongainhf
--hfreference
--lfreference
--roomrollofffactor
},
},
...
}</pre></code>

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

{{tag|name=grassBladeTex|type=string
|description=Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture. More Information: [[Mapdev:grass]]}}

{{tag|name=grassShadingTex|type=string
|description=Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color. More Information: [[Mapdev:grass]]}}

{{tag|name=detailTex|type=string
|description=Specifies the detail texture for the map. More Information: [[Mapdev:detail]]}}

{{tag|name=specularTex|type=string
|description=More Information: [[Mapdev:specular]]}}

{{tag|name=splatDetailTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=splatDistrTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=skyReflectModTex|type=string
|description=More Information: [[Mapdev:skyreflectmod]]}}

{{tag|name=detailNormalTex|type=string
|description=More Information: [[Mapdev:normal]]}}

{{tag|name=lightEmissionTex|type=string
|description=More Information: [[Mapdev:lightemission]]}}

{{tag|name=parallaxHeightTex|type=string
|description=More Information: [[Mapdev:parallax]]}}

== splats ==
<code><pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre></code>
{{tag|name=texScales|type=float[4]
|default={0.2, 0.2, 0.2, 0.2}|description=Scale value for the splat texture in the RGBA channels respectively.}}

{{tag|name=texMults|type=float[4]
|default={1.0, 1.0, 1.0, 1.0}|description=Value for the splat texture in the RGBA channels respectively.}}

== atmosphere ==
<code><pre>local mapinfo = {
...
atmosphere = {
minWind = 5.0,
maxWind = 25.0,

fogStart = 0.1,
fogEnd = 1.0,
fogColor = {0.7, 0.7, 0.8},

sunColor = {1.0, 1.0, 1.0},
skyColor = {0.1, 0.15, 0.7},
skyDir = {0.0, 0.0, -1.0},
skyBox = "",

cloudDensity = 0.5,
cloudColor = {1.0, 1.0, 1.0},
},
...
}</pre></code>

{{tag|name=minWind|type=float|range=[0.0-max]|default=5.0|
description=The minimum amount of energy the wind on the map will give. is clamped to maxwind}}

{{tag|name=maxWind|type=float|range=[0.0-max]|default=25.0
|description=The maximum amount of energy the wind on the map will give}}

{{tag|name=fogStart|type=float|default=0.1
|description=The distance from the camera at which the fog will start. <code>viewRange * fogStart</code>}}

{{tag|name=fogEnd|type=float|default=1.0
|description=The distance from the camera that fog is opaque. <code>viewRange * fogEnd</code> }}}

{{tag|name=fogColor|type=rgb|default={0.7, 0.7, 0.8}
|description=The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker}}

{{tag|name=sunColor|type=rgb|default={1.0, 1.0, 1.0}
|description=The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true}}

{{tag|name=skyColor|type=rgb|default={0.1, 0.15, 0.7}
|description=The color of the sky itself. The values are in the order Red, Green, Blue}}

{{tag|name=skyDir|type=float[3]|default={0.0, 0.0, -1.0}
|description=Is normalised vector}}

{{tag|name=skyBox|type=string
|description=Specify a .dds skybox (also called skycube) for examples and resources see this [http://springrts.com/phpbb/viewtopic.php?f=56&t=11009 thread]}}

{{tag|name=cloudDensity|type=float|range=[0.0-max]|default=0.5
|description=The amount of clouds in the sky}}

{{tag|name=cloudColor|type=rgb
|default={1.0, 1.0, 1.0}|description=The color of the clouds}}

== grass ==
<code><pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
maxStrawsPerTurf = 150,
},
...
}</pre></code>
{{tag|name=bladeWaveScale|type=float|default=1.0
|description=Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation}}

{{tag|name=bladeWidth|type=float|default=0.32
|description=Specifies the width of each blade of grass}}

{{tag|name=bladeHeight|type=float|default=4.0
|description=Specifies the length of each blade of grass}}

{{tag|name=bladeAngle|type=float|default=1.57
|description=Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass}}

{{tag|name=maxStrawsPerTurf|type=int|default=150
|description=The maximum number of grass blades per 'turf', A turf is approximately 32x32 elmos. }}

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

== Lighting ==
<code><pre>local mapinfo = {
...
lighting = {
--// dynsun
sunStartAngle = 0.0,
sunOrbitTime = 1440.0,
sunDir = {0.0, 1.0, 2.0, 1e9},

--// unit & ground lighting
groundAmbientColor = {0.5, 0.5, 0.5},
groundDiffuseColor = {0.5, 0.5, 0.5},
groundSpecularColor = {0.1, 0.1, 0.1},
groundShadowDensity = 0.8,
unitAmbientColor = {0.4, 0.4, 0.4},
unitDiffuseColor = {0.7, 0.7, 0.7},
unitSpecularColor = {0.7, 0.7, 0.7},
unitShadowDensity = 0.8,

specularExponent = 100.0,
},
...
}</pre></code>
{{tag|name=sunStartAngle|type=float|default=0.0}}

{{tag|name=sunOrbitTime|type=float|default=1440.0}}

{{tag|name=sunDir|type=float[3]|default={0.0, 1.0, 2.0}
|description=The direction of the sun, which is normalized by Spring. The Y-axis is up}}

{{tag|name=groundAmbientColor|type=rgb|default={0.5, 0.5, 0.5}
|description=The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue}}

{{tag|name=groundDiffuseColor|type=rgb|default={0.5, 05, 0.5}
|description=The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue}}

{{tag|name=groundSpecularColor|type=rgb|default={0.1, 0.1, 0.1}
|description=and its effect when a specular map is present?}}

{{tag|name=groundShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go.}}

{{tag|name=unitAmbientColor|type=float|default={0.4, 0.4, 0.4}
|description=The ambient (non-sun-lit) color of units and corpses}}

{{tag|name=unitDiffuseColor|type=rgb|default={0.7, 0.7, 0.7}
|description=The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor)}}

{{tag|name=unitSpecularColor|type=rgb|default=unitDiffuseColor}}

{{tag|name=unitShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go}}

{{tag|name=specularExponent|type=float|default=100}}

== water ==
<code><pre>local mapinfo = {
...
water = {
damage = 0.0,

repeatX = 0.0,
repeatY = 0.0,

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

ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.0,

planeColor = {0.0, 0.4, 0.0},

surfaceColor = {0.75, 0.8, 0.85},
surfaceAlpha = 0.55,
diffuseColor = {1.0, 1.0, 1.0},
specularColor = {0.5, 0.5, 0.5},

fresnelMin = 0.2,
fresnelMax = 0.8,
fresnelPower = 4.0,

reflectionDistortion = 1.0,

blurBase = 2.0,
blurExponent = 1.5,

perlinStartFreq = 8.0,
perlinLacunarity = 3.0,
perlinAmplitude = 0.9,
windSpeed = 1.0, --// does nothing yet

shoreWaves = true,
forceRendering = false,

--// undefined == load them from resources.lua!
--texture = "",
--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},

},
...
}</pre></code>
{{tag|name=damage|type=float|default=0.0
|description=Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water. As of 95.0 by default damage is also applied to hovercraft units. i wonder if this can be made to give life...?}}

{{tag|name=repeatX|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=repeatY|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=absorb|type=rgb|default={0.0, 0.0, 0.0}
|description=How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel}}

{{tag|name=baseColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue}}

{{tag|name=minColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The smallest values the water will go down to due to WaterAbsorb}}

{{tag|name=ambientFactor|type=float|default=1.0}}

{{tag|name=diffuseFactor|type=float|default=1.0}}

{{tag|name=specularFactor|type=float|default=1.0}}

{{tag|name=specularPower|type=float|default=20.0}}

{{tag|name=planeColor|type=rgb|default={0.0, 0.4, 0.0}
|description=This sets the color of the groundplane under the water outside the map boundaries}}

{{tag|name=surfaceColor|type=rgb|default={0.75, 0.8, 0.85}
|description=The color of the water surface. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!}}

{{tag|name=surfaceAlpha|type=float|default=0.55
|description= Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections)}}

{{tag|name=diffuseColor|type=rgb|default=value
|description=This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid}}

{{tag|name=specularColor|type=rgb|default=lighting.groundDiffuseColor}}

{{tag|name=fresnelMin|type=float|default=0.2}}

{{tag|name=fresnelMax|type=float|default=0.8}}

{{tag|name=fresnelPower|type=float|default=4.0}}

{{tag|name=reflectionDistortion|type=float|default=1.0
|description=How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20}}

{{tag|name=blurBase|type=float|default=2.0
|description=Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10}}

{{tag|name=blurExponent|type=float|default=1.5
|description=How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption}}

{{tag|name=perlinStartFreq|type=float|default=8.0
|description=Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)}}

{{tag|name=perlinLacunarity|type=float|default=3.0
|description=Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)}}

{{tag|name=perlinAmplitude|type=float|default=0.9
|description=Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0}}

{{tag|name=windSpeed|type=float|default=1.0
|description=does nothing yet}}

{{tag|name=shoreWaves|type=bool|default=true}}

{{tag|name=forceRendering|type=bool|default=true}}

will have to ask about those undefined tags

== teams ==
<code><pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 2033, z = 852}},
[1] = {startPos = {x = 10134, z = 852}},
[2] = {startPos = {x = 0, z = 0}},
[3] = {startPos = {x = 0, z = 0}},
...
},
...
}</pre></code>
Holds an array of start positions

== terrainTypes ==
<code><pre>local mapinfo = {
...
terrainTypes = {
[0] = {
name = "Default",
hardness = 1.0,
receiveTracks = true,
moveSpeeds = {
tank = 1.0,
kbot = 1.0,
hover = 1.0,
ship = 1.0,
},
},
[1] = {
...
},
...
},
...
}</pre></code>
Holds an array of start types where each element contains:

{{tag|name=name|type=string
|description=A label for the terrain type}}

{{tag|name=hardness|type=float|range=[0.001-max]|default=1.0
|description=Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard}}

{{tag|name=receiveTracks|type=bool|default=true
|description= Effects whether track decals will be placed on the ground from moving vehicles}}

{{tag|name=moveSpeeds.tank|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for tanks when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.kbot|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for kbots when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.hover|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.ship|type=float|range=[0.0-max]|default=1
|description= Speed multiplier for ships when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

== custom ==
<code><pre>local mapinfo = {
...
custom = {
fog = {
color = {0.26, 0.30, 0.41},
height = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
fogatten = 0.003,
},
precipitation = {
density = 30000,
size = 1.5,
speed = 50,
windscale = 1.2,
texture = 'LuaGaia/effects/snowflake.png',
},

},
...
}</pre></code>

[[Category:Map Dev]]

Mapdev:mapinfo.lua

2019-11-11T13:00:24Z

Beherith: /* mapinfo */

= mapinfo.lua Reference =
This file is the primary configuration file for maps, list many things including resources, attributes, ad properties.

==Source==
The engine source code which reads this file from the map is viewable here:
* {{sourcelink|file=rts/Map/MapInfo.cpp}}
* {{sourcelink|file=rts/Map/MapParser.cpp}}

== Example ==
Can be found in the [https://github.com/jk3064/Map-Blueprint/archive/master.zip map blueprint]

= File Location =
relative to the root directory of the map
: ./mapinfo.lua

= Formatting =
check [http://www.lua.org/docs.html Lua Documentation] for syntax etc.

In this wiki page, variables are organised as such:
{{tag|name=VariableName|type=type|range=[valid range]|special=Required|default=value
|description=Description}}

== Data Types ==
{{DataTypes}}

= Sections =
== mapinfo ==
<code><pre>local mapinfo = {
name = "MyMap",
shortname = "",
description = "",
author = "",
version = "1.0",
--mutator = "deployment";
mapfile = "maps/mymap.smf", -- // location of smf/sm3 file
modtype = 3, --// 1=primary, 0=hidden, 3=map
depend = {"Map Helper v1"},
replace = {},

--startpic = "", --// deprecated
--StartMusic = "", --// deprecated

maphardness = 100,
notDeformable = false,
gravity = 130,
tidalStrength = 0,
maxMetal = 0.02,
extractorRadius = 500.0,
voidWater = false,
voidGround = false,
autoShowMetal = true,

smf = {
...
},

sound = {
...
},

resources = {
...
},

splats = {
...
},

atmosphere = {
...
},

grass = {
...
},

lighting = {
...
},

water = {
...
},

teams = {
...
},

terrainTypes = {
...
},

custom = {
...
},
}</pre></code>

{{tag|name=name|type=string|special=Required|default=none
|description=Name of the map}}

{{tag|name=shortname|type=string|special=Required
|description=maps will not show in the map list without a valid shortname(not sure on its requirements)}}

{{tag|name=description|type=string|default=name
|description=The description of the map that shows in the multiplayer battleroom}}

{{tag|name=author|type=string|default=""
|description=Author of the map}}

{{tag|name=version|type=string
|description=version, appended to name}}

{{tag|name=mutator|type=string}}

{{tag|name=mapfile|type=string
|description=location of smf/sm3 file}}

{{tag|name=modtype|type=int|range=[013]|special=Required
|description=1=primary, 0=hidden, 3=map}}

{{tag|name=depend|special=Required}}

{{tag|name=replace}}

{{tag|name=maphardness|type=float|default=100.0
|description=Defines how much a map will deform from impacts. Higher values mean less deformation, negative values will result in negative deformation (really funny looking)}}

{{tag|name=notDeformable|type=bool|default=false
|description=Setting it to 1 means that no explosions can deform the map.}}

{{tag|name=gravity|type=float|range=[0.001-max]|default=130.0
|description=As you would expect, affects ballistics and how far units fly after an explosion. The force of gravity in units/sec^2}}

{{tag|name=tidalStrength|type=float|range=[0.0-max]|default=0.0
|description=The amount of energy which will be given by tidal generators.}}

{{tag|name=maxMetal|type=float|range=[0.0-max]|default=0.02
|description=How much metal a map square with the maximum metal value gives.}}

{{tag|name=extractorRadius|type=float|range=[0.0-max]|default=500
|description=The radius of effect that a single extractor will extract from. If two radii intersect, both extractors will suffer from reduced output.}}

{{tag|name=voidWater|type=bool|default=false
|description=Voidwater means there will be no water plane, and all parts of the map under water will be completely transparent, to show the skybox through the map. For example, check [http://springrts.com/phpbb/viewtopic.php?f=13&t=20684&hilit=apophis Apophis_v2]}}. Additionally for this to work, the <code>mapinfo.water.planeColor</code> variable must not be specified in the mapinfo.lua file, delete or comment it out if it exists.

{{tag|name=voidGround|type=bool|default=false
|special=New in 92.0
|description=Allows portions of the ground to be invisible if the map was compiled with a diffuse image that has an alpha channel. The terrain still exists, its just transparent.}}.

{{tag|name=voidAlphaMin|type=float|default=0.9
|description=Controls what alpha level the transparency trigger.}}.

{{tag|name=autoShowMetal|type=bool|default=true
|description=Defines whether the metal map (F4 mode) is shown automatically when a mex is queued for placement.}}

== smf ==
<code><pre>local mapinfo = {
...
smf = {
minHeight = 1000,
maxHeight = -300,
minimapTex = "",
smtFileName0 = "",
smtFileName1 = "",
smtFileName.. = "",
smtFileNameN = "",
},
...
}</pre></code>
{{tag|name=minHeight|type=float|default=0.0
|description=Overrides the minimum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=maxHeight|type=float|default=0.0
|description=Overrides the maximum map height specified while compiling. Compile time height used if undefined}}

{{tag|name=minimapTex|type=string
|special=New in 99.0
| description=Overrides the minimap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=metalmapTex|type=string
|special=New in 99.0
| description=Overrides the metalmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=typemapTex|type=string
|special=New in 99.0
| description=Overrides the typemap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=grassmapTex|type=string
|special=New in 99.0
| description=Overrides the grassmap with an image of your choice, smf used if undefined or invalid}}

{{tag|name=smtFileName[N]|type=string}}

== sound ==
<code><pre>local mapinfo = {
...
sound = {
preset = "default",

passfilter = {
...
},

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

{{tag|name=preset|type=string|default="default"
|description=Sets the _reverb_ preset (= echo parameters), passfilter (the direct sound) is unchanged. To get a list of all possible presets check: [https://github.com/spring/spring/blob/master/rts/System/Sound/OpenAL/EFXPresets.cpp EFXPresets.cpp]}}

{{Tip|You can change the preset at runtime via:
* /tset UseEFX [1|0]
* /tset snd_eaxpreset preset_name (may change to a real cmd in the future)
* /tset snd_filter %gainlf %gainhf (may " " " " " " " " )}}

=== passfilter ===
Note, you likely want to set these tags due to the fact that they are _not_ set by `preset`! So if you want to create a muffled sound you need to use them.
<code><pre>local mapinfo = {
...
sound = {
...
passfilter = {
gainlf = 1.0,
gainhf = 1.0,
},
...
},
...
}</pre></code>

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

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

=== reverb ===
Normally you just want use the `preset` tag but you can use handtweak a preset if wanted with the following tags. To know their function & ranges check the official OpenAL1.1 SDK document.
<code><pre>local mapinfo = {
...
sound = {
...
reverb = {
--density
--diffusion
--gain
--gainhf
--gainlf
--decaytime
--decayhflimit
--decayhfratio
--decaylfratio
--reflectionsgain
--reflectionsdelay
--reflectionspan
--latereverbgain
--latereverbdelay
--latereverbpan
--echotime
--echodepth
--modtime
--moddepth
--airabsorptiongainhf
--hfreference
--lfreference
--roomrollofffactor
},
},
...
}</pre></code>

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

{{tag|name=grassBladeTex|type=string
|description=Specifies the texture to be used on the grass blades themselves. Green-yellow gradients make for some interesting effects. Defaults to the internally generated blade texture. More Information: [[Mapdev:grass]]}}

{{tag|name=grassShadingTex|type=string
|description=Specifies the color variation of the grass across the map. This defaults to the minimap, so the grass color can match the map color. More Information: [[Mapdev:grass]]}}

{{tag|name=detailTex|type=string
|description=Specifies the detail texture for the map. More Information: [[Mapdev:detail]]}}

{{tag|name=specularTex|type=string
|description=More Information: [[Mapdev:specular]]}}

{{tag|name=splatDetailTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=splatDistrTex|type=string
|description=More Information: [[Mapdev:splatdetail]]}}

{{tag|name=skyReflectModTex|type=string
|description=More Information: [[Mapdev:skyreflectmod]]}}

{{tag|name=detailNormalTex|type=string
|description=More Information: [[Mapdev:normal]]}}

{{tag|name=lightEmissionTex|type=string
|description=More Information: [[Mapdev:lightemission]]}}

{{tag|name=parallaxHeightTex|type=string
|description=More Information: [[Mapdev:parallax]]}}

== splats ==
<code><pre>local mapinfo = {
...
splats = {
texScales = {0.02, 0.02, 0.02, 0.02},
texMults = {1.0, 1.0, 1.0, 1.0},
},
...
}</pre></code>
{{tag|name=texScales|type=float[4]
|default={0.2, 0.2, 0.2, 0.2}|description=Scale value for the splat texture in the RGBA channels respectively.}}

{{tag|name=texMults|type=float[4]
|default={1.0, 1.0, 1.0, 1.0}|description=Value for the splat texture in the RGBA channels respectively.}}

== atmosphere ==
<code><pre>local mapinfo = {
...
atmosphere = {
minWind = 5.0,
maxWind = 25.0,

fogStart = 0.1,
fogEnd = 1.0,
fogColor = {0.7, 0.7, 0.8},

sunColor = {1.0, 1.0, 1.0},
skyColor = {0.1, 0.15, 0.7},
skyDir = {0.0, 0.0, -1.0},
skyBox = "",

cloudDensity = 0.5,
cloudColor = {1.0, 1.0, 1.0},
},
...
}</pre></code>

{{tag|name=minWind|type=float|range=[0.0-max]|default=5.0|
description=The minimum amount of energy the wind on the map will give. is clamped to maxwind}}

{{tag|name=maxWind|type=float|range=[0.0-max]|default=25.0
|description=The maximum amount of energy the wind on the map will give}}

{{tag|name=fogStart|type=float|default=0.1
|description=The distance from the camera at which the fog will start. <code>viewRange * fogStart</code>}}

{{tag|name=fogEnd|type=float|default=1.0
|description=The distance from the camera that fog is opaque. <code>viewRange * fogEnd</code> }}}

{{tag|name=fogColor|type=rgb|default={0.7, 0.7, 0.8}
|description=The color of the fog and the infinite plane below the world. The values are in the order Red, Green, Blue. However, giving values higher than 1.0 will give brighter fog and less than 0.0 will give darker}}

{{tag|name=sunColor|type=rgb|default={1.0, 1.0, 1.0}
|description=The color of the sun in the sky. The values are in the order Red, Green, Blue. This will also effect the size of the star. As the values increase (including over 1.0), the disc will get bigger; the inverse is also true}}

{{tag|name=skyColor|type=rgb|default={0.1, 0.15, 0.7}
|description=The color of the sky itself. The values are in the order Red, Green, Blue}}

{{tag|name=skyDir|type=float[3]|default={0.0, 0.0, -1.0}
|description=Is normalised vector}}

{{tag|name=skyBox|type=string
|description=Specify a .dds skybox (also called skycube) for examples and resources see this [http://springrts.com/phpbb/viewtopic.php?f=56&t=11009 thread]}}

{{tag|name=cloudDensity|type=float|range=[0.0-max]|default=0.5
|description=The amount of clouds in the sky}}

{{tag|name=cloudColor|type=rgb
|default={1.0, 1.0, 1.0}|description=The color of the clouds}}

== grass ==
<code><pre>local mapinfo = {
...
grass = {
bladeWaveScale = 1.0,
bladeWidth = 0.32,
bladeHeight = 4.0,
bladeAngle = 1.57,
bladeColor = {0.59, 0.81, 0.57},
},
...
}</pre></code>
{{tag|name=bladeWaveScale|type=float|default=1.0
|description=Specifies how much the wind should effect grass blade movement, as well as the amplitude of the grass motion. Setting it to 0 will stop grass animation}}

{{tag|name=bladeWidth|type=float|default=0.32
|description=Specifies the width of each blade of grass}}

{{tag|name=bladeHeight|type=float|default=4.0
|description=Specifies the length of each blade of grass}}

{{tag|name=bladeAngle|type=float|default=1.57
|description=Specifies the curvature of each blade of grass. Unit is radians. 0 means completely straight blades of grass}}

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

== Lighting ==
<code><pre>local mapinfo = {
...
lighting = {
--// dynsun
sunStartAngle = 0.0,
sunOrbitTime = 1440.0,
sunDir = {0.0, 1.0, 2.0, 1e9},

--// unit & ground lighting
groundAmbientColor = {0.5, 0.5, 0.5},
groundDiffuseColor = {0.5, 0.5, 0.5},
groundSpecularColor = {0.1, 0.1, 0.1},
groundShadowDensity = 0.8,
unitAmbientColor = {0.4, 0.4, 0.4},
unitDiffuseColor = {0.7, 0.7, 0.7},
unitSpecularColor = {0.7, 0.7, 0.7},
unitShadowDensity = 0.8,

specularExponent = 100.0,
},
...
}</pre></code>
{{tag|name=sunStartAngle|type=float|default=0.0}}

{{tag|name=sunOrbitTime|type=float|default=1440.0}}

{{tag|name=sunDir|type=float[3]|default={0.0, 1.0, 2.0}
|description=The direction of the sun, which is normalized by Spring. The Y-axis is up}}

{{tag|name=groundAmbientColor|type=rgb|default={0.5, 0.5, 0.5}
|description=The ambient (non-sun-lit) color of ground, grass, trees and other features. The values are in the order Red, Green, Blue}}

{{tag|name=groundDiffuseColor|type=rgb|default={0.5, 05, 0.5}
|description=The color of ground where it is fully sun lit (added to GroundAmbientColor). The values are in the order Red, Green, Blue}}

{{tag|name=groundSpecularColor|type=rgb|default={0.1, 0.1, 0.1}
|description=and its effect when a specular map is present?}}

{{tag|name=groundShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go.}}

{{tag|name=unitAmbientColor|type=float|default={0.4, 0.4, 0.4}
|description=The ambient (non-sun-lit) color of units and corpses}}

{{tag|name=unitDiffuseColor|type=rgb|default={0.7, 0.7, 0.7}
|description=The color of units where they is fully sun lit (added to UnitAmbientColor). The color of units where they is fully sun lit (added to UnitAmbientColor)}}

{{tag|name=unitSpecularColor|type=rgb|default=unitDiffuseColor}}

{{tag|name=unitShadowDensity|type=float|default=0.8
|description=How far from the non shadowed to the ambient color stuff in shadow will go}}

{{tag|name=specularExponent|type=float|default=100}}

== water ==
<code><pre>local mapinfo = {
...
water = {
damage = 0.0,

repeatX = 0.0,
repeatY = 0.0,

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

ambientFactor = 1.0,
diffuseFactor = 1.0,
specularFactor = 1.0,
specularPower = 20.0,

planeColor = {0.0, 0.4, 0.0},

surfaceColor = {0.75, 0.8, 0.85},
surfaceAlpha = 0.55,
diffuseColor = {1.0, 1.0, 1.0},
specularColor = {0.5, 0.5, 0.5},

fresnelMin = 0.2,
fresnelMax = 0.8,
fresnelPower = 4.0,

reflectionDistortion = 1.0,

blurBase = 2.0,
blurExponent = 1.5,

perlinStartFreq = 8.0,
perlinLacunarity = 3.0,
perlinAmplitude = 0.9,
windSpeed = 1.0, --// does nothing yet

shoreWaves = true,
forceRendering = false,

--// undefined == load them from resources.lua!
--texture = "",
--foamTexture = "",
--normalTexture = "",
--caustics = {
-- "",
-- "",
--},

},
...
}</pre></code>
{{tag|name=damage|type=float|default=0.0
|description=Number of hit points per game frame (30 frames per second) a unit will be damaged if it is in the water. As of 95.0 by default damage is also applied to hovercraft units. i wonder if this can be made to give life...?}}

{{tag|name=repeatX|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=repeatY|type=float|default=0.0
|description=effects the filing frequency of the watertexture}}

{{tag|name=absorb|type=rgb|default={0.0, 0.0, 0.0}
|description=How fast different colors (RGB in order) are absorbed by the water. Can be used to make the water look murky at deeper sections and so on. How this works: the waterabsorb value for the color channel gets multiplied by the depth of the water at a point, and this product gets subtracted from WaterBaseColor, until WaterMinColor is reached. Example: WaterAbsorb is 0.01, for the red channel, and we want to know how much red will be left in the water at a Spring elevation of -100, since 0.01*100= 1 , at this depth, there will be no more red component in the water, unless WaterMinColor is higher than 0 on the red channel}}

{{tag|name=baseColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The color of the water just beneath the surface plane. This is the starting color from which deeper waters will absorb more color. The values are in the order Red, Green, Blue}}

{{tag|name=minColor|type=rgb|default={0.0, 0.0, 0.0}
|description=The smallest values the water will go down to due to WaterAbsorb}}

{{tag|name=ambientFactor|type=float|default=1.0}}

{{tag|name=diffuseFactor|type=float|default=1.0}}

{{tag|name=specularFactor|type=float|default=1.0}}

{{tag|name=specularPower|type=float|default=20.0}}

{{tag|name=planeColor|type=rgb|default={0.0, 0.4, 0.0}
|description=This sets the color of the groundplane under the water outside the map boundaries}}

{{tag|name=surfaceColor|type=rgb|default={0.75, 0.8, 0.85}
|description=The color of the water surface. Mostly affects the colors of the reflections off the top of the water. Has no effect on bump mapped water!}}

{{tag|name=surfaceAlpha|type=float|default=0.55
|description= Transparency of the water surface. 0 meaning almost fully transparent water plane(low amount of reflections visible), and 1 being nearly opaque (massive amount of reflections)}}

{{tag|name=diffuseColor|type=rgb|default=value
|description=This specifies the diffuse color of the water body. WARNING: use of this tag disables the effect of WaterAbsorb , in fact, this tag does nothing but disable WaterAbsorb. Avoid}}

{{tag|name=specularColor|type=rgb|default=lighting.groundDiffuseColor}}

{{tag|name=fresnelMin|type=float|default=0.2}}

{{tag|name=fresnelMax|type=float|default=0.8}}

{{tag|name=fresnelPower|type=float|default=4.0}}

{{tag|name=reflectionDistortion|type=float|default=1.0
|description=How much the surface should distort reflections that are cause by waves not being level: ergo it adds more choppyness to your reflections sensible from 0 to 20}}

{{tag|name=blurBase|type=float|default=2.0
|description=Something to do with blur, but it just seems to cause banding with values under 2 and corruption with values above 10}}

{{tag|name=blurExponent|type=float|default=1.5
|description=How much reflections on water surface should be blurred together with the water surface, lower values meaning clearer reflections, (0.2-5) Warning: above 5 seems to cause water corruption}}

{{tag|name=perlinStartFreq|type=float|default=8.0
|description=Wave sizes, smaller = big waves, sensible: [1,20] (influence the wave sizes)}}

{{tag|name=perlinLacunarity|type=float|default=3.0
|description=Defines the size of the perlin waves, small values being big waves ([0.2,5] is sensible)}}

{{tag|name=perlinAmplitude|type=float|default=0.9
|description=Base stillness of water surface, 0 is dead still, 1 is 'windy' .This doesnt affect the bump texture depth, besides the fact that this disables the bump texture when set to 0}}

{{tag|name=windSpeed|type=float|default=1.0
|description=does nothing yet}}

{{tag|name=shoreWaves|type=bool|default=true}}

{{tag|name=forceRendering|type=bool|default=true}}

will have to ask about those undefined tags

== teams ==
<code><pre>local mapinfo = {
...
teams = {
[0] = {startPos = {x = 2033, z = 852}},
[1] = {startPos = {x = 10134, z = 852}},
[2] = {startPos = {x = 0, z = 0}},
[3] = {startPos = {x = 0, z = 0}},
...
},
...
}</pre></code>
Holds an array of start positions

== terrainTypes ==
<code><pre>local mapinfo = {
...
terrainTypes = {
[0] = {
name = "Default",
hardness = 1.0,
receiveTracks = true,
moveSpeeds = {
tank = 1.0,
kbot = 1.0,
hover = 1.0,
ship = 1.0,
},
},
[1] = {
...
},
...
},
...
}</pre></code>
Holds an array of start types where each element contains:

{{tag|name=name|type=string
|description=A label for the terrain type}}

{{tag|name=hardness|type=float|range=[0.001-max]|default=1.0
|description=Used as a multiplier against the mapinfo.mapHardness value. Can be used to make a particular terrain type softer or harder. A value of '1' will make it as hard as MapHardness, and 0.5 will make it half as hard}}

{{tag|name=receiveTracks|type=bool|default=true
|description= Effects whether track decals will be placed on the ground from moving vehicles}}

{{tag|name=moveSpeeds.tank|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for tanks when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.kbot|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for kbots when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.hover|type=float|range=[0.0-max]|default=1.0
|description= Speed multiplier for hovercraft when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

{{tag|name=moveSpeeds.ship|type=float|range=[0.0-max]|default=1
|description= Speed multiplier for ships when travelling on the parent terrain type. A value of '1.0' is normal speed, 0.5 will make them travel at half speed on the parent terrain type}}

== custom ==
<code><pre>local mapinfo = {
...
custom = {
fog = {
color = {0.26, 0.30, 0.41},
height = "80%", --// allows either absolue sizes or in percent of map's MaxHeight
fogatten = 0.003,
},
precipitation = {
density = 30000,
size = 1.5,
speed = 50,
windscale = 1.2,
texture = 'LuaGaia/effects/snowflake.png',
},

},
...
}</pre></code>

[[Category:Map Dev]]

Mapdev:splatdetailnormals

2016-02-10T12:03:26Z

Beherith: /* Detail Normal Textures */

= Detail Normal Texture Splatting (DNTS) =

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

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

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

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

The system uses the same splatDistributionTexture as regular SSMF.

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

Example result:

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

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

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

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

= Specification =

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

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

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

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

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

Mapdev:splatdetailnormals

2016-02-10T10:45:41Z

Beherith: /* Detail Normal Texture Splatting (DNTS) */

= Detail Normal Texture Splatting (DNTS) =

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

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

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

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

The system uses the same splatDistributionTexture as regular SSMF.

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

Example result:

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

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

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

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

= Specification =

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

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

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

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

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

Mapdev:splatdetailnormals

2016-02-10T10:15:05Z

Beherith: /* Detail Normal Textures */

= Detail Normal Texture Splatting (DNTS) =

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

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

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

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

The system uses the same splatDistributionTexture as regular SSMF.

Example result:

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

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

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

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

= Specification =

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

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

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

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

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

Animation-CobCallins

2016-02-03T10:10:12Z

Beherith: /* Weapons */

==Source==

Some (but not all) are listed near the end of this file: {{sourcelink|file=rts/Sim/Units/Scripts/CobInstance.cpp}}

==Purpose==
Callins have two purposes:

First, they allow a script to be notified when an event happens, such as the unit being created or destroyed.

Second, they allow the engine to get information from the script. Sometimes this is accomplished through a return value, but usually this is done by setting one of the arguments to a function to the requested value.

==Callins==

===General===

*Create(): Called when the unit is created. "Created" means when the unit's nanoframe is created; if you want to wait until the unit is actually finished, you'll have to use something like

while(GET BUILD_PERCENT_LEFT) sleep 250;

*Activate()/Deactivate(): Called when the unit is turned on/off.
*Killed(severity, corpsetype): Called when the unit is killed. Severity indicates how many percent of the unit's hit points were dealt by the final blow. Corpsetype basically indicates the number of times the unit and its corpses are destroyed; for example, corpsetype = 3 acts as if the unit is destroyed, the corpse is destroyed, and the corpse's corpse is destroyed. If it runs out of corpses nothing is left behind. Set corpsetype to the desired value.

===Movement===

*StartMoving()/StopMoving(): Called when the unit starts/stops moving. This includes rotation, so don't be surprised if StartMoving() sometimes gets called when a unit starts aiming at a target.
*SetSFXOccupy(terraintype): Supposedly called when the unit changes terrain type, although it didn't work last time I tried it? Maybe I was using it wrong. terraintype: 0 = transported, 1 = sea, 2 = deep sea (greater than 5 water depth and unit is upright), 4 = land.
*MoveRate[0...3](): Appears to be the aircraft equivalent of SetSFXOccupy. MoveRate3 doesn't appear to actually be used. MoveRate1 is called when the aircraft takes off or lands. If the aircraft is not taking off or landing, MoveRate0 is called when the aircraft drops below 1/3 maximum speed, MoveRate2 is called when the aircraft exceeds 2/3 maximum speed, and MoveRate1 is called when the aircraft enters within 1/3-2/3 maximum speed. I don't know if this actually works.
*SetDirection(heading): Used only for wind generators. Gives the direction of the wind.
*SetSpeed(speed): Used for wind generators, tidals, and mexes. Basically more resources = higher speed.

Comments:
* MoveRate0 ... Moverate3 only work with gunship type of aircraft:
[http://springrts.com/phpbb/viewtopic.php?f=14&t=26890&hilit=Moverate0 Forum thread]
* SetSFXOccupy(terraintype) for aircraft: terraintype = 4 when flying over land and 1 when flying over water. (I used "get IN_WATER" to find out when unit is submerged).

===Weapons===

For weapons, X means either the number of the weapon, or "Primary", "Secondary", or "Tertiary" (don't put "Weapon" for these). I recommend using numbers, since it's cleaner and you can use more than three weapons that way.

*AimWeaponX(heading, pitch): Called every ~0.5s when the unit is aiming the weapon at a target. This is used to turn a unit's turrets toward the target. Return 1 when the weapon is ready to fire. Alternately, return 0 if you don't want the weapon to fire (you can use this to disable weapons).
*AimFromWeaponX(piecenum): You should set piecenum to a piece of the model; LOS is traced from the here to the target to see if the weapon can fire.
*FireWeaponX(): Called whenever the trigger is pulled on a weapon. This occurs before the ''first'' shot in a burst/projectile salvo (only).
*ShotX(zero): Called before every shot a weapon fires. This includes burst and projectile tags. This happens after FireWeaponX(), even for the first shot. There's one input argument which is 0, because of a typo in the source.
*QueryWeaponX(piecenum): You should set piecenum to a piece of the model. The shot starts from this piece of the model; this is called for this purpose after FireWeaponX() and ShotX(). LOS is also traced from here to the target to see if a weapon can fire. Make sure this is a piece on the weapon's turret. Not doing this right can cause headaches; example: http://trac.caspring.org/wiki/GunsJammingOnShips
*EndBurstX(): Called after the last shot in a burst.
*BlockShotX(in unitID, out block, in usertarget)
*TargetWeightX(unitID, weightMod)
*RockUnit(anglex, anglez): Called when the unit fires. Use it to rock the unit on firing, although there are other ways to do this. The angles returned are in unit space, and are multiplied by 500.
*HitByWeapon(anglex, anglez): Called when the unit is hit by a weapon. Angles are in unit space and multiplied by 500.
*HitByWeaponID(anglex, anglez, weapondefid, damage): Called when the unit is hit by a weapon. Angles are in unit space and multiplied by 500.
*SetMaxReloadTime(time): Called on unit creation. time is the time in ms that it takes the slowest-firing weapon to reload.

===Construction===

*StartBuilding(): Called when the unit starts building.
*StopBuilding(): Called when the unit stops building.
*QueryNanoPiece(piecenum): You should set piecenum to the piece you want the nanospray to come from.
*QueryBuildInfo(piecenum): For factories. You should set piecenum to the piece you want the unit to be built on.

===Transportation===
*Falling(): Used for airdropping units?
*Landed(): Used for airdropping units?
*QueryTransport(piecenum): You should set piecenum to the piece you want the transported unit to be attached to.
*BeginTransport(): Called when an air transport picks up a unit.
*EndTransport(): Called when an air transport becomes empty.
*TransportPickup(): Called when a land transport picks up a unit.
*TransportDrop(): Called when a land transport becomes empty.
*StartUnload(): Called when the transport starts the unloading process.

===Landing Pads===
*QueryLandingPadCount(count): You should set count to the number of landing pads. However, it doesn't seem to be actually necessary to do this unless you want more than 16 pads.
*QueryLandingPad(piecenum1, piecenum2, piecenum3...): Set each piecenum to a different landing pad piece.

[[Category:Animation]]