Spring - User contributions [en]

Lua:Callins

2016-02-11T14:44:16Z

Jools: /* Unsynced 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].

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

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

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

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

== Unsynced Only ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Drawing ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Synced - Unsynced Shared ==

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

=== Game ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[[Category: Lua]]

XTA

2015-08-01T00:15:07Z

Jools: /* Mapslists */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost - for beginners
[durian]Autohost - for fleabowl
[elderberry]Autohost - for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts ==

To start up one of these hosts, if it is not running but another host is running, you can use the command:

<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:

<code>!setengine <engine name or latest></code> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
Pick a random "good" map: <code>!map</code>

Download a map: <code>!dlmap <mapname or url></code> After this wait 30 seconds or issue the command <code>!reloadarchives</code>

===Mapslists===

Maplists act like filters: when you (for example) set the !maplist 1v1 command, all subsequent listing of maps will be only from the 1v1 map list. So this will allow you to only use a subset of all maps. There are now these defined maplists, but more can be requested:
<code>!maplist 1v1 | 2v2 | 3v3 | 4v4 | 5v5 | 6v6 | teams | bigteams | 3ffa | 4ffa | 5ffa | fleas | good</code>

To return to all maps, use this command:
<code>!maplist all</code>

Show list of maplists: <code>!printmaplist</code>

Show list of maps in a specific list: <code>!printmaplist <listname></code>, for example <code>!printmaplist 1v1</code>

Add current map to a list: <code>!addmap <listname></code>, for example <code>!addmap 1v1</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-08-01T00:14:31Z

Jools: /* Mapslists */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost - for beginners
[durian]Autohost - for fleabowl
[elderberry]Autohost - for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts ==

To start up one of these hosts, if it is not running but another host is running, you can use the command:

<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:

<code>!setengine <engine name or latest></code> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
Pick a random "good" map: <code>!map</code>

Download a map: <code>!dlmap <mapname or url></code> After this wait 30 seconds or issue the command <code>!reloadarchives</code>

===Mapslists===

Maplists act like filters: when you (for example) set the !maplist 1v1 command, all subsequent listing of maps will be only from the 1v1 map list. So this will allow you to only use a subset of all maps. There are now these defined maplists, but more can be requested:
<code>!maplist 1v1 | 2v2 | 3v3 | 4v4 | 5v5 | 6v6 | teams | bigteams | 3ffa | 4ffa | 5ffa | fleas | good</code>

To return to all maps, use this command:
<code>!maplist all</code>

''More commands:''

Show list of maplists: <code>!printmaplist</code>

Show list of maps in a specific list: <code>!printmaplist <listname></code>, for example <code>!printmaplist 1v1</code>

Add current map to a list: <code>!addmap <listname></code>, for example <code>!addmap 1v1</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-07-31T23:48:47Z

Jools: /* Maps */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost - for beginners
[durian]Autohost - for fleabowl
[elderberry]Autohost - for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts ==

To start up one of these hosts, if it is not running but another host is running, you can use the command:

<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:

<code>!setengine <engine name or latest></code> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
Pick a random "good" map: <code>!map</code>

Download a map: <code>!dlmap <mapname or url></code> After this wait 30 seconds or issue the command <code>!reloadarchives</code>

===Mapslists===

Maplists act like filters: when you (for example) set the !maplist 1v1 command, all subsequent listing of maps will be only from the 1v1 map list. So this will allow you to only use a subset of all maps. There are now these defined maplists, but more can be requested:
Maplists: 1v1 (30), 2v2 (7), 3v3 (5), 4v4 (6), 5v5 (4), 6v6 (0), teams (7), bigteams (1), 3ffa (11), 4ffa (3), 5ffa (4), fleas (0), good (9)
(the number in brackets indicates the number of maps as of July 31st, 2015).

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-03-10T23:24:10Z

Jools: /* Important Autohost Commands */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost - for beginners
[durian]Autohost - for fleabowl
[elderberry]Autohost - for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts ==

To start up one of these hosts, if it is not running but another host is running, you can use the command:

<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:

<code>!setengine <engine name or latest></code> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
Pick a random "good" map: <code>!map</code>

Download a map: <code>!dlmap <mapname or url></code> After this wait 30 seconds or issue the command <code>!reloadarchives</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-03-10T23:22:21Z

Jools: /* Managing the autohosts */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost -- for beginners
[durian]Autohost -- for fleabowl
[elderberry]Autohost -- for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts ==

To start up one of these hosts, if it is not running but another host is running, you can use the command:

<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:

<code>!setengine <engine name or latest></code> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
Pick a random "good" map: <code>!map</code>

Download a map: <code>!dlmap <mapname or url></code> After this wait 30 seconds or issue the command <code>!reloadarchives</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-03-10T23:19:47Z

Jools: /* Managing the autohosts */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost -- for beginners
[durian]Autohost -- for fleabowl
[elderberry]Autohost -- for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts ==

To start up one of these hosts, if it is not running but another host is running, you can use the command:

<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:

<code>!setengine <engine name or latest></code> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
Pick a random "good" map: <code>!map</code>

Download a map: <code>!dlmap <mapname or url></code> After this wait 30 seconds or issue the command <code>!reloadarchives</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-03-10T23:18:47Z

Jools: /* Important Autohost Commands */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost -- for beginners
[durian]Autohost -- for fleabowl
[elderberry]Autohost -- for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts ==

To start up one of these hosts, if it is not running but another host is running, you can use the command:
<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:
<code>!setengine <engine name or latest> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
Pick a random "good" map: <code>!map</code>

Download a map: <code>!dlmap <mapname or url></code> After this wait 30 seconds or issue the command <code>!reloadarchives</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

XTA

2015-03-10T23:17:05Z

Jools: /* Important Autohost Commands */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==
The easiest way to download latest XTA is via the the automatic download system of your favorite multiplayer lobby.

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
Official XTA autohosts are:
<pre>
[semprini]Autohost - for all
[loganberry]Autohost -- for beginners
[durian]Autohost -- for fleabowl
[elderberry]Autohost -- for testing new xta versions
</pre>

Of course you can also use either of these hosts for other purposes.

== Managing the autohosts

To start up one of these hosts, if it is not running but another host is running, you can use the command:
<code>!spawn <autohost></code> - where <autohost> is one of semprini, logan, elder or durian.

In elderberry autohost you can also set another spring engine with the command:
<code>!setengine <engine name or latest> - for example !setengine 98.0 to set engine to Spring 98.0

To get a long, complete list type of commands: <code>!help</code>

Below are some often used commands for quicker looking:
===Maps===
pick a random "good" map: <code>!map</code>

===King of the Hill===
Add an one more startbox than they are teams.

<code>!koth 1</code> - enable King of the Hill mode.

<code>!koth 0</code> - disable King of the Hill mode.

<code>!hilltime X</code> - team has to control hill for X minutes to win.

<code>!gracetime Z</code> - at game start hill stays neutral for Z minutes.

===Game options===
<code>!mode killall</code> - destroy all enemy units to win

<code>!mode comends</code> - destroy enemy Commanders to win

<code>!spidertortoise 0</code> - Turn spiders & turtle units off.



[[Category:Games]]

Links

2014-11-30T18:20:42Z

Jools: /* AutoHosts (dedicated servers) */

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

= Community Links =
*[[Associated_Development_Groups|Associated Development Groups]] - various forums etc
*[http://springfiles.com/ SpringFiles] - download page for maps & games
*[http://weblobby.springrts.com WebLobby]
*[http://ladder.springrts.com/ Ladder]
*[[mumble|mumble server]]
*[http://feeds.feedburner.com/SpringCommunityHeadlines SpringInfo Community News]
*[http://replays.springrts.com/ Spring Replays]

= Development Links =

*[http://stacktranslate.springrts.com Stacktrace Translator]
*[http://answers.springlobby.info/questions/ Developer Q&A]
*[http://springrts.com/mantis/ Mantis] - place to report engine bugs, problems & (minor) feature requests
*[http://buildbot.springrts.com/waterfall?reload=30 buildbot waterfall]
*[http://springrts.com/dl/buildbot/default/ spring engine development builds]
*[http://spring.osocial.se/hierarchy.html Spring Doxygen]
*[http://spring.osocial.se/db/de7/unitsync__api_8h.html unitsync API]
*[[Rapid]] - the games download api
*[[Development:Minutes | Meeting Minutes]] - Archived chatlogs of engine developer meetings
*[http://springrts.com/dl/buildbot/default/master/{{StableEngineVersion}}/manpages/spring.6.html Spring's manpage]

= Repo. Links =
== Engine & Content ==
*[https://github.com/spring Spring github repo]
*[[Gamedev:PublicRepos | Game Repos]] - Publicly readable game repos
=== [https://github.com/jk3064/ jK's lua repos] ===
*[https://github.com/jk3064/Map-Blueprint Map Blueprint] - basic container to create new maps ([[MakingMapsWithBluePrintAndMapConv |see]])
*[https://github.com/jk3064/chiliui Chili] - a lua based gui framework
*[https://github.com/jk3064/chili_loadscreen Chili Loadscreen] - a chili based loadscreen
*[https://github.com/jk3064/Custom-Unit-Shader-Framework CustomUnitShaders] - a lua based per-unit shader framework (includes normalmap support)

== Lobby Server & Clients ==
*[[uberserver]] - the lobby server
*[http://code.google.com/p/zero-k/ ZKLobby's google code page] - a .net lobby
*[[SpringLobby]] - a wxWidgets lobby
*[https://github.com/cleanrock/flobby flobby] - a FLTK based lobby (linux only)

== AutoHosts (dedicated servers) ==
*[[SPADS]]
*[[Springie]] - mainly used by ZK

== Content Downloaders ==
*[[pr-downloader]] - an unified download app & lib (can dl from plasma, rapid, ...)
*[https://github.com/spring/RapidTools rapid server tools] - tools to create a rapid repository
*[[Plasma]] - a torrent based download system (mostly for maps, games should use rapid)

== Tools ==
*[[Upspring]]
*[[MapConv]]
*[[MapConvNG]]

= SpringFiles API =
*[http://api.springfiles.com human readable]
*[http://api.springfiles.com/xmlrpc.php xmlrpc]
*[https://github.com/springfiles/upq/blob/master/doc/exampleclient.py example client]

= Miscellaneous =

*[http://packages.springrts.com Rapid Upload Interface] - Mappers & GameDevs can upload their files via it
*[http://planet-wars.eu/ModelBase/Models.aspx Model Database]

= Statistics =

*[http://www.ohloh.net/p/springrts ohloh springrts]
*[http://zero-k.info/stats/ lobby stats]

[[Category:Development]]

Lua:Callins

2014-11-07T21:17:45Z

Jools: /* Lua Callins */

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

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

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

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

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|params = type, id
|return = number cmdID
|description = Used to set the default command when a unit is selected.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = none
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value.
}}

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

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

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

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

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

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

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

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

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

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

=== Drawing ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Synced - Unsynced Shared ==

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

=== Game ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = AllowWeaponTargetCheck
|params = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = bool allow
|description = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag.
}}

{{LuaCallin
|name = AllowWeaponTarget
|params = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = bool allowed, number priority
|description = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value controls the priority of the target (maximum of <code>1.0</code>).
}}

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

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

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

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

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

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

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

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

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

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

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

[[Category: Lua]]

Lua:Callins

2014-11-07T20:05:20Z

Jools: /* Lua Callins */

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

Some functions may differ between (synced) gadget and widgets; those are in the [[#Synced_-_Unsynced_Shared]] section. Essentially the reason is that all information should be available to synced (game logic controlling) gadgets, but restricted to unsynced gadget/widget (e.g. information about an enemy unit only detected via radar and not yet in LOS). In such cases the full (synced) param list is documented.
<a href="http://imgur.com/Gr5qnAx"><img src="http://i.imgur.com/Gr5qnAx.png" title="source: imgur.com" /></a>

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

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

== Unsynced Only ==

{{LuaCallin
|name = DefaultCommand
|params = type, id
|return = number cmdID
|description = Used to set the default command when a unit is selected.
}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = KeyPress
|params = key, mods, isRepeat
|return = none
|description = Called repeatedly when a key is pressed down. If you want an action to occur only once check for <code>isRepeat == false</code>. The <code>mods</code> parameter is a table, with keys <code>alt</code>, <code>ctrl</code>, <code>meta</code> and <code>shift</code> each having a boolean value.
}}

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

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

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

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

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

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

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

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

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

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

=== Drawing ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Synced - Unsynced Shared ==

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

=== Game ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{LuaCallin
|name = AllowWeaponTargetCheck
|params = attackerID, attackerWeaponNum, attackerWeaponDefID
|return = bool allow
|description = Determines if this weapon can automatically generate targets itself. See also {{xtaglink|Gamedev:WeaponDefs|commandFire}} weaponDef tag.
}}

{{LuaCallin
|name = AllowWeaponTarget
|params = attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defPriority
|return = bool allowed, number priority
|description = Controls blocking of a specific target from being considered during a weapon's periodic auto-targeting sweep. The second return value controls the priority of the target (maximum of <code>1.0</code>).
}}

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

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

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

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

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

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

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

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

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

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

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

[[Category: Lua]]

Lua SyncedRead

2014-11-06T17:33:36Z

Jools: /* CommandQueues */

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

== Game ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

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

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

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

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

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

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

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

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

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

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


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

Post 95.0 this no longer returns neutral units

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

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

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

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

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

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

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

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

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

'''Spring.GetUnitVelocity''' velw new in 95.0
( number unitID ) -> nil | number velx, number vely, number velz, number velLength
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding''' returns what unit a constructor/factory is currently building
( number unitID ) -> nil | number unitID
'''Spring.GetUnitCurrentBuildPower''' {{new|92.0}}
( number unitID ) -> nil | number buildPower
'''Spring.GetUnitNanoPieces'''
( number unitID ) -> nil | { [1] = number piece1, etc ... }
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID [, number weaponID = -1] ) -> nil | number isEnabled, number curPower
'''Spring.GetUnitTravel'''
( number unitID ) -> nil | number travel, number travelPeriod
'''Spring.GetUnitFuel'''
( number unitID ) -> nil | number
'''Spring.GetUnitFlanking'''
( number unitID, string "dir" ) -> nil | number x, number y, number z
( number unitID, string "mode" | "moveFactor" | "minDamage" | "maxDamage" ) -> nil | number
( number unitID ) -> nil | number mode, number modilityAdd,
number minDamage, number maxDamage, number dirX, number dirY, number dirZ
'''Spring.GetUnitSensorRadius'''
( number unitID, string type ) -> nil | number radius
possible types are: airLos, radar, sonar, seismic, radarJammer & sonarJammer
'''Spring.GetUnitLosState''' raw is only available in gadgets
( number unitID [, number allyTeamID [, boolean raw] ] ) -> nil | number raw |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' surfaceDist new in 95.0
( number unitID1, number unitID2 [, boolean 2D] [, boolean surfaceDist] ) -> nil | number distance
returns the distance of 2 units, surfaceDist calculates the distance between the unitsphere surfaces instead of their midpos

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

==== Unit Weapon Informations ====
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"

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

'''Spring.GetUnitWeaponTryTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponTestTarget''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponTestRange''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

'''Spring.GetUnitWeaponHaveFreeLineOfFire''' {{new|94.0}}
( number unitID, number weaponNum,
number targetID | number posX, number posY, number posZ ) -> nil | boolean success

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

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

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

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

=== Unit Pieces ===
'''Spring.GetUnitVectors'''
( number unitID ) -> nil | {frontX,frontY,frontZ}, {upX,upY,upZ}, {rightX,rightY,rightZ}
'''Spring.GetUnitPiecePosition'''
( number unitID, number piece ) -> number posx, number posy, number posz
Returns piece position in unit space

'''Spring.GetUnitPieceDirection'''
( number unitID, number piece ) -> number dirx, number diry, number dirz
Consider this broken. It returns reverse direction in piece space (i.e. vertex(0)-vertex(1)) for pieces with >= 2 vertices and (1,1,1) for pieces with < 2 vertices)

'''Spring.GetUnitPieceMatrix'''
( number unitID, number piece ) -> { [1] = number, ... , [16] = number }
'''Spring.GetUnitPieceList'''
( number unitID ) -> { [1] = string "piecename", ... , [pieceNumN] = string "piecename" }
'''Spring.GetUnitPieceMap'''
( number unitID ) -> { "piecename1" = pieceNum1, ... , "piecenameN" = pieceNumN }
'''Spring.GetUnitPieceInfo'''
( number unitID, number piece ) -> {
"name" = string "piecename",
"isEmpty" = boolean,
"children" = { [1] = string "piecename", ... },
"min" = { [1] = number x, [2] = number y, [3] = number z },
"max" = { [1] = number x, [2] = number y, [3] = number z },
"offset" = { [1] = number x, [2] = number y, [3] = number z },
"parent" = string "parentpiecename",
}
"parent" field {{New|95.0}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Projectiles ==

'''Spring.GetProjectilesInRectangle'''

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

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

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

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

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


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

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

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

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

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

[[category: Lua]]

Gamedev:PublicRepos

2014-10-02T17:04:16Z

Jools:

==What Is This?==
This is a small collection of publicly known and readable code repositories for established Spring games. The intention being to provide a wealth of examples to all game developers from noob to pro.

== Known Repos ==
[https://code.google.com/p/air-raid-spring/ Air Raid]

[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/ Balanced Annihilation]

[https://code.google.com/p/basically-ota/ BOTA]

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT Conflict Terra]

[http://www.petro.darkstars.co.uk/damned/ Damned]

[https://code.google.com/p/evolutionrts/source/browse/#svn%2Ftrunk%2Fevolutiondev.sdd Evolution RTS]

[https://github.com/imperialwinter/swiw.sdd Imperial Winter]

[http://code.google.com/p/journeywar/ Journeywar]

[https://github.com/jk3064?tab=repositories jK]
* [[Chili]]
* [[LUPS]]
* Custom-Unit-Shader-Framework
* [[Mapdev:Main#Blueprint | Map-Blueprint]]

[https://github.com/David-Becker/mods KDR_11k]
* Cuberors' Finest
* CvC
* Doserz
* Fibre
* GINTA
* Gun Wings Test
* Light Side of Spring
* MicroModules
* Pong

[https://sourceforge.net/p/mwspring/code/ MechCommander: Legacy]

[https://github.com/spring1944/spring1944 Spring: 1944]

[https://code.google.com/p/springtanks/source/browse/#svn%2Ftrunk Spring Tanks]

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd Spring Tutorial Game]

[https://github.com/KingRaptor/THIS THIS]

[http://code.google.com/p/xta-springrts/ XTA]

[http://code.google.com/p/zero-k/source/browse/trunk#trunk%2Fmods%2Fzk Zero-K]

[[Category:Game Dev]]

Gamedev:WeaponDefs

2014-04-03T08:47:06Z

Jools: /* Cannon */

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

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

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

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

* {{sourcelink|file=rts/Sim/Weapons/WeaponDef.cpp}}

==Data Types==
Tags may be one of the following data types:
* <code>int</code> - An integer number
* <code>float</code> - A number with decimals.
* <code>bool</code> - A value which can be <code>true</code> or <code>false</code>.
* <code>string</code> - Text, or more precisely a string of alphanumeric characters.
* <code>float[3]</code> - A vector, with three <code>float</code> components, representing x, y and z axes (y is 'up').

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

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

It is usual to name the returned WeaponDef table the internal <code>weaponName</code> desired for the weapon.

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

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

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

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

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

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

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

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

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

{{tag
|name = weaponVelocity
|type = float
|default = 0.0
|description = The velocity in [[elmo]]s per second of the weapon projectile.}}

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

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

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

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

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

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

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

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

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

====Collision & Avoidance====

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

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

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

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

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

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

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

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

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

{{tag
|name = collisionSize
|type = float
|default = 0.05 (0.5 for [[#Flame]] and [[#LaserCannon]], 10.0 for [[#Dgun]])
|description = The radius used in collision calculations. For non-instant-hit weapons which do not use a 3D {{taglink|model}}.}}

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

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

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

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

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

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

{{tag
|name = tolerance
|type = float
|default = 3000.0
|description = The amount to which the weapon's "real" aim can be off while the weapon will still be able to fire accurately at the target. For {{taglink|turret|false}} or {{taglink|fixedlauncher|true}} weapons this determines in what arc the unit will fire.}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Bouncing====

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

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

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

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

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

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

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

{{tag
|name = craterAreaOfEffect
|type = float
|default = areaOfEffect * 0.5
|description = The ''radius'' in [[elmo]]s in which the weapons explosion will cause terrain cratering.}}

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

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

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

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

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

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

====Bursts====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Visuals====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====AircraftBomb Visuals====

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

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

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

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

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

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

====BeamLaser Visuals====

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

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

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

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

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

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

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

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

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

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

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

====Cannon Visuals====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====LaserCannon Visuals====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Sub Tables==

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

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

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

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

The following tags are repulser specific:

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

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

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

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

The following tags are general behaviour for all shields:

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

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

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

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

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

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

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

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

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

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

The following tags control the visual aspects of the shield:

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

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

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

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

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

===customParams===
The <code>customParams</code> subtable of a WeaponDef allows the game designer to give their weapons custom attributes, which can then be accessed via lua gadgets and widgets. It is a map (key-value pair indexed table) of strings. When accessing these attributes in lua the strings can be turned back into numbers, bools or even tables. This gives great control to game designers to essentially implement their own behaviour tags.

There are no additional tags specific to this subtable

==Examples==
[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/weapons 'Balanced Annihilation' WeaponDefs]

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Fweapons 'Conflict Terra' WeaponDefs] (Most are integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]])

[https://code.google.com/p/evolutionrts/source/browse/#svn%2Ftrunk%2Fevolutiondev.sdd%2FWeapons 'Evolution RTS' WeaponDefs] (Most are integrated into their [[Gamedev:UnitDefs#Examples|UnitDefs]])

[https://github.com/spring1944/spring1944/tree/master/weapons 'Spring: 1944' WeaponDefs] (Implements an [http://en.wikipedia.org/wiki/Object-oriented_programming OOP] paradigm with [http://en.wikipedia.org/wiki/Inheritance_(computer_science) inheritance])

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FWeapons 'Spring Tutorial Game' WeaponDefs]

[[Category: Game Dev]]

Lua MoveCtrl

2014-03-20T21:06:02Z

Jools: /* MoveType-Controlling */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Spring.MoveCtrl.SetShotStop''' Currently a no-op
( number unitID, boolean shotstop ) -> nil

'''Spring.MoveCtrl.SetSlopeStop''' Currently a no-op
( number unitID, boolean slopestop ) -> nil

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

= MoveType-Controlling =

'''Spring.MoveCtrl.SetMoveDef'''
( number unitID, number moveDefID | string moveDefName ) -> boolean success

Note: string moveDefName needs to be in '''lowercase''', notwithstanding the fact that it may be in another case in the movedef table.

NOTE: all Set*MoveTypeData functions support the following number keys:
maxSpeed
maxWantedSpeed
repairBelowHealth


'''Spring.MoveCtrl.SetAirMoveTypeData''' {{new|0.81}}
( number unitID, string key, value ) -> nil
( number unitID, table values ) -> nil
supported keys:
numbers:
wantedHeight
myGravity
maxBank
maxPitch
turnRadius
maxAcc
maxAileron
maxElevator
maxRudder
booleans:
collide
useSmoothMesh
NOTE: not all keys and not all values may work correctly.
[[SetMoveTypeDataExample|Example usage]]

'''Spring.MoveCtrl.SetGroundMoveTypeData''' {{new|0.81}}
( number unitID, string key, value ) -> nil
( number unitID, table values ) -> nil
supported keys:
numbers:
baseTurnRate
turnRate
accRate
decRate
maxSpeed
maxReverseSpeed
requestedSpeed
requestedTurnRate
booleans:
floatOnWater
NOTE: not all keys and not all values may work correctly.
[[SetMoveTypeDataExample|Example usage]]

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

[[category: Lua]]

Lua MoveCtrl

2014-03-20T20:57:09Z

Jools: /* MoveType-Controlling */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Spring.MoveCtrl.SetShotStop''' Currently a no-op
( number unitID, boolean shotstop ) -> nil

'''Spring.MoveCtrl.SetSlopeStop''' Currently a no-op
( number unitID, boolean slopestop ) -> nil

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

= MoveType-Controlling =

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


'''Spring.MoveCtrl.SetAirMoveTypeData''' {{new|0.81}}
( number unitID, string key, value ) -> nil
( number unitID, table values ) -> nil
supported keys:
numbers:
wantedHeight
myGravity
maxBank
maxPitch
turnRadius
maxAcc
maxAileron
maxElevator
maxRudder
booleans:
collide
useSmoothMesh
NOTE: not all keys and not all values may work correctly.
[[SetMoveTypeDataExample|Example usage]]

'''Spring.MoveCtrl.SetGroundMoveTypeData''' {{new|0.81}}
( number unitID, string key, value ) -> nil
( number unitID, table values ) -> nil
supported keys:
numbers:
baseTurnRate
turnRate
accRate
decRate
maxSpeed
maxReverseSpeed
requestedSpeed
requestedTurnRate
booleans:
floatOnWater
NOTE: not all keys and not all values may work correctly.
[[SetMoveTypeDataExample|Example usage]]

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

[[category: Lua]]

Animation-CobCallins

2014-03-14T05:14:35Z

Jools: /* Movement */

==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.
*HitByWeaponID(damage, weaponid?, unitid?): Called when the unit is hit by a weapon.
*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]]

Animation-CobCallins

2014-03-13T01:23:46Z

Jools: /* Movement */

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

MoveRate0 ... Moverate3 only work with gunship type of aircraft:
[http://springrts.com/phpbb/viewtopic.php?f=14&t=26890&hilit=Moverate0 Forum thread]
--[[User:Jools|Jools]] ([[User talk:Jools|talk]]) 02:23, 13 March 2014 (CET)

===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.
*HitByWeaponID(damage, weaponid?, unitid?): Called when the unit is hit by a weapon.
*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]]

XTA

2014-02-22T14:09:48Z

Jools: /* Download */

[[category:Xta]]
'''[[Games|<--Back to Games]]'''

[[Image:Xta_logo_white.jpg]]

== What is XTA? ==

XTA is one of the original games for Spring, and the one many players feel is "more OTA than OTA itself" due to the authentic feel combined with the Spring Engine's capabilities.

XTA tests a player's tactical, teamwork and micro abilities whilst also fostering diverse playstyles giving many ways in which one action can change the outcome of battle.

'''But the best reciew for any player is to experience it for themselves.'''

== Download ==

The latest XTA can be found from http://packages.springrts.com/builds or from springfiles: search for XTA (at the time of writing this page, the current version is http://springfiles.com/spring/games/xta-35).

The XTA section on the official forum usually also contains the latest release: http://springrts.com/phpbb/viewforum.php?f=48

You can also download it by using [http://springrts.com/wiki/Download_Systems rapid system].
----

== Gameplay ==

Here are just some of the many good aspects XTA has to offer.

*Perhaps XTA's greatest strength is that players must keep the balance of keeping their own units alive through repairing and avoiding projectiles, while still doing maximum damage to the enemy. Amongst this they also have to keep their economy on track and try guess their opponent's next move. Sound easy? Give it to a go!

*XTA is more micro than macro, although the latter is a vital feature. Units have more health than other games enabling players to keep units alive. Spamming is done less as units are more expensive and too many units means you will lose your units to the a few well microed enemies. It's not how many you build but how you use them.

*At the advanced levels of the tech tree, both factions really come into their own. Whereas Core may get the power of flame, Arm get the power of lightning, offering the quick and light to the strong and slow. Will you go for brute force and economical superiority or hit and run stealth tactics?

*XTA prides itself on being a mod of team play allowing teams to play strategically and work together to achieve goals as a simple macro victory is rare. The small community makes players able to have a greater understanding of each other giving the game a more rewarding victory.

*One of XTA's best selling points is the '''Commander'''. The versatility of this unit allows it to be used for aggressive, tactical, defensive and economical purposes as well as having the ability to Morph to be stronger.

*Very much similar to Spring itself, XTA has a friendly community and although it being relatively small, balance discussions are often held within the group. However, this also allows all players to know each other making games more between friends than foes. It also has one of the most active clan systems.

*XTA has a tough learning curve, however an intelligent player will quickly learn when to build and what, may it be lab or unit. This makes XTA a mod constantly keeping the player entertained and challenged. With different tactics being discovered all the time users have many ideas to choose from of how to start their game. XTA is renowned for players making comebacks by rebuilding their base.

----

== So where can I find out more? ==

'''XTA is proud to be a community-run development program.'''

The XTA community is always willing to listen to suggestions. The current forum can be found [http://springrts.com/phpbb/viewforum.php?f=48 here]. From there you will be able to read on the latest plans of XTA here, read the change log, and contribute your own ideas on the mod itself.

Something not to your liking about the current XTA? Talk about, maybe have it changed! Many balance issues are discussed from the introduction of new units to the changing of a single unit's DP

You can join the '''#xta channel''' to find other XTA players and see if anyone wishes for a game. There is nearly always a game of the most uptodate XTA being hosted.

Newer versions will continue to be released to incorporate more detailed visual effects/or models as the Spring Engine develops.

If you wish to learn the basics of XTA, you can read guides such as:

*[http://springrts.com/wiki/New_to_xta XTA Basics]
*[http://springrts.com/wiki/Xta_units XTA unit guide]
*[http://springrts.com/wiki/Xta_commander XTA Commander guide]

For some commented XTA games please feel free to visit [http://www.youtube.com/user/xtareplay here] to get a feel of the game.

----

==History==

XTA was a balance mod for TA, developed by the [[SY]] clan.

For Spring, it was the first mod available to the public for online play, the first that was ported and for a long time came bundled with the installation of the Spring engine, ready to play.

The mod has gone through many developers, starting with the [SY] clan with the most ancient and famous to the oldest of players, SJ; and then moving onto other users.

One of the most notable players has been Noize, a founder of BA. Noize started XTA's modern look, with updated graphics and flash explosions (XTA Pimped Edition), which would later be seen as unnecessary and extremely laggy.

A short time afterwards the [KnoX] clan, the leading XTA clan ran by '''Myg''' and Gizmo starting to develop the mod. For a brief time a major debate became visible that XTA was KnoX's mod now, this would be shortly dismissed.

After [KnoX] disbanded due to them feeling the time was right for the members to go their separate ways, they still maintained XTA until Noruas began upkeep of the mod. With XTA 7.1 being seen as a watershed moment due to the peak of XTA's player base due to the decline of AA and rise of BA, so too can XTA 8.1. With some debate to whether the current XTA is the best, the two main contenders would be 7.1 and 8.1. With 8.1 came updated graphics and what many players remember as "The golden days" whereas 7.1 can be called the heyday of XTA itself.

Noruas has introduced more units than any other developer of XTA, improved graphics and dragged XTA through the new Spring versions. With the community split about where they stand on many of his somewhat radical ideas, Noruas has certainly added to XTA.

Noruas maintained XTA for some time. Players contribute and offer help on a multitude of scales. The current XTA balance offers something new and dynamic whilst still maintaining the roots of OTA and the older XTA versions giving a blend of classic and modern.

Recently Deadnight Warrior has taken over development, fixing bugs, optimizing scripts and tweaking balance. [http://code.google.com/p/xta-springrts/ A SVN with bugtracker] was also set up.

----

== Eye Candy ==

XTA is arguably the best-looking mod in terms of graphics. With new unit models and new explosion/smoke effects being released with every update, the XTA mod keeps up to date with the Spring Engine and what it has to offer.

Here are some pictures of what XTA has to offer:

[[image:Screen508.jpg|800px|Core Commander]]
[[image:Screen511.jpg|800px|Arm Commander]]
[[image:Screen620.jpg|800px|A Land boat]]

Alternatively, you can view some clips of XTA in action as well as commentaries of XTA replays [http://www.youtube.com//XtaReplay here] or [http://www.youtube.com/xtaboi here].

== Important Autohost Commands ==
=== For Helium===
Game end mode:
!setoptions mode=comends
or
!setoptions mode=killall

Make teams:
!balance 2
!balance 3
...
!balance 10

Turn XTAaids units on/off:
!setoptions xtaidunits=1
!setoptions xtaidunits=0

Back to [[Games]]

[[Category:Games]]

LuaCallinReturn

2014-01-17T11:55:31Z

Jools: /* Unit-Specific: */

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

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

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

==Commands, general-purpose:==

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

Shutdown() --> none.

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

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

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

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

KeyRelease() --> "key"

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

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

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

MouseWheel() --> "up, value"

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

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

AddConsoleLine() --> "msg, priority"

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

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

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

CommandsChanged() --> unknown (none?)

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

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

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

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

AllowFeatureBuildStep() --> unknown, please document.

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

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

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

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

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

==Unit-Specific:==

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

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

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

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

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

UnitExperience() --> "unitID, unitDefID, unitTeam, experience, oldExperience"

Spring.SetExperienceGrade must be called first to determine how often it is called

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

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

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

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

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam"

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam"

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

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

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

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

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

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

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

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

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

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"

Only called for unitDefIDs registered via [[Lua_System#Synced|Script.SetWatchUnit]] since 85.0

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

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

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

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

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

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

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

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID)

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

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

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

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

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

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

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

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

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

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

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

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

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

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

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

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

* DrawWorldPreUnit() --> none.

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

* DrawWorld() --> none.

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

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

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

DrawFeature(featureID, DrawMode) 

DrawShield(unitID, weaponID, DrawMode) 

DrawProjectile(projectileID, DrawMode) 

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

DrawScreen() --> none.

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

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

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

Only available to LuaIntro, draws custom load screens.

==Game Events:==

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

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

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

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

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

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

GamePreload() --> none.

GameStart() --> none.

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

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

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

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

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

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

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

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

GamePaused() --> "playerID, paused"

PlayerAdded() --> "playerID"

PlayerRemoved() --> "playerID, reason"

==Projectiles:==

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

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

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

[[Category:Lua]]

Bugs

2013-12-05T14:04:54Z

Jools: /* As a developer who found a bug */

== See if the bug and a solution are already known ==
You can do so in the [[FAQ]]

You can also have a look at recent and stickied threads in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum]

== How to report bugs==
To report a bug, please give a description, what is going wrong and '''how it can be reproduced'''. what steps are required to reproduce it? If required to reproduce the bug add a script or/and a link to the Game/Map.

==Logfiles, screenshots, replays==
* Always attach [[infolog.txt]], as it contains system/driver/version info and if spring crashed. Click the link to see what it is and how to share it.

* Attach a replay: often Bugs can't be reproduced, its often better to see something than to only read about that.

* Screenshots are taken with the F12 key and saved in the \screenshots\ folder. You can attach them to postings or upload on site such as: [http://www.imgur.com imgur.com] , [http://www.abload.de abload.de]

* If a dev asks you for more information, please answer his questions.

* Try to avoid endless discussions why a bug was introduced, be polite!

* If you want more tips for a good bug-report, please read "[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively]"

'''The better the bug-report, the better the chances, that it will be fixed!'''

== Where to report bugs==
===As a player who needs help===
Do not be afraid to ask for help [http://springrts.com/phpbb/viewforum.php?f=11 in the forum.] Read the guidelines above so people can help you as good as possible.

===As a developer who found a bug===
If you found a bug in the Spring Engine, please report it to the [http://springrts.com/mantis bug tracker]. However, reporters are advised that this official bug report site has become increasingly unfriendly. Therefore, people are discouraged from reporting an excessive amount of issues there. A good cap on reports is about one monthly issue, unless you have questions that can be answered with yes/no, in which case engine developers can bear up to 5 (five) monthly issues. If you have issues which developers may consider stupid, it is better to refrain from reporting these in any official way.

Before [http://springrts.com/mantis/bug_report_page.php filling a bug], please look if someone else [http://springrts.com/mantis/view_all_bug_page.php already has reported] this issue.

[[Category:Engine Dev]]

Bugs

2013-12-05T14:03:49Z

Jools: /* As a developer who found a bug */

== See if the bug and a solution are already known ==
You can do so in the [[FAQ]]

You can also have a look at recent and stickied threads in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum]

== How to report bugs==
To report a bug, please give a description, what is going wrong and '''how it can be reproduced'''. what steps are required to reproduce it? If required to reproduce the bug add a script or/and a link to the Game/Map.

==Logfiles, screenshots, replays==
* Always attach [[infolog.txt]], as it contains system/driver/version info and if spring crashed. Click the link to see what it is and how to share it.

* Attach a replay: often Bugs can't be reproduced, its often better to see something than to only read about that.

* Screenshots are taken with the F12 key and saved in the \screenshots\ folder. You can attach them to postings or upload on site such as: [http://www.imgur.com imgur.com] , [http://www.abload.de abload.de]

* If a dev asks you for more information, please answer his questions.

* Try to avoid endless discussions why a bug was introduced, be polite!

* If you want more tips for a good bug-report, please read "[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively]"

'''The better the bug-report, the better the chances, that it will be fixed!'''

== Where to report bugs==
===As a player who needs help===
Do not be afraid to ask for help [http://springrts.com/phpbb/viewforum.php?f=11 in the forum.] Read the guidelines above so people can help you as good as possible.

===As a developer who found a bug===
If you found a bug in the Spring Engine, please report it to the [http://springrts.com/mantis bug tracker]. However, reporters are advised that this official bug report site has become increasingly unfriendly. Therefore, people are discouraged from reporting an excessive amount of issues there. A good cap on reports is about one monthly issue, unless you have questions that can be answered with yes/no, in which case engine developers can bear up to 5 (five) monthly issues.

Before [http://springrts.com/mantis/bug_report_page.php filling a bug], please look if someone else [http://springrts.com/mantis/view_all_bug_page.php already has reported] this issue.

[[Category:Engine Dev]]

Bugs

2013-12-05T14:03:11Z

Jools: /* As a developer who found a bug */

== See if the bug and a solution are already known ==
You can do so in the [[FAQ]]

You can also have a look at recent and stickied threads in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum]

== How to report bugs==
To report a bug, please give a description, what is going wrong and '''how it can be reproduced'''. what steps are required to reproduce it? If required to reproduce the bug add a script or/and a link to the Game/Map.

==Logfiles, screenshots, replays==
* Always attach [[infolog.txt]], as it contains system/driver/version info and if spring crashed. Click the link to see what it is and how to share it.

* Attach a replay: often Bugs can't be reproduced, its often better to see something than to only read about that.

* Screenshots are taken with the F12 key and saved in the \screenshots\ folder. You can attach them to postings or upload on site such as: [http://www.imgur.com imgur.com] , [http://www.abload.de abload.de]

* If a dev asks you for more information, please answer his questions.

* Try to avoid endless discussions why a bug was introduced, be polite!

* If you want more tips for a good bug-report, please read "[http://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively]"

'''The better the bug-report, the better the chances, that it will be fixed!'''

== Where to report bugs==
===As a player who needs help===
Do not be afraid to ask for help [http://springrts.com/phpbb/viewforum.php?f=11 in the forum.] Read the guidelines above so people can help you as good as possible.

===As a developer who found a bug===
If you found a bug in the Spring Engine, please report it to the [http://springrts.com/mantis bug tracker]. However, reporters are advised that this official bug report site has become increasingly unfriendly. Therefore, people are discouraged from report an excessive amount of issues there. A good cap on reports are about one monthly issue, unless you have questions that can be answered with yes/no, in which case engine developers can bear up to 5 (five) monthly issues.

Before [http://springrts.com/mantis/bug_report_page.php filling a bug], please look if someone else [http://springrts.com/mantis/view_all_bug_page.php already has reported] this issue.

[[Category:Engine Dev]]

LuaCallinReturn

2013-11-14T21:34:31Z

Jools: /* Unit-Specific: */

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

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

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

==Commands, general-purpose:==

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

Shutdown() --> none.

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

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

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

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

KeyRelease() --> "key"

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

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

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

MouseWheel() --> "up, value"

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

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

AddConsoleLine() --> "msg, priority"

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

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

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

CommandsChanged() --> unknown (none?)

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

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

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

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

AllowFeatureBuildStep() --> unknown, please document.

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

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

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

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

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

==Unit-Specific:==

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

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

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

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

UnitExperience() --> "unitID, unitDefID, unitTeam, experience, oldExperience"

Spring.SetExperienceGrade must be called first to determine how often it is called

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

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

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

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

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam"

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam"

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

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

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

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

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

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

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

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

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

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"

Only called for unitDefIDs registered via [[Lua_System#Synced|Script.SetWatchUnit]] since 85.0

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

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

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

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

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

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

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

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID)

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

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

Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0

DrawShield(number unitID, number weaponID) --> boolean

''true'' (<-?) skips Spring's own drawing of shield <weaponID> owned by unit <unitID>

[https://github.com/spring/spring/commit/7bbfd9464d4f74c12163ea0740c8c60d1ba978f1 maybe new in 86.0+]

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag, cmdParams, cmdOptions" cmdParams and cmdOptions are only available from version 95.0

UnitFeatureCollision(colliderID, collideeID, crushKilled) -- needs SetWatchUnit for first and SetWatchFeature for second party

95+FeatureDamaged() --> "featureID, featureDefID, featureTeam, damage [, weaponDefID, projectileID [, attackerID, attackerDefID, attackerTeam ]]"

95+FeaturePreDamaged() --> "featureID, featureDefID, featureTeam, damage [, weaponDefID, projectileID [, attackerID, attackerDefID, attackerTeam ]]"

==Drawing:==
Inside these functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

* DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

* DrawWorldPreUnit() --> none.

Spring draws units, features, some water types, cloaked units, and the sun.

* DrawWorld() --> none.

Spring draws command queues, 'map stuff', and map marks.

Each unit might also have a DrawUnit call, [[Lua_UnitRendering|enabled here.]]

DrawUnit(unitID,DrawMode) 
With enum DrawMode { 
notDrawing = 0, 
normalDraw = 1, 
shadowDraw = 2, 
reflectionDraw = 3, 
refractionDraw = 4 
};

DrawFeature(featureID, DrawMode) 

DrawShield(unitID, weaponID, DrawMode) 

DrawProjectile(projectileID, DrawMode) 

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

==Game Events:==

GameID() --> "gameID" {{new|89.0}}

Explosion() --> "weaponID, px, py, pz, ownerID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon
 return true to hide the weapon's CEG

ShockFront() --> "power, dx, dy, dz" Not yet implemented!

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail. Not yet implemented!

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) Not yet implemented!

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() --> "cx, cy, cz, playerID, readyState, rx, ry, rz", where rx,ry,rz are the position the player picked and cx,cy,cz are that position clamped to the startbox. readyState can be any one of 0 -- player picked a position, 1 -- player clicked ready, 2 -- game was force-started (player did not click ready)
 return true/false to allow/deny placing startposition marker

GameSetup() --> string "state", boolean "ready", table "playerStates"
 return success, newReady

GamePaused() --> "playerID, paused"

PlayerAdded() --> "playerID"

PlayerRemoved() --> "playerID, reason"

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID, weaponDefID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

ProjectileDestroyed() --> "proID"
 Only called for weaponDefIDs registered via Script.SetWatchWeapon

AllowWeaponInterceptTarget --> "number interceptorUnitID, number interceptorWeaponID, number targetProjectileID"
returns boolean

[[Category:Lua]]

LuaCallinReturn

2013-06-15T00:39:07Z

Jools: /* Commands, general-purpose: */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

==Engine Source==
If you can understand Lua code well and wish to get the most up to date info, you can refer to:
{{sourcelink|file=cont/base/springcontent/LuaGadgets/actions.lua}},
{{sourcelink|file=cont/LuaUI/widgets.lua}} and 
{{sourcelink|file=cont/base/springcontent/LuaGadgets/gadgets.lua}} 
to see how widget/gadget call-ins are distributed, find call-in and widgetHandler function definitions, see how they are processed and what values should be returned from some call ins
(are these the only files?)

==What is a callin anyway?==
Call-ins are calls from the engine, into the gadget or widget script. In other words, these functions are called when a particular â€œeventâ€ happens.
Some call-in functions can return values to the engine.
===Blocking events with return values===
The call-in functions named '''''Allow'''''XXX can block their event by returning ''false''. 
For example ''AllowUnitTransfer()'' 
<code>return true</code> = allow transfer 
<code>return false</code> = deny transfer

==Commands, general-purpose:==

Initialize() --> none.
called when widget/gadget gets (re-)loaded.

Shutdown() --> none.

PlayerChanged --> (playerID).
gadget/widget: Use this to check whether a player has become spectator for instance.

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

CommandNotify() --> "id, params, options", where id = the CommandID

KeyPress() --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

KeyRelease() --> "key"

MouseMove() --> "x, y, dx, dy, button"

MousePress() --> "x, y, button" 
button parameter values: left - 1, middle - 2, right - 3

MouseRelease() --> "x, y, button" 
Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same widget that returns true.

MouseWheel() --> "up, value"

IsAbove() --> "x, y" where x,y = screen coordinates.

GetTooltip() --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

AddConsoleLine() --> "msg, priority"

MapDrawCmd() --> "playerID, cmdType, px, py, pz, labeltext"

AllowCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

CommandFallback() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

CommandsChanged() --> unknown (none?)

AllowUnitCreation() --> "unitDefID, builderID, builderTeam, x, y, z, facing"

AllowUnitTransfer() --> "unitID, unitDefID, oldTeam, newTeam, capture"

AllowUnitBuildStep() --> "builderID, builderTeam, unitID, unitDefID, part"

AllowFeatureCreation() --> "featureDefID, teamID, x, y, z"

AllowFeatureBuildStep() --> unknown, please document.

AllowResourceLevel() --> "teamID, res, level"

AllowResourceTransfer() --> "teamID, res, level"

Update() --> "dt" 
gets called very often, even if the game is paused. dt is the time since the function was last called (???)

DefaultCommand() --> "type,id" 
can return an [[Lua_CMDs|CMD]] to change cursor and command. {{forumlink|topic=26438|title=example usage}}

AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID) -> allowFpsControl 
''return true'' allows fps mode, ''return false'' blocks it.

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, attackerID, attackerDefID, attackerTeam" (prior to 94.0)

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam" (as of 94.0)

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, attackerID, attackerDefID, attackerTeam" 
Can overwrite the taken damage by returning a new number value. 

As of 88.0 for both UnitDamaged and UnitPreDamaged:
weaponDefID -1 --> debris collision
weaponDefID -2 --> ground collision
weaponDefID -3 --> object collision
weaponDefID -4 --> fire damage
weaponDefID -5 --> water damage
weaponDefID -6 --> kill damage

UnitExperience() --> "unitID, unitDefID, unitTeam, experience, oldExperience"

Spring.SetExperienceGrade must be called first to determine how often it is called

UnitCreated() --> "unitID, unitDefID, teamID, builderID"

UnitFinished() --> "unitID, unitDefID, teamID"

UnitFromFactory() --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

UnitDestroyed() --> "unitID, unitDefID, teamID, attackerID, attackerDefID, attackerTeamID"

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam"

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam"

UnitIdle() --> "unitID, unitDefID, teamID"

UnitCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams"

UnitSeismicPing() --> "x, y, z, strength"

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

UnitLeftLos() --> "unitID, unitDefID, teamID"

UnitLoaded() --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

UnitUnloaded() --> "unitID, unitDefID, teamID, transportID"

UnitCloaked() --> "unitID, unitDefID, teamID"

UnitDecloaked)--> "unitID, unitDefID, teamID"

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"

Only called for unitDefIDs registered via [[Lua_System#Synced|Script.SetWatchUnit]] since 85.0

StockpileChanged() --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

UnitEnteredWater() --> "unitID, unitDefID, teamID"

UnitEnteredAir() --> "unitID, unitDefID, teamID"

UnitLeftWater() --> "unitID, unitDefID, teamID"

UnitLeftAir() --> "unitID, unitDefID, teamID"

ShieldPreDamaged() --> "proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile"

UnitUnitCollision(colliderID, collideeID) -- needs SetWatchUnit enabled for both parties

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID)
{{new|83.0}}

Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0

AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID, defaultPriority)
--> <code>return "targetAllowed, targetPriority"</code>
{{new|83.0}}, defaultPriority new in 89.0 

Only called for weaponDefIDs registered via [[Lua_System#Synced|Script.SetWatchWeapon]] since 92.0

DrawShield(number unitID, number weaponID) --> boolean

''true'' (<-?) skips Spring's own drawing of shield <weaponID> owned by unit <unitID>

[https://github.com/spring/spring/commit/7bbfd9464d4f74c12163ea0740c8c60d1ba978f1 maybe new in 86.0+]

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag"

UnitFeatureCollision(colliderID, collideeID, crushKilled) -- needs SetWatchUnit for first and SetWatchFeature for second party

==Drawing:==
Inside these functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

* DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

* DrawWorldPreUnit() --> none.

Spring draws units, features, some water types, cloaked units, and the sun.

* DrawWorld() --> none.

Spring draws command queues, 'map stuff', and map marks.

Each unit might also have a DrawUnit call, [[Lua_UnitRendering|enabled here.]]

DrawUnit(unitID,DrawMode) 
With enum DrawMode { 
notDrawing = 0, 
normalDraw = 1, 
shadowDraw = 2, 
reflectionDraw = 3, 
refractionDraw = 4 
};

DrawFeature(featureID, DrawMode) 

DrawShield(unitID, weaponID, DrawMode) 

DrawProjectile(projectileID, DrawMode) 

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

==Game Events:==

GameID() --> "gameID" {{new|89.0}}

Explosion() --> "weaponID, px, py, pz, ownerID"

ShockFront() --> "power, dx, dy, dz"

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail.

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) New in 0.83.x

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() --> x,y,z, playerID

return true/false to allow/deny placing startposition marker

GameSetup()
 --> string "state", boolean "ready", table "playerStates"

return success, newReady

GamePaused() --> "playerID, paused" {{new|83.0}}

PlayerAdded() --> "playerID" {{new|83.0}}

PlayerRemoved() --> "playerID, reason" {{new|83.0}}

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID, weaponDefID"
Only called for weapons with SetWatchWeapon enabled

ProjectileDestroyed() --> "proID"
Only called for weapons with SetWatchWeapon enabled

[[Category:Lua]]

LuaCallinReturn

2012-03-15T21:54:55Z

Jools: /* Game Events: */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

==Engine Source==
If you can understand Lua code well and wish to get the most up to date info, you can refer to:
{{sourcelink|file=cont/base/springcontent/LuaGadgets/actions.lua}},
{{sourcelink|file=cont/LuaUI/widgets.lua}} and 
{{sourcelink|file=cont/base/springcontent/LuaGadgets/gadgets.lua}} 
to see how widget/gadget call-ins are distributed, find call-in and widgetHandler function definitions, see how they are processed and what values should be returned from some call ins
(are these the only files?)

==What is a callin anyway?==
Call-ins are calls from the engine, into the gadget or widget script. In other words, these functions are called when a particular â€œeventâ€ happens.
Some call-in functions can return values to the engine.
===Blocking events with return values===
The call-in functions named '''''Allow'''''XXX can block their event by returning ''false''. 
For example ''AllowUnitTransfer()'' 
<code>return true</code> = allow transfer 
<code>return false</code> = deny transfer

==Commands, general-purpose:==

Initialize() --> none.
called when widget/gadget gets (re-)loaded.

Shutdown() --> none.

PlayerChanged --> (playerID).
gadget/widget: Use this to check whether a player has become spectator for instance.

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

CommandNotify() --> "id, params, options", where id = the CommandID

KeyPress() --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

KeyRelease() --> "key"

MouseMove() --> "x, y, dx, dy, button"

MousePress() --> "x, y, button" 
button parameter values: left - 1, middle - 2, right - 3

MouseRelease() --> "x, y, button" 
Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same widget that returns true.

MouseWheel() --> "up, value"

IsAbove() --> "x, y" where x,y = screen coordinates.

GetTooltip() --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

AddConsoleLine() --> "msg, priority"

MapDrawCmd() --> "playerID, cmdType, px, py, pz, labeltext"

AllowCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

CommandFallback() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

CommandsChanged() --> unknown (none?)

AllowUnitCreation() --> "unitDefID, builderID, builderTeam, x, y, z"

AllowUnitTransfer() --> "unitID, unitDefID, oldTeam, newTeam, capture"

AllowUnitBuildStep() --> "builderID, builderTeam, unitID, unitDefID, part"

AllowFeatureCreation() --> "featureDefID, teamID, x, y, z"

AllowFeatureBuildStep() --> unknown, please document.

AllowResourceLevel() --> "teamID, res, level"

AllowResourceTransfer() --> "teamID, res, level"

Update() --> "dt" 
gets called very often, even if the game is paused. dt is the time since the function was last called (???)

DefaultCommand() --> nothing (???) 
can return an [[Lua_CMDs|CMD]] to change cursor and command. {{forumlink|topic=26438|title=example usage}}

AllowDirectUnitControl(unitID, unitDefID, unitTeam, playerID) -> allowFpsControl 
''return true'' allows fps mode, ''return false'' blocks it.

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam"

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam" 
can overwrite the taken damage by returning a new number value. 
[https://github.com/spring/spring/commit/a75743e42806f94d73c6e98420e30165998873a4 weaponID<0 indicates damage taken by non-weapon ways] (85.0+)

UnitCreated() --> "unitID, unitDefID, teamID, builderID"

UnitFinished() --> "unitID, unitDefID, teamID"

UnitFromFactory() --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

UnitDestroyed() --> "unitID, unitDefID, teamID, attackerID, attackerDefID, attackerTeamID"

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam"

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam"

UnitIdle() --> "unitID, unitDefID, teamID"

UnitCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams"

UnitSeismicPing() --> "x, y, z, strength"

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

UnitLeftLos() --> "unitID, unitDefID, teamID"

UnitLoaded() --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

UnitUnloaded() --> "unitID, unitDefID, teamID, transportID"

UnitCloaked() --> "unitID, unitDefID, teamID"

UnitDecloaked)--> "unitID, unitDefID, teamID"

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"

Only called for unitDefIDs registered via [[Lua_System#Synced|Script.SetWatchUnit]] since 85.0

StockpileChanged() --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

UnitEnteredWater() --> "unitID, unitDefID, teamID"

UnitEnteredAir() --> "unitID, unitDefID, teamID"

UnitLeftWater() --> "unitID, unitDefID, teamID"

UnitLeftAir() --> "unitID, unitDefID, teamID"

ShieldPreDamaged() --> "proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile"

UnitUnitCollision(colliderID, collideeID) -- needs SetWatchUnit enabled for both parties

AllowWeaponTargetCheck(attackerID, attackerWeaponNum, attackerWeaponDefID) New in 0.83.x

AllowWeaponTarget(attackerID, targetID, attackerWeaponNum, attackerWeaponDefID) New in 0.83.x 
--> <code>return "targetAllowed, targetPriority"</code>

DrawShield(number unitID, number weaponID) --> boolean

''true'' (<-?) skips Spring's own drawing of shield <weaponID> owned by unit <unitID>

[https://github.com/spring/spring/commit/7bbfd9464d4f74c12163ea0740c8c60d1ba978f1 maybe new in 86.0+]

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag"

UnitFeatureCollision(colliderID, collideeID, crushKilled) -- needs SetWatchUnit for first and SetWatchFeature for second party

==Drawing:==
Inside these functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

* DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

* DrawWorldPreUnit() --> none.

Spring draws units, features, some water types, cloaked units, and the sun.

* DrawWorld() --> none.

Spring draws command queues, 'map stuff', and map marks.

Each unit might also have a DrawUnit call, [[Lua_UnitRendering|enabled here.]]

DrawUnit(unitID,DrawMode) 
With enum DrawMode { 
notDrawing = 0, 
normalDraw = 1, 
shadowDraw = 2, 
reflectionDraw = 3, 
refractionDraw = 4 
};

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

==Game Events:==

Explosion() --> "weaponID, px, py, pz, ownerID"

ShockFront() --> "power, dx, dy, dz"

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail.

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) New in 0.83.x

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() --> playerID, x,y,z

return true/false to allow/deny placing startposition marker

GameSetup()
 --> string "state", boolean "ready", table "playerStates"

return success, newReady

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID"

ProjectileDestroyed() --> "proID"

==Details needed!==
from https://github.com/spring/spring/blob/84.0/doc/changelog.txt

- added widget call-in GamePaused ->parameters: none?
- added widget call-in PlayerAdded ->parameters: probally playerID, teamID?
- added widget call-in PlayerRemoved ->parameters: probally playerID, teamID?

[[category: Lua]]

LuaCallinReturn

2011-08-10T21:07:53Z

Jools: /* Commands, general-purpose: */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

==Engine Source==
{{sourcelink|file=cont/base/springcontent/LuaGadgets/actions.lua}} (is that the only file????)

==What is a callin anyway?==
Call-ins are calls from the engine, into the gadget or widget script. In other words, these functions are called when a particular â€œeventâ€ happens.
Some call-in functions can return values to the engine.
===Blocking events with return values===
The call-in functions named '''''Allow'''''XXX can block their event by returning ''false''. 
For example ''AllowUnitTransfer()'' 
<code>return true</code> = allow transfer 
<code>return false</code> = deny transfer

==Commands, general-purpose:==

Initialize() --> none.
called when widget/gadget gets (re-)loaded.

Shutdown() --> none.

PlayerChanged --> (playerID).
gadget/widget: Use this to check whether a player has become spectator for instance.

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

CommandNotify() --> "id, params, options", where id = the CommandID

KeyPress() --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

KeyRelease() --> "key"

MouseMove() --> "x, y, dx, dy, button"

MousePress() --> "x, y, button" 
button parameter values: left - 1, middle - 2, right - 3

MouseRelease() --> "x, y, button" 
Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same widget that returns true.

MouseWheel() --> "up, value"

IsAbove() --> "x, y" where x,y = screen coordinates.

GetTooltip() --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

AddConsoleLine() --> "msg, priority"

MapDrawCmd() --> "playerID, cmdType, px, py, pz, labeltext"

AllowCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

CommandFallback() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

CommandsChanged() --> unknown (none?)

AllowUnitCreation() --> "unitDefID, builderID, builderTeam, x, y, z"

AllowUnitTransfer() --> "unitID, unitDefID, oldTeam, newTeam, capture"

AllowUnitBuildStep() --> "builderID, builderTeam, unitID, unitDefID, part"

AllowFeatureCreation() --> "featureDefID, teamID, x, y, z"

AllowFeatureBuildStep() --> unknown, please document.

AllowResourceLevel() --> "teamID, res, level"

AllowResourceTransfer() --> "teamID, res, level"

Update() --> "dt" 
gets called very often, even if the game is paused. dt is the time since the function was last called (???)

DefaultCommand() --> nothing (???) 
can return an [[Lua_CMDs|CMD]] to change cursor and command. {{forumlink|topic=26438|title=example usage}}

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam"

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam" 
can overwrite the taken damage by returning a new number value

UnitCreated() --> "unitID, unitDefID, teamID, builderID"

UnitFinished() --> "unitID, unitDefID, teamID"

UnitFromFactory() --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

UnitDestroyed() --> "unitID, unitDefID, teamID, attackerID?"

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam"

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam"

UnitIdle() --> "unitID, unitDefID, teamID"

UnitCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams"

UnitSeismicPing() --> "x, y, z, strength"

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

UnitLeftLos() --> "unitID, unitDefID, teamID"

UnitLoaded() --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

UnitUnloaded() --> "unitID, unitDefID, teamID, transportID"

UnitCloaked() --> "unitID, unitDefID, teamID"

UnitDecloaked)--> "unitID, unitDefID, teamID"

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"

StockpileChanged() --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

UnitEnteredWater() --> "unitID, unitDefID, teamID"

UnitEnteredAir() --> "unitID, unitDefID, teamID"

UnitLeftWater() --> "unitID, unitDefID, teamID"

UnitLeftAir() --> "unitID, unitDefID, teamID"

ShieldPreDamaged() --> "proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile"

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag"

==Drawing:==
Inside these functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

* DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

* DrawWorldPreUnit() --> none.

Spring draws units, features, some water types, cloaked units, and the sun.

* DrawWorld() --> none.

Spring draws command queues, 'map stuff', and map marks.

Each unit might also have a DrawUnit call, [[Lua_UnitRendering|enabled here.]]

DrawUnit(unitID,DrawMode) 
With enum DrawMode { 
notDrawing = 0, 
normalDraw = 1, 
shadowDraw = 2, 
reflectionDraw = 3, 
refractionDraw = 4 
};

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

==Game Events:==

Explosion() --> "weaponID, px, py, pz, ownerID"

ShockFront() --> "power, dx, dy, dz"

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail.

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) New in 0.83.x

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() --> nobody cares 
returns nobody cares

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID"

ProjectileDestroyed() --> "proID"

[[category: Lua]]

LuaCallinReturn

2011-08-10T21:07:00Z

Jools: /* Commands, general-purpose: */

[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}

==Engine Source==
{{sourcelink|file=cont/base/springcontent/LuaGadgets/actions.lua}} (is that the only file????)

==What is a callin anyway?==
Call-ins are calls from the engine, into the gadget or widget script. In other words, these functions are called when a particular â€œeventâ€ happens.
Some call-in functions can return values to the engine.
===Blocking events with return values===
The call-in functions named '''''Allow'''''XXX can block their event by returning ''false''. 
For example ''AllowUnitTransfer()'' 
<code>return true</code> = allow transfer 
<code>return false</code> = deny transfer

==Commands, general-purpose:==

Initialize() --> none.
called when widget/gadget gets (re-)loaded.

Shutdown() --> none.

gadget/widget:PlayerChanged --> (playerID).

Use this to check whether a player has become spectator for instance.

LayoutButtons() --> unknown, please document.

ConfigureLayout() --> "command".

CommandNotify() --> "id, params, options", where id = the CommandID

KeyPress() --> "key, mods, isRepeat", where key = keymap, mods = SHIFT, etc.

KeyRelease() --> "key"

MouseMove() --> "x, y, dx, dy, button"

MousePress() --> "x, y, button" 
button parameter values: left - 1, middle - 2, right - 3

MouseRelease() --> "x, y, button" 
Please note that in order to have Spring call MouseRelease, you need to have a MousePress call-in in the same widget that returns true.

MouseWheel() --> "up, value"

IsAbove() --> "x, y" where x,y = screen coordinates.

GetTooltip() --> "x, y" where x,y = screen coordinates. Returns WorldTooltip.

AddConsoleLine() --> "msg, priority"

MapDrawCmd() --> "playerID, cmdType, px, py, pz, labeltext"

AllowCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag, synced"

CommandFallback() --> "unitID, unitDefID, unitTeam, cmdID, cmdParams, cmdOptions, cmdTag"

CommandsChanged() --> unknown (none?)

AllowUnitCreation() --> "unitDefID, builderID, builderTeam, x, y, z"

AllowUnitTransfer() --> "unitID, unitDefID, oldTeam, newTeam, capture"

AllowUnitBuildStep() --> "builderID, builderTeam, unitID, unitDefID, part"

AllowFeatureCreation() --> "featureDefID, teamID, x, y, z"

AllowFeatureBuildStep() --> unknown, please document.

AllowResourceLevel() --> "teamID, res, level"

AllowResourceTransfer() --> "teamID, res, level"

Update() --> "dt" 
gets called very often, even if the game is paused. dt is the time since the function was last called (???)

DefaultCommand() --> nothing (???) 
can return an [[Lua_CMDs|CMD]] to change cursor and command. {{forumlink|topic=26438|title=example usage}}

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam"

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam" 
can overwrite the taken damage by returning a new number value

UnitCreated() --> "unitID, unitDefID, teamID, builderID"

UnitFinished() --> "unitID, unitDefID, teamID"

UnitFromFactory() --> "unitID, unitDefID, unitTeam, factID, factDefID, userOrders"

UnitDestroyed() --> "unitID, unitDefID, teamID, attackerID?"

UnitTaken() --> "unitID, unitDefID, unitTeam, newTeam"

UnitGiven() --> "unitID, unitDefID, unitTeam, oldTeam"

UnitIdle() --> "unitID, unitDefID, teamID"

UnitCommand() --> "unitID, unitDefID, unitTeam, cmdID, cmdOpts, cmdParams"

UnitSeismicPing() --> "x, y, z, strength"

UnitEnteredRadar() --> "unitID, unitTeam"

UnitEnteredLos() --> "unitID, teamID"

UnitLeftRadar() --> "unitID, unitTeam"

UnitLeftLos() --> "unitID, unitDefID, teamID"

UnitLoaded() --> "unitID, unitDefID, unitTeam, transportID, transportTeam"

UnitUnloaded() --> "unitID, unitDefID, teamID, transportID"

UnitCloaked() --> "unitID, unitDefID, teamID"

UnitDecloaked)--> "unitID, unitDefID, teamID"

UnitMoveFailed() --> "unitID, unitDefID, unitTeam"

StockpileChanged() --> "unitID, unitDefID, unitTeam, weaponNum, oldCount, newCount"

UnitEnteredWater() --> "unitID, unitDefID, teamID"

UnitEnteredAir() --> "unitID, unitDefID, teamID"

UnitLeftWater() --> "unitID, unitDefID, teamID"

UnitLeftAir() --> "unitID, unitDefID, teamID"

ShieldPreDamaged() --> "proID, proOwnerID, shieldEmitterWeaponNum, shieldCarrierUnitID, bounceProjectile"

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

TerraformComplete() --> "unitID, unitDefID, unitTeam, buildUnitID, buildUnitDefID, buildUnitTeam"

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag"

==Drawing:==
Inside these functions, you can use the [[Lua_OpenGL_Api | Lua OpenGL Api]] to draw graphics.

* DrawGenesis() --> none. Don't render here.

Spring draws the sky, the map, some water types, and unit selection.

* DrawWorldPreUnit() --> none.

Spring draws units, features, some water types, cloaked units, and the sun.

* DrawWorld() --> none.

Spring draws command queues, 'map stuff', and map marks.

Each unit might also have a DrawUnit call, [[Lua_UnitRendering|enabled here.]]

DrawUnit(unitID,DrawMode) 
With enum DrawMode { 
notDrawing = 0, 
normalDraw = 1, 
shadowDraw = 2, 
reflectionDraw = 3, 
refractionDraw = 4 
};

DrawScreenEffects() --> "vsx, vsy" where vsx, vsy are screen coords.

DrawScreen() --> none.

DrawInMiniMap() --> "sx, sy" where sx,sy are values relative to the minimap's position and scale.

DrawWorldShadow() --> none.

DrawWorldReflection() --> none.

DrawWorldRefraction() --> none.

==Game Events:==

Explosion() --> "weaponID, px, py, pz, ownerID"

ShockFront() --> "power, dx, dy, dz"

GameFrame() --> "frameNum"

CobCallback() --> unknown, marked FIXME.

GroupChanged() --> "groupID" where groupID is the value of Group whose table value changed.

WorldTooltip() --> "ttType, data1, data2, data3" special, should be documented in detail.

GamePreload() --> none.

GameStart() --> none.

GameProgress() --> "serverFrameNum" ( called every 60 frames, calculating delta between GameFrame and GameProgress can give an ETA about catching up with simulation ) New in 0.83.x

GameOver() --> "[ [1] = allyTeamID1, [2] = allyTeamID2, ... ]", a list of winning allyteams, if empty the game result was undecided ( like when dropping from an host ) Will return nil in pre 0.83.x

TeamDied() --> "TeamID" where TeamID = the team that has been eliminated.

AllowStartPosition() --> nobody cares 
returns nobody cares

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID"

ProjectileDestroyed() --> "proID"

[[category: Lua]]

Ota2xta

2010-03-01T18:41:45Z

Jools:

This is a reference for OTA players that play XTA mod for the first time.

But does work as well for new and regulars from other mods.

= The Energy build tree =

[[Image:ArmenergyBpath.jpg|thumb|300px|* Arm energy buildtree ]]

[[Image:Coreenergybpath.jpg|thumb|300px|* Core energy buildtree ]]
In few words, for OTA players, '''do not build the Fusion Power Plant''', use the ''Mini Fusions'' -> ''Cloakable Fusions'' building path instead.

The Energy tree for XTA, differs from OTA in several aspects.

In short, several buildings and Mobile units have been added "in between" the basic Energy sources like Solar Collectors/Wind Generators, and the more advanced Fusion power plant.

== Energy producing buildings and Mobile units ==

=== The basic Energy structures ===

Are the same, windmill, and solar collector.

However there are some differences:

==== The solar collector ====

Main changes from OTA:

- DOES NOT REQUIRE ENERGY to be built.

'''Advantages:'''

- Is heavily armoured.

- Produces a continuous Energy output.

'''Downside:'''

- Its rather expensive in Metal compared to Wind Generators.

- Blocks fire from light laser tower.

'''Tips'''

- Offers a quick solution for Energy stall at mid Metal cost (145 Metal).

- Acts as a barricade/defence.

==== Energy storage ====

The cost has been increased, but the storage capacity is now around 32k.

This makes for a better Energy and Metal resource management, without the hassle of having to build lots and lots of storage.

'''Tips'''

- Combine with windmill farms in windy maps for better results.

- In early game, if you are using Metal makers, it generates non continuous Metal output, so do not build one if you are using Metal maker economy. '''Unless you have some sort of Metal maker ai.'''

Those are the main changes for the level one energy structures.

=== Advanced Energy structures ===

At Level Two, XTA introduces the major changes and advantages compared to OTA.

To start with, there is a "midway" Fusion Energy plant.

'''The Mini Fusions'''

Each side has its own. This units cover the gap between basic Energy sources and the more advanced ones, having around 38%-44% of the Energy output of the next step in the Energy build tree, and offering 19x-22x times the output of a single solar.

==== Core Mini Fusion ====

Produces +300 Energy and are built by Level Two builders.

Advantages:

- Is built by any Level Two construction unit.

- Produces 300 Energy.

Downside:

- It uses more space, for less Energy output compared to bigger Fusions.

Tips

- You can calculate 1 Mini Fusion per MohoMetalExtractor.

- Huge explosion on self destruct, can be used as a bomb to kill incoming attacking force.

==== Arm Mobile Fusion ====

Arm-ones are built in the Level Two tank lab, and produce 260 Energy.

Advantages:

- Quite less overall cost

- It's built very fast due to the strong nanolathing from the Level Two Vehicle Factory.

- It is Mobile! This means you can avoid attacks to it by hiding somewhere else.

- Less efficient in space/Energy output than Core Mini Fusion

- In times of peril can be used as bomb by Self Destructing.

Downside:

- Forces the Arm player to build Level Two tank lab to have access to it.

Tips

- You can calculate one Mobile Fusion per Moho Metal Extractor.

- It has a huge explosion on self destroy, and is used often as a last resort defence, (as a Mobile bomb), with great results.

Here is a [http://modinfo.adune.nl/index.php?act=editmultiple&from=find&MOD=XTApev955&units=Arm_Mobile_Fusion+Core_light_Fusion_power_plant reference for stats delta] between Arm and Core Minis.

==== Cloakable Fusions ====

The big Fusions have changed as well.

Now the Cloakable Fusion, is what the normal OTA Fusion used to be, that is, it produces 800 Energy and has a small penalty in its cost compared to Mini Fusions, and to big Fusions, but it almost completely stealth once its cloaked and within radar jammer range.

==== Big Fusions ====

The BIG Fusion makes 3500 Energy, and has a '''very high cost''' (in Energy Metal and Build Time), although its somehow more efficient than Cloakable Fusion, this unit is '''2 TIMES AS EXPENSIVE''' as what the original Fusion used to be, so '''DO NOT BUILD IT RIGHT AWAY'''. This big Fusion is intended for late game, when you will need huge Armies or mass nuclear weapons.

Here is a [http://modinfo.adune.nl/index.php?act=editmultiple&from=find&MOD=XTApev955&units=Arm_Cloakable_Fusion_reactor+Arm_Fusion_reactor comparative view of the Cloakable and Big Fusions.]

==== Note ====

This is an attempt to explain:

1 You must '''NOT build a BIG (non Cloakable) Fusion power plant in XTA''', like you used in OTA.

Use a '''Cloakable Fusion''' for that purpose.

2 There are several new power sources that fill the gap between 20 and 1000 e output OTA had.

3 The Moho Metal Extractors take 300 Energy to work (extract Metal) so do not build them if you do not have the Energy, or will stall your entire production.

= Power consumption/costs =

The first thing you need to know, is, Moho Metal Extractors use 300 of Energy to work.

This can be justified, because of Metal is a quantitative scarce resource, and a Moho Metal Extractor, effectively quintuples the extraction rate, such marvel must come at a cost. In this case the cost, a part of the unit and tech Level itself, is the need of much more power to function.

The increase in the Energy slightly higher than x^5, with x = Energy drain of Level One Metal Extractor.

= Basic XTA description for OTA players =

All Level One units are worth building:
*Stumpies and Hammers are decent anti-Missile Tower choices.
*Jeffies are very dangerous, but they do cost nearly 200 Metal.
*There is a Level One Gunship now.
*Freedom Fighters and Avengers have been given their sorely needed boost.

All Level Two units are worth building:
*Sumos have tons of Armour, huge range, rapid fire rate and move at medium speed.
*Their 2.1k Metal cost is well worth the unit you get in exchange.
*Goliaths have a great deal of health, a medium ranged Plasma main turret and a second laser turret.
*Mavericks build much faster.
*Flakkers fire at ground targets, and their Anti Air potential has been improved.
*Warlords and Leviathans were massively boosted in terms of Armour and firepower.
*Krogoths have 105,000 health and a lot of firepower, as well as a hefty price tag.

Nearly all defences were revamped:
*MTs are nearly unchanged, except they are smaller so that you can fit more of them into the same space.
*LLTs have the range and power to be worth building.
*HLTs are a bit costly, but they can reach further than missiles.
*An excellent early creep weapon.
*Ambusher/Toaster are now buildable by Level One Construction units and fulfil the same role as Guardian/Punisher in OTA.
*Guardian/Punisher are Level Two structures with much longer range, firepower and Armour.
*Annihilators and Doomsday Machines have far higher range, more Armour, and they do not blow up half your base when they die.
*With all the Armour available in Level Two units, you will need them.
*Big Bertha has lost some accuracy, Intimidator lost some range. Both lost firepower but gained Armour and area of effect.
*Stunner/Neutron silos are short ranged, very fast building budget nukes.
*Anti Nuke silos build their missiles faster to accommodate for STUNNER/Neutron change.

Resource structures have changed less than other parts of the mod but the game play impact is very big:
*Metal Extractors self destruct instantly and without damaging anything around them.
*This makes upgrading to Moho Extractors less tedious.
*ARM has a Mobile Fusion, Core has a stationary Light Fusion.
*Both cost 1500 Metal and make about 300 Energy: ideal to fuel your Moho economy.
*Moho Extractors are quite cheap (750 Metal) and make lots of Metal, but they drain 300 Energy.
*You want to have at least a Geo or Mobile/Light Fusion before you build a Moho.
'''Cloakable Fusions have taken the place of OTA's regular ones.'''
*Regular Fusions now cost 12k Metal. Their Armour and Energy production have been increased appropriately.
*Mine layers have several types of mines that are worth building and move faster. Mines are also not visible on radar as in OTA, which makes them useful.
*Energy and Metal Storage stores a lot more.
*Missile frigates have got firepower and health suitable for their cost.
*Mobile artillery and lugers are not inaccurate.
*Decoy commanders build as fast as real commanders.
*The build range on all Construction units has been increased.

[[Category:xta]]

Ota2xta

2010-03-01T18:41:06Z

Jools:

This is a reference for OTA players that play XTA mod for the first time.

But does work as well for new and regulars from other mods.

= The Energy build tree =

[[Image:ArmenergyBpath.jpg|thumb|300px|* Arm energy buildtree ]]

[[Image:Coreenergybpath.jpg|thumb|300px|* Core energy buildtree ]]
In few words, for OTA players, '''do not build the Fusion Power Plant''', use the ''Mini Fusions'' -> ''Cloakable Fusions'' building path instead.

The Energy tree for XTA, differs from OTA in several aspects.

In short, several buildings and Mobile units have been added "in between" the basic Energy sources like Solar Collectors/Wind Generators, and the more advanced Fusion power plant.

== Energy producing buildings and Mobile units ==

=== The basic Energy structures ===

Are the same, windmill, and solar collector.

However there are some differences:

==== The solar collector ====

Main changes from OTA:

- DOES NOT REQUIRE ENERGY to be built.

'''Advantages:'''

- Is heavily armoured.

- Produces a continuous Energy output.

'''Downside:'''

- Its rather expensive in Metal compared to Wind Generators.

- Blocks fire from light laser tower.

'''Tips'''

- Offers a quick solution for Energy stall at mid Metal cost (145 Metal).

- Acts as a barricade/defence.

==== Energy storage ====

The cost has been increased, but the storage capacity is now around 32k.

This makes for a better Energy and Metal resource management, without the hassle of having to build lots and lots of storage.

'''Tips'''

- Combine with windmill farms in windy maps for better results.

- In early game, if you are using Metal makers, it generates non continuous Metal output, so do not build one if you are using Metal maker economy. '''Unless you have some sort of Metal maker ai.'''

Those are the main changes for the level one energy structures.

=== Advanced Energy structures ===

At Level Two, XTA introduces the major changes and advantages compared to OTA.

To start with, there is a "midway" Fusion Energy plant.

'''The Mini Fusions'''

Each side has its own. This units cover the gap between basic Energy sources and the more advanced ones, having around 38%-44% of the Energy output of the next step in the Energy build tree, and offering 19x-22x times the output of a single solar.

==== Core Mini Fusion ====

Produces +300 Energy and are built by Level Two builders.

Advantages:

- Is built by any Level Two construction unit.

- Produces 300 Energy.

Downside:

- It uses more space, for less Energy output compared to bigger Fusions.

Tips

- You can calculate 1 Mini Fusion per MohoMetalExtractor.

- Huge explosion on self destruct, can be used as a bomb to kill incoming attacking force.

==== Arm Mobile Fusion ====

Arm-ones are built in the Level Two tank lab, and produce 260 Energy.

Advantages:

- Quite less overall cost

- It's built very fast due to the strong nanolathing from the Level Two Vehicle Factory.

- It is Mobile! This means you can avoid attacks to it by hiding somewhere else.

- Less efficient in space/Energy output than Core Mini Fusion

- In times of peril can be used as bomb by Self Destructing.

Downside:

- Forces the Arm player to build Level Two tank lab to have access to it.

Tips

- You can calculate one Mobile Fusion per Moho Metal Extractor.

- It has a huge explosion on self destroy, and is used often as a last resort defence, (as a Mobile bomb), with great results.

Here is a [http://modinfo.adune.nl/index.php?act=editmultiple&from=find&MOD=XTApev955&units=Arm_Mobile_Fusion+Core_light_Fusion_power_plant reference for stats delta] between Arm and Core Minis.

==== Cloakable Fusions ====

The big Fusions have changed as well.

Now the Cloakable Fusion, is what the normal OTA Fusion used to be, that is, it produces 800 Energy and has a small penalty in its cost compared to Mini Fusions, and to big Fusions, but it almost completely stealth once its cloaked and within radar jammer range.

==== Big Fusions ====

The BIG Fusion makes 3500 Energy, and has a '''very high cost''' (in Energy Metal and Build Time), although its somehow more efficient than Cloakable Fusion, this unit is '''2 TIMES AS EXPENSIVE''' as what the original Fusion used to be, so '''DO NOT BUILD IT RIGHT AWAY'''. This big Fusion is intended for late game, when you will need huge Armies or mass nuclear weapons.

Here is a [http://modinfo.adune.nl/index.php?act=editmultiple&from=find&MOD=XTApev955&units=Arm_Cloakable_Fusion_reactor+Arm_Fusion_reactor comparative view of the Cloakable and Big Fusions.]

==== Note ====

This is an attempt to explain:

1 You must '''NOT build a BIG (non Cloakable) Fusion power plant in XTA''', like you used in OTA.

Use a '''Cloakable Fusion''' for that purpose.

2 There are several new power sources that fill the gap between 20 and 1000 e output OTA had.

3 The Moho Metal Extractors take 300 Energy to work (extract Metal) so do not build them if you do not have the Energy, or will stall your entire production.

= Power consumption/costs =

The first thing you need to know, is, Moho Metal Extractors use 300 of Energy to work.

This can be justified, because of Metal is a quantitative scarce resource, and a Moho Metal Extractor, effectively quintuples the extraction rate, such marvel must come at a cost. In this case the cost, a part of the unit and tech Level itself, is the need of much more power to function.

The increase in the Energy slightly higher than x^5, with x = Energy drain of Level One Metal Extractor.

= Basic XTA description for OTA players =

All Level One units are worth building:
*Stumpies and Hammers are decent anti-Missile Tower choices.
*Jeffies are very dangerous, but they do cost nearly 200 Metal.
*There is a Level One Gunship now.
*Freedom Fighters and Avengers have been given their sorely needed boost.

All Level Two units are worth building:
*Sumos have tons of Armour, huge range, rapid fire rate and move at medium speed.
*Their 2.1k Metal cost is well worth the unit you get in exchange.
*Goliaths have a great deal of health, a medium ranged Plasma main turret and a second laser turret.
*Mavericks build much faster.
*Flakkers fire at ground targets, and their Anti Air potential has been improved.
*Warlords and Leviathans were massively boosted in terms of Armour and firepower.
*Krogoths have 105,000 health and a lot of firepower, as well as a hefty price tag.

Nearly all defences were revamped:
*MTs are nearly unchanged, except they are smaller so that you can fit more of them into the same space.
*LLTs have the range and power to be worth building.
*HLTs are a bit costly, but they can reach further than missiles.
*An excellent early creep weapon.
*Ambusher/Toaster are now buildable by Level One Construction units and fulfil the same role as Guardian/Punisher in OTA.
*Guardian/Punisher are Level Two structures with much longer range, firepower and Armour.
*Annihilators and Doomsday Machines have far higher range, more Armour, and they do not blow up half your base when they die.
*With all the Armour available in Level Two units, you will need them.
*Big Bertha has lost some accuracy, Intimidator lost some range. Both lost firepower but gained Armour and area of effect.
*Stunner/Neutron silos are short ranged, very fast building budget nukes.
*Anti Nuke silos build their missiles faster to accommodate for STUNNER/Neutron change.

Resource structures have changed less than other parts of the mod but the game play impact is very big:
*Metal Extractors self destruct instantly and without damaging anything around them.
*This makes upgrading to Moho Extractors less tedious.
*ARM has a Mobile Fusion, Core has a stationary Light Fusion.
*Both cost 1500 Metal and make about 300 Energy: ideal to fuel your Moho economy.
*Moho Extractors are quite cheap (750 Metal) and make lots of Metal, but they drain 300 Energy.
*You want to have at least a Geo or Mobile/Light Fusion before you build a Moho.
'''Cloakable Fusions have taken the place of OTA's regular ones.'''
*Regular Fusions now cost 12k Metal. Their Armour and Energy production have been increased appropriately.

*Mine layers have several types of mines that are worth building and move faster. Mines are also not visible on radar as in OTA, which makes them useful.
*Energy and Metal Storage stores a lot more.
*Missile frigates have got firepower and health suitable for their cost.
*Mobile artillery and lugers are not inaccurate.
*Decoy commanders build as fast as real commanders.
*The build range on all Construction units has been increased.

[[Category:xta]]

Ota2xta

2010-03-01T18:29:57Z

Jools:

This is a reference for OTA players that play XTA mod for the first time.

But does work as well for new and regulars from other mods.

= The Energy build tree =

[[Image:ArmenergyBpath.jpg|thumb|300px|* Arm energy buildtree ]]

[[Image:Coreenergybpath.jpg|thumb|300px|* Core energy buildtree ]]
In few words, for OTA players, '''do not build the Fusion Power Plant''', use the ''Mini Fusions'' -> ''Cloakable Fusions'' building path instead.

The Energy tree for XTA, differs from OTA in several aspects.

In short, several buildings and Mobile units have been added "in between" the basic Energy sources like Solar Collectors/Wind Generators, and the more advanced Fusion power plant.

== Energy producing buildings and Mobile units ==

=== The basic Energy structures ===

Are the same, windmill, and solar collector.

However there are some differences:

==== The solar collector ====

Main changes from OTA:

- DOES NOT COST ENERGY to build it.

'''Advantages:'''

- Is heavily armoured.

- Produces a continuous Energy output.

'''Downside:'''

- Its rather expensive in Metal compared to Wind Generators.

- Blocks light laser tower fire.

'''Tips'''

- Offers a quick solution for Energy stall at mid Metal cost (145 Metal).

- Acts as a barricade/defence.

==== Energy storage ====

The cost has been increased, but the storage capacity is now around 32k.

This makes for a better Energy and Metal resource management, without the hassle of having to build lots and lots of storage.

'''Tips'''

- Combine with windmill farms in windy maps for better results.

- In early game, if you are using Metal makers, it generates non continuous Metal output, so do not build one if you are using Metal maker economy. '''Unless you have some sort of Metal maker ai.'''

Those are the main changes for the level one energy structures.

=== Advanced Energy structures ===

At Level Two, XTA introduces the major changes and advantages compared to OTA.

To start with, there is a "midway" Fusion Energy plant.

'''The Mini Fusions'''

Each side has its own. This units cover the gap between basic Energy sources and the more advanced ones, having around 38%-44% of the Energy output of the next step in the Energy build tree, and offering 19x-22x times the output of a single solar.

==== Core Mini Fusion ====

Produces +300 Energy and are built by Level Two builders.

Advantages:

- Is built by any Level Two construction unit.

- Produces 300 Energy.

Downside:

- It uses more space, for less Energy output compared to bigger Fusions.

Tips

- You can calculate 1 Mini Fusion per MohoMetalExtractor.

- Huge explosion on self destroy, can be used as a bomb to kill incoming attacking force.

==== Arm Mobile Fusion ====

Arm ones are built in the Level Two tank lab, and produce 260 Energy.

Advantages:

- Quite less overall cost

- Its build very fast because of the strong nanolathing form the Level Two Vehicle Factory.

- It is Mobile! This means you can avoid attacks to it by hidding somewhere else.

- Less efficient in space/Energy output than Core Mini Fusion

- In times of peril can be used as bomb by Self Destructing.

Downside:

- Forces the Arm player to build Level Two tank lab to have access to it.

Tips

- You can calculate one Mobile Fusion per Moho Metal Extractor.

- It has a huge explosion on self destroy, and is used often as a last resort defence, (as a Mobile bomb), with great results.

Here is a [http://modinfo.adune.nl/index.php?act=editmultiple&from=find&MOD=XTApev955&units=Arm_Mobile_Fusion+Core_light_Fusion_power_plant reference for stats delta] between Arm and Core Minis.

==== Cloakable Fusions ====

The big Fusions have changed as well.

Now the Cloakable Fusion, is what the normal OTA Fusion used to be, that is, it produces 800 Energy and has a small penalty in its cost compared to Mini Fusions, and to big Fusions, but it almost completely stealth once its cloaked and within radar jammer range.

==== Big Fusions ====

The BIG Fusion makes 3500 Energy, and has a '''very high cost''' (in Energy Metal and BT), although its somehow more efficient than Cloakable Fusion, this unit is '''2 TIMES AS EXPENSIVE''' as what the original Fusion used to be, so '''DO NOT BUILD IT RIGHT AWAY'''. This big Fusion is intended for late game, when you will need huge Armies or mass nuclear weapons.

Here is a [http://modinfo.adune.nl/index.php?act=editmultiple&from=find&MOD=XTApev955&units=Arm_Cloakable_Fusion_reactor+Arm_Fusion_reactor comparative view of the Cloakable and Big Fusions.]

==== Note ====

This is an attempt to explain:

1 You must '''NOT build a BIG (non Cloakable) Fusion power plant in XTA''', like you used in OTA.

Use a '''Cloakable Fusion''' for that purpose.

2 There are several new power sources that fill the gap between 20 and 1000 e output OTA had.

3 The Moho Metal Extractors take 300 Energy to work (extract Metal) so do not build them if you do not have the Energy, or will stall your entire production.

= Power consumption/costs =

The first thing you need to know, is, Moho Metal Extractors use 300 of Energy to work.

This can be justified, because of Metal is a quantitative scarce resource, and a Moho Metal Extractor, effectively quintuples the extraction rate, such marvel must come at a cost. In this case the cost, a part of the unit and tech Level itself, is the need of much more power to function.

The increase in the Energy slightly higher than x^5, with x = Energy drain of Level One Metal Extractor.

= Basic XTA description for OTA players =

All Level One units are worth building:
*Stumpies and Hammers are decent anti-Missile Tower choices.
*Jeffies are very dangerous, but they do cost nearly 200 Metal.
*There is a Level One Gunship now.
*Freedom Fighters and Avengers have been given their sorely needed boost.

All Level Two units are worth building:
*Sumos have tons of Armour, huge range, rapid fire rate and move at medium speed.
*Their 2.1k Metal cost is well worth the unit you get in exchange.
*Goliaths have a great deal of health, a medium ranged Plasma main turret and a second laser turret.
*Mavericks build much faster.
*Flakkers fire at ground targets, and their Anti Air potential has been improved.
*Warlords and Leviathans were massively boosted in terms of Armour and firepower.
*Krogoths have 105,000 health and a lot of firepower, as well as a hefty price tag.

Nearly all defences were revamped:
*MTs are nearly unchanged, except they are smaller so that you can fit more of them into the same space.
*LLTs have the range and power to be worth building.
*HLTs are a bit costly, but they can reach further than missiles.
*An excellent early creep weapon.
*Ambusher/Toaster are now buildable by Level One Construction units and fulfil the same role as Guardian/Punisher in OTA.
*Guardian/Punisher are Level Two structures with much longer range, firepower and Armour.
*Annihilators and Doomsday Machines have far higher range, more Armour, and they do not blow up half your base when they die.
*With all the Armour available in Level Two units, you will need them.
*Big Bertha has lost some accuracy, Intimidator lost some range. Both lost firepower but gained Armour and area of effect.
*Stunner/Neutron silos are short ranged, very fast building budget nukes.
*Anti Nuke silos build their missiles faster to accommodate for STUNNER/Neutron change.

Resource structures have changed less than other parts of the mod but the game play impact is very big:
*Metal Extractors self destruct instantly and without damaging anything around them.
*This makes upgrading to Moho Extractors less tedious.
*ARM has a Mobile Fusion, CORE has a stationary Light Fusion.
*Both cost 1500 Metal and make about 300 Energy: ideal to fuel your Moho economy.
*Moho Extractors are quite cheap (750 Metal) and make lots of Metal, but they drain 300 Energy.
*You want to have at least a Geo or Mobile/Light Fusion before you build a Moho.
'''Cloakable Fusions have taken the place of OTA's regular ones.'''
*Regular Fusions now cost 12k Metal. Their Armour and Energy production have been increased appropriately.

*Mine layers have several types of mines that are worth building and move faster.
*Energy and Metal Storage stores a lot more.
*Missile frigates have got firepower and health suitable for their cost.
*Mobile artillery and lugers are not inaccurate.
*Decoy commanders build as fast as real commanders.
*The build range on all Construction units has been increased.

[[Category:xta]]

XTA Clans

2010-01-21T21:28:19Z

Jools:

List of active clans and their members:

'''[CoX]''' Commanders of XTA:

Babbles "My Commander is the army" 
Tribulex "Why so serious? Let's put a *smile* on your face" 
FrozenLegacy "Sorry, Frozen has self destructed, come again later" 
Jools "Do you want some mines with that?" 
Ansiktsburk "Allies losing, need to tech faster!" 
Malric "My gf won't let me play :(" 
Scifi "I'm modding, go away" 
Jimjoe "Stop talking about my mum, Shift" 
V1ntage "I'm really bad!" 
Shift "UKRAINE IS JOKE TO YOU?!" 
Punarbhava "I'm too out of it to care" 
Snel "I'm the only good Swedish player really"

'''[CoW]''' Core of War:

Manolo "Less playing, more speccing!" 
Seba "1v1?" 
TheMightyOne "It hasn't failed me the first 9000 times, so it won't now!" 
FlorisXIV "I have more smurfs than ingame minutes" 
Error232 "I'm rusty, I swear!" 
Kloot "HLT here, HLT there" 
HermuldXV "cow says mooh" 
Jim Hatama "No-one knows who I am" 
Ray "I hate people who are better than me; I love CoW"

'''[RoX]''' Rogues of XTA:

Janid "I love my crashers like my children" 
Tobi "I got bored of doing everything" 
John "My AK beats your AK" 
Pintle "Hey, didn't my clan used to be good?" 
1v0ry_k1ng "I haven't actually played, but I know the balance better than you" 
PhreakY "I'm riding on knowing Pintle"

'''[SIN]'''

Basic "Everything is OP unless I say otherwise" 
el_barto "Barto timed out before he could be quoted" 
Black_cat "I'm the second best Texan in Spring!" 
DearLordAnimal "I am but one of many" 
DojeH "Every low ranking German player is me"

[[Category:xta]]