Spring - User contributions [en]

LuaCallinReturn

2013-10-10T16:55:43Z

Braindamage: added new return val for UnitCmdDone and UnitCommand for spring 95.0

[[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"
Not yet implemented!

UnitEnteredAir() --> "unitID, unitDefID, teamID"
Not yet implemented!

UnitLeftWater() --> "unitID, unitDefID, teamID"
Not yet implemented!

UnitLeftAir() --> "unitID, unitDefID, teamID"
Not yet implemented!

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

==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" Not yet implemented!
 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

[[Category:Lua]]

LuaCallinReturn

2013-10-10T16:53:49Z

Braindamage: MapDrawCmd has been available since ever, just not forwarded in default gadgethandler whilst available in default widgethandler

[[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"

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"
Not yet implemented!

UnitEnteredAir() --> "unitID, unitDefID, teamID"
Not yet implemented!

UnitLeftWater() --> "unitID, unitDefID, teamID"
Not yet implemented!

UnitLeftAir() --> "unitID, unitDefID, teamID"
Not yet implemented!

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"

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"
 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" Not yet implemented!
 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

[[Category:Lua]]

LuaCallinReturn

2013-10-10T16:51:58Z

Braindamage: UnitCommand has been implemented since ever, just the default gadgethandler misses the forwarding, whilst the default widgethandler does

[[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" Not yet implemented!

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"

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"
Not yet implemented!

UnitEnteredAir() --> "unitID, unitDefID, teamID"
Not yet implemented!

UnitLeftWater() --> "unitID, unitDefID, teamID"
Not yet implemented!

UnitLeftAir() --> "unitID, unitDefID, teamID"
Not yet implemented!

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"

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"
 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" Not yet implemented!
 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

[[Category:Lua]]

Lua SyncedCtrl

2013-10-10T14:58:10Z

Braindamage: added userTarget param info to SetUnitTarget

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

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

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

= RulesParams =
string values are new since 95.0

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

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

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

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

'''Spring.SetTeamResource'''
( number teamID, string res, number amount ) -> nil

possible values for res are:
"m" = metal
"e" = energy
"ms" = metal storage
"es" = energy storage


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

'''Spring.ShareTeamResource''' 0.82 and later
( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

= Unit Handling =
'''Spring.CreateUnit''' note: offmap positions are clamped! (you still can use MoveCtrl todo so)
( string "defName" | number unitDefID,
number x, number y, number z,
(number facing | string "facing"),
number teamID
[, boolean build = false]
[, boolean flattenGround = true]
[, number unitID]
[, number builderID]) -> number unitID

possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
if build is true the unit is created in "being built" state, with buildProgress = 0
unitID and builderID are {{new|92.0}}, the former allowing to spawn a unit with
a specific ID.


'''Spring.DestroyUnit'''
( number unitID
[, boolean selfd = false]
[, boolean reclaimed = false]
[, number attackerID ] ) -> nil

selfd := makes the unit act like it self-destructed
reclaimed := don't show any DeathSequences, don't leave a wreckage.
NOTE this does _not_ give back the resources to the team!


'''Spring.TransferUnit'''
( number unitID,
numer newTeamID
[, boolean given = true ] ) -> nil
if given=false, the unit is captured

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

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

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

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

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

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

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

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

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

'''Spring.SetUnitLineage''' Removed from version 83.0 
( number unitID, number teamID [, boolean isRoot] ) -> nil

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

'''Spring.SetUnitTarget'''
( number unitID,
number enemyUnitID | number x, number y, number z,
[ boolean dgun = false ], [ boolean userTarget = false ] ) -> nil userTarget new in version 95.0

'''Spring.SetUnitBlocking''' crushable new in version 85.0
( number unitID, boolean blocking [, boolean collide [, boolean crushable]] ) -> nil

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

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

'''Spring.SetUnitNanoPieces''' {{new|92.0}}
( number builderID, table pieces ) -> nil

'''Spring.SetUnitArmored''' armorMultiple new in version 0.83.x
( number unitID, boolean armored [, number armorMultiple] ) -> nil

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

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

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,]
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}

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


'''Spring.SetUnitPieceCollisionVolumeData'''
( number unitID, number pieceIndex, boolean enableLocal,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number vType, number Axis
) -> nil

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

'''Spring.SetUnitMoveGoal''' used by default commands to get in build-,attackrange etc.
( number unitID, number x, number y, number z,
[, number radius = 0 [, number speed = unit->maxSpeed * 2 ] ] ) -> nil

'''Spring.SetUnitPhysics'''
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
) -> nil

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

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

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

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

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

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

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

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


mpx, mpy, mpz: new middle position of unit

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

relative: are the new coordinates relative to world or unit coordinates?


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

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

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


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

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

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

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

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

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

'''Spring.SetUnitLosState'''
( number unitID, number allyTeam, number los | table losTypes ) -> nil
see above for more info on the arguments

'''Spring.SetUnitSensorRadius'''
( number unitID, string type, number radius ) -> nil | number newRadius
type can be:
"los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"

== Unit Resourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil

possible values for res are: "[u|c][u|m][m|e]"
unconditional | conditional
use | make
metal | energy


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

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

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

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

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

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

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

'''Spring.SetFeatureResurrect'''
( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil

possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3


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

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

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

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

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

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

check Spring.SetUnitMidAndAimPos for further explanation of the arguments

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

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

'''Spring.CallCOBScriptCB''' 
broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil

structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}


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

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

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

'''Spring.SetUnitToFeature'''
( boolean tofeature ) -> nil

an ugly global switch that can be used to block units turning into features when they finish being built (like *A DT's do, which have the isFeature tag)
[http://springrts.com/phpbb/viewtopic.php?f=14&p=481521 thread]


'''Spring.SetExperienceGrade'''
( number expGrade
[, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]] ) -> nil

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


'''Spring.SpawnCEG'''
( string "cegname",
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil

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


'''Spring.SetProjectileTarget'''
( number projID,
[ targetID, targetType ] | [ number posX, number posY, number posZ ] )
-> nil | boolean validTarget
targetType can be one of:
'u' - unit
'f' - feature
'p' - projectile

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

[[category: Lua]]

Lua SyncedRead

2013-09-01T13:55:31Z

Braindamage: added GetUnitWeaponTarget infos

[[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'''
( ) -> 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

=== Unit Informations ===
'''Spring.ValidUnitID'''
( number unitID ) -> boolean
'''Spring.GetUnitIsDead'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitTooltip'''
( number unitID ) -> nil | string tooltip
'''Spring.GetUnitDefID'''
( number unitID ) -> nil | number unitDefID
'''Spring.GetUnitTeam'''
( number unitID ) -> nil | number teamID
'''Spring.GetUnitAllyTeam'''
( number unitID ) -> nil | number allyID
'''Spring.GetUnitLineage''' 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.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
'''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.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''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 |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' (returns the distance of 2 units)
( number unitID1, number unitID2 [, boolean 2D ] ) -> nil | number distance
'''Spring.GetUnitDefDimensions'''
( number unitDefID ) -> nil |
{
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}
'''Spring.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.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

=== 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 },
}
'''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'''
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}

'''Spring.GetCommandQueue''' (same as Spring.GetUnitCommands)
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.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] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFactoryCounts''' (used to get the buildqueue of a factory, seems screwed o_O)
( number unitID [, number count [, boolean addCMDs ] ] ) -> nil | commandQueueTable = {
[2] = { [number unitDefID | number -cmdID] = number count }, ...
}

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

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

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

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

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

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

== Ground ==
=== Ground Informations ===
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

'''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'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''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.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece

'''Spring.GetProjectileTarget'''
( number projectileID ) -> nil | number targetID, string targetType
targetType can be one of:
'u' - unit
'f' - feature
'p' - projectile


'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity

'''Spring.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 here:[[http://springrts.com/wiki/Animation-CobConstants#explode]]
SHATTER = 1, EXPLODE = 2, EXPLODE_ON_HIT = 2, FALL = 4, SMOKE = 8, FIRE = 16
NONE = 32, NO_CEG_TRAIL = 64, NO_HEATCLOUD = 128 
'''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]]

Building Spring on Linux

2013-08-02T14:48:52Z

Braindamage: Undo revision 27478 by Braindamage (talk)

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev cmake
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===
<code><pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread-dev libboost-regex-dev libboost-system-dev \
libboost-program-options-dev libboost-signals-dev

# alternatively, you can try ...
sudo apt-get build-dep spring
</pre></code>

... and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).
(this problem is either not reproducible with Ubuntu 10.10, or not present in spring master anymore)

to speed up compiling/linking, you can install gold, an alternative linker and an ccache:

<code><pre>sudo apt-get install binutils-gold ccache</pre></code>

to make ccache useful, the cache size needs to be increased by:

<code><pre>ccache -M 5G</pre></code>

to set it to 5GB.

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12-15:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
cmake .
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>~/spring</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=~/spring .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr .
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

Building Spring on Linux

2013-08-02T14:48:32Z

Braindamage: Undo revision 27480 by Braindamage (talk)

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev cmake
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===
<code><pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread-dev libboost-regex-dev libboost-system-dev \
libboost-program-options-dev libboost-signals-dev

# alternatively, you can try ...
sudo apt-get build-dep spring
</pre></code>

... and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).
(this problem is either not reproducible with Ubuntu 10.10, or not present in spring master anymore)

to speed up compiling/linking, you can install gold, an alternative linker and an ccache:

<code><pre>sudo apt-get install binutils-gold ccache</pre></code>

to make ccache useful, the cache size needs to be increased by:

<code><pre>ccache -M 5G</pre></code>

to set it to 5GB.

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12-15:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
mkdir build
cd build
cmake ..
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>~/spring</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=~/spring .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr .
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

Building Spring on Linux

2013-08-02T14:42:24Z

Braindamage: updated other cmake usages to be consisent

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev cmake
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===
<code><pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread-dev libboost-regex-dev libboost-system-dev \
libboost-program-options-dev libboost-signals-dev

# alternatively, you can try ...
sudo apt-get build-dep spring
</pre></code>

... and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).
(this problem is either not reproducible with Ubuntu 10.10, or not present in spring master anymore)

to speed up compiling/linking, you can install gold, an alternative linker and an ccache:

<code><pre>sudo apt-get install binutils-gold ccache</pre></code>

to make ccache useful, the cache size needs to be increased by:

<code><pre>ccache -M 5G</pre></code>

to set it to 5GB.

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12-15:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
mkdir build
cd build
cmake ..
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>~/spring</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=~/spring ..
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH ..
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr ..
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

Building Spring on Linux

2013-08-02T14:41:28Z

Braindamage: suggest out-of-source builds by default

[[Engine_Development|Development]] < [[Building_spring|Building Spring]] < {{FULLPAGENAME}}

= Build From Source on Linux =
If you prefer to use your distributions package system (release versions only), refer to the Linux [[SetupGuide]].

If there is no package tailored for your distribution, you have to install from sources manually. Doing this for distributions where packages are available is not recommended.

'''Warning:''' 
'''Be careful when building from source.''' 
You might encounter sync errors in online play if:
* you are using an untested compiler (''gcc'' from the 4.x serie should be safe)
* you use non-standard compiler settings (be careful about ''-march'')!


== Obtaining the Source ==
{{Obtaining_The_Source_Code}}

= Get Dependencies =

To compile, you will have to install some development packages Spring depends on. These vary from distro to distro and may also depend on your specific configuration.

If your distributions is not listed below, you should be able to figure out the correct package names from this.

== Full list ==
* Programs necessary to build
** ''cmake''
** ''7zip'' (aka ''p7zip'' or ''7z'')
** The usual build toolchain
*** ''gcc''
*** ''make''
* Libraries
** SDL
** ''boost'' (version 1.35 or later)
*** ''threads''
*** ''regex''
*** ''signals''
*** ''system''
*** ''program-options''
** ''libdeviL'' (IL)
** OpenAL (openal-soft, older openal-0.0.8 does not work)
** OpenGL headers (mesa, GLEW, etc.)
** ''zlib''
** ''freetype'' (2)
** ''ogg'', ''vorbis'' and ''vorbisfile''
* Optional (for AI Interfaces and Skirmish AIs)
** ''python'' (2.5+)
** ''jdk'' (1.5+)

== Debian ==

For Etch (debian 4.0 stable) and Sid (debian unstable), I've confirmed the
following to be the minimal set that is necessary to get. This works with Ubuntu 8.10, too.
As of ~ July 2009, spring depends on boost 1.35+ (if your distro is behind, you can try [https://launchpad.net/~pgquiles/+archive/ppa some unofficial backports]).

Also, on 64-bit, be sure to build against DevIL 1.6.8-rc2+, as 1.6.7 has a bug in the PNG loading code that causes issues.

<code><pre>
sudo aptitude install build-essential zlib1g-dev libfreetype6-dev cmake
sudo aptitude install libsdl1.2-dev libopenal-dev libglew-dev zip
sudo aptitude install libvorbis-dev libxcursor-dev libdevil-dev
sudo aptitude install libboost-system1.37-dev libboost-system1.37-thread-dev
sudo aptitude install libboost-system1.37-regex-dev
sudo aptitude install libboost-system1.37-serialization-dev
sudo aptitude install libboost-system1.37-program-options-dev
</pre></code>

and cmake, depending on what you use for building (I advise to use cmake). On debian 5.0 (lenny), libglew1.5-dev is required as well.

=== Ubuntu ===
<code><pre>
# compiler and build tools
sudo apt-get install build-essential cmake cmake-gui git

# spring dependencies
sudo apt-get install libglew-dev libsdl-dev libdevil-dev libopenal-dev \
libogg-dev libvorbis-dev libfreetype6-dev p7zip-full libxcursor-dev \
libboost-thread-dev libboost-regex-dev libboost-system-dev \
libboost-program-options-dev libboost-signals-dev

# alternatively, you can try ...
sudo apt-get build-dep spring
</pre></code>

... and that should install all the required dependencies (''it should but it appears to be broken - SpliFF 2011-02-21'').

NOTE: On Ubuntu the CMake scripts currently don't detect FREETYPE_INCLUDE_DIR. You will need to set this by hand (using -DFREETYPE_INCLUDE_DIR="/usr/include/freetype2/freetype" or by adding an 'advanced' entry in cmake-gui).
(this problem is either not reproducible with Ubuntu 10.10, or not present in spring master anymore)

to speed up compiling/linking, you can install gold, an alternative linker and an ccache:

<code><pre>sudo apt-get install binutils-gold ccache</pre></code>

to make ccache useful, the cache size needs to be increased by:

<code><pre>ccache -M 5G</pre></code>

to set it to 5GB.

== Gentoo ==
This has been tested to work with a clean install of gentoo 2008.0:

<code><pre>
emerge cmake \>=media-libs/freetype-2.0.0 \>=media-libs/libsdl-1.2.0
emerge media-libs/openal media-libs/glew dev-libs/boost
emerge app-arch/zip media-libs/libogg
USE="png jpg tiff opengl" emerge media-libs/devil
</pre></code>

== Fedora ==

On Fedora 8:

<code><pre>
yum install cmake boost-devel openal-devel SDL-devel \
DevIL-devel glew-devel libvorbis-devel
</pre></code>

On Fedora 12-15:

<code><pre>
yum install gcc-c++ cmake boost-devel DevIL-devel freetype-devel \
glew-devel libvorbis-devel libXcursor-devel openal-devel SDL-devel p7zip
</pre></code>

== Slackware ==

On Slackware 13, cmake, ogg & vorbis, boost, glew and SDL already come with the full regular install, both libs and headers. You can find helper scripts to easily compile and package DevIL, OpenAL and spring itself [http://slackbuilds.org/ here].

= Build And Install =

== Using CMake (2.6 or newer) ==
Configure and build:

<code><pre>
mkdir build
cd build
cmake ..
make spring
</pre></code>

Install:

<code><pre>
make install-spring
</pre></code>

Default install paths are:

<code>/usr/local/bin/spring</code> Spring executable

<code>/usr/local/share/games/spring</code> read-only data

If you want <code>~/spring</code> prefix instead of <code>/usr/local</code>, configure like this:

<code><pre>
cmake -DCMAKE_INSTALL_PREFIX=~/spring .
</pre></code>
For further ways of customizing your build, have a look at the variables shown with:
<code><pre>
cmake -LH .
</pre></code>

Ububtu 9.10 - if it cannot locate freetype include dir, then use:
<code><pre>
cmake -DFREETYPE_INCLUDE_DIR=/usr .
</pre></code>

If you experience performance problems on multi-core systems, you may additionally build the MT version of spring:

<code><pre>
make spring-multithreaded
</pre></code>

And install with:
<code><pre>
make install-spring-multithreaded
</pre></code>

Other targets are: <code>spring-headless</code> and <code>spring-dedicated</code>.

{{Troubleshooting_linux}}

[[Category:Compiling]]
[[Category:Linux]]

Lua UnsyncedRead

2013-02-15T15:15:35Z

Braindamage: added arg for GetPlayerRoster

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

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetReplayLength''' {{new|92.0}}
( ) -> nil | number (in gameframes)
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

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

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] | [number sortType], [bool showPathingPlayers] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}
if pingTime is == -1, the player is pathfinding, in order to find the progress, use:
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000
for the progress
 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z
'''Spring.TraceScreenRay'''
( number mouseX, number mouseY [, boolean onlyCoords
[, boolean useMinimap, [boolean includeSky]] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean midPos = false ] ) -> nil | number x, number y, number z
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== UI ==

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "pathTraversability" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> 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.GetActiveCmdDesc'''
( number index ) -> nil | {
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.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''
( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed
'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number] = boolean,
...
}
'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | { [1] = {[string actionCmd] = string actionExtra}, ... }
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit

== Time ==
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.DiffTimers'''
( timer cur, timer ago) -> number seconds

== Rendering ==

'''Spring.GetMapSquareTexture'''
(number texSqrX, number texSqrY, number texMipLvl, string luaTexName) -> boolean success

[[category: Lua]]

Lua UnsyncedRead

2013-02-15T02:51:26Z

Braindamage: added pathfindingprogress infos for GetPlayerRoster

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

== Replay/Spectating ==
'''Spring.IsReplay'''
( ) -> nil | boolean
'''Spring.GetReplayLength''' {{new|92.0}}
( ) -> nil | number (in gameframes)
'''Spring.GetSpectatingState'''
( ) -> boolean spectating, boolean fullView, boolean fullSelect

== ModUI ==
'''Spring.GetModUICtrl'''
( ) -> boolean

== MyInfo ==
'''Spring.GetMyAllyTeamID'''
( ) -> number
'''Spring.GetMyTeamID'''
( ) -> number
'''Spring.GetMyPlayerID'''
( ) -> number

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

'''Spring.GetLocalPlayerID'''
( ) -> number playerID
'''Spring.GetLocalTeamID'''
( ) -> number teamID
'''Spring.GetLocalAllyTeamID'''
( ) -> number allyID

== Team/Player Info ==
'''Spring.GetPlayerRoster'''
( [number sortType] ) ->
nil | playerTable = {
[1] = {
string name,
number playerID,
number teamID,
number allyTeamID,
boolean spectator,
number cpuUsage,
number pingTime
},
etc...
}
if pingTime is == -1, the player is pathfinding, in order to find the progress, use
cpuUsage&0x1 if it's PC or BO, cpuUsage& 0xFE to get path res, (cpuUsage>>8)*1000) for the progress
 Sort codes:
1 = Sort by allies (the default)
2 = Sort by teamID
3 = Sort by playerName
4 = Sort by CPU usage
5 = Sort by ping time
'''Spring.GetTeamColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetTeamOrigColor'''
( number teamID ) -> nil | number r, number g, number b, number a
'''Spring.GetPlayerTraffic'''
( number playerID [, number packetID] ) -> number

== Sound ==
'''Spring.GetSoundStreamTime'''
( ) -> number playedTime, number totalTime

== Camera ==
'''Spring.GetCameraNames'''
( ) -> { [camName] = number camNum, ... }
'''Spring.GetCameraState'''
( ) -> { "name" = string, "mode" = number camIdx, state1 = number, state2 = number, ... }

See [[Lua_camState]] for details about Spring.GetCameraState output.

'''Spring.GetCameraPosition'''
( ) -> number x, number y, number z
'''Spring.GetCameraDirection'''
( ) -> number forward_x, number forward_y, number forward_z
'''Spring.GetCameraFOV'''
( ) -> number fov
'''Spring.GetCameraVectors'''
( ) -> vectorTable = {
forward = { [1] = number x, [2] = number y, [3] = number z },
up = { [1] = number x, [2] = number y, [3] = number z },
right = { [1] = number x, [2] = number y, [3] = number z },
top = { [1] = number x, [2] = number y, [3] = number z },
bottom = { [1] = number x, [2] = number y, [3] = number z },
leftside = { [1] = number x, [2] = number y, [3] = number z },
rightside = { [1] = number x, [2] = number y, [3] = number z }
}

=== Inview ===
'''Spring.GetVisibleUnits'''
( [number teamID = -1 [, number radius = 30 [, boolean Icons = true ]]] )
-> nil | unitTable = { [1] = number unitID, ... }
'''Spring.GetVisibleFeatures'''
( [number allyTeamID = -1 [, number radius = 30 [, boolean Icons = true [, boolean geos = true ]]]] )
-> nil | featureTable = { [1] = number featureID, ... }

'''Spring.IsAABBInView'''
( number minX, number minY, number minZ,
number maxX, number maxY, number maxZ ) -> nil | boolean
'''Spring.IsSphereInView'''
( number x, number y, number z [, number radius ] ) -> nil | boolean
'''Spring.IsUnitIcon'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitInView'''
( number unitID ) -> nil | boolean
'''Spring.IsUnitVisible'''
( number unitID [, number radius [, boolean checkIcons] ] ) -> nil | boolean

=== Screen Trace ===
'''Spring.WorldToScreenCoords'''
( number x, number y, number z ) -> number x, number y, number z
'''Spring.TraceScreenRay'''
( number mouseX, number mouseY [, boolean onlyCoords
[, boolean useMinimap, [boolean includeSky]] ] )
-> nil |
string "unit", number unitID |
string "feature", number featureID |
string "ground", { [1] = number x, [2] = number y, [3] = number z }

=== Screen & Window Geometry ===
'''Spring.GetViewGeometry'''
( ) -> number viewSizeX, number viewSizeY, number viewPosX, number viewPosY
'''Spring.GetWindowGeometry'''
( ) -> number winSizeX, number winSizeY, number winPosX, number winPosY
'''Spring.GetScreenGeometry''' (is missing multiscreen support!)
( ) -> number screenSizeX, number screenSizeY, number ZERO, number ZERO

== Unit ==
'''Spring.IsUnitAllied'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitViewPosition'''
( number unitID [, boolean midPos = false ] ) -> nil | number x, number y, number z
'''Spring.GetUnitTransformMatrix'''
( number unitID [, boolean invert = false] ) -> nil | number a11, number a12 ..., number a44 (4x4 matrix)

=== Selected Units ===
'''Spring.GetSelectedUnits'''
( ) -> { [1] = unitID, ... }
'''Spring.GetSelectedUnitsSorted'''
( ) -> { [number unitDefID] = { [1] = [number unitID], etc...}, ... }
'''Spring.GetSelectedUnitsCounts'''
( ) -> { [number unitDefID] = number count, etc... }
'''Spring.GetSelectedUnitsCount'''
( ) -> number count
'''Spring.IsUnitSelected'''
( number unitID ) -> nil | boolean

=== Unit Groups ===
'''Spring.GetUnitGroup'''
( number unitID ) -> nil | number

'''Spring.GetGroupList'''
( ) -> nil | {
[number] = number unitCount,
...
}
'''Spring.GetSelectedGroup'''
( ) -> number
'''Spring.GetGroupAIName'''
( number groupID ) -> string aiName
'''Spring.GetGroupAIList'''
( ) -> {
[1] = string aiName, ...
}

'''Spring.GetGroupUnits'''
( number groupID ) -> nil | {
[1] = number unitID, ...
}
'''Spring.GetGroupUnitsSorted'''
( number groupID ) -> nil | {
[number unitDefID] = {number unitID, ...}, ...
}
'''Spring.GetGroupUnitsCounts'''
( number groupID ) -> nil | {
[number unitDefID] = number count, ...
}
'''Spring.GetGroupUnitsCount'''
( number groupID ) -> nil | number count

== UI ==

=== GUI Settings ===
'''Spring.IsGUIHidden'''
( ) -> nil | boolean
'''Spring.HaveShadows'''
( ) -> nil | boolean
'''Spring.HaveAdvShading'''
( ) -> nil | boolean
'''Spring.GetWaterMode'''
( ) -> nil | number mode, string "mode"

 mode numbers:
0 - basic
1 - reflective
2 - dynamic
3 - refractive
4 - bumpwater
default - unknown
'''Spring.GetMapDrawMode'''
( ) -> nil | "normal" | "height" | "metal" | "pathTraversability" | "los"
'''Spring.GetDrawSelectionInfo''' Returns whether "Selected units" text is displayed.
( ) -> boolean

=== Unit GUI States ===
'''Spring.GetUnitLuaDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoDraw'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoMinimap'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitNoSelect'''
( number unitID ) -> nil | boolean

=== Minimap ===
'''Spring.GetMiniMapGeometry'''
( ) -> number posX, number posY, number sizeX, number sizeY,
boolean minimized, boolean maximized
'''Spring.GetMiniMapDualScreen'''
( ) -> boolean false | string "left" | string "right"
'''Spring.IsAboveMiniMap'''
( number x, number y ) -> nil | boolean

=== (Build-)Menu ===
'''Spring.GetActiveCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetDefaultCommand'''
( ) -> nil | number index (, number cmd_id, number cmd_type, string cmd_name)
'''Spring.GetActiveCmdDescs'''
( ) -> 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.GetActiveCmdDesc'''
( number index ) -> nil | {
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.GetCmdDescIndex'''
( number cmdID ) -> nil | number index
'''Spring.GetActivePage'''
( ) -> nil | number pageNum, number maxPages

=== Build Facing ===
'''Spring.GetBuildFacing'''
( ) -> nil | number
'''Spring.GetBuildSpacing'''
( ) -> nil | number

=== GatherMode & InvertQueueKey ===
'''Spring.GetGatherMode'''
( ) -> nil | number
'''Spring.GetInvertQueueKey'''
( ) -> nil | boolean

=== Mouse States ===
'''Spring.GetMouseState'''
( ) -> number X, number Y,
boolean leftPressed, boolean middlePressed, boolean rightPressed
'''Spring.GetMouseCursor'''
( ) -> string name, number scale
'''Spring.GetMouseStartPosition'''
( number mouseButton ) -> nil | number pressedX, number pressedY,
number camPosX, number camPosY, number camPosZ,
number dirX, number dirY, number dirZ

=== (Hot-)Keys ===
'''Spring.GetKeyState'''
( number key ) -> nil | boolean
'''Spring.GetModKeyState'''
( ) -> boolean alt, boolean ctrl, boolean meta, boolean shift
'''Spring.GetPressedKeys'''
( ) -> {
[number] = boolean,
...
}
'''Spring.GetKeyCode'''
( string keysym ) -> number
'''Spring.GetKeySymbol'''
( number key ) -> string "keysym1", string "keysym2"
'''Spring.GetKeyBindings'''
( string keyset ) -> nil | { [1] = {[string actionCmd] = string actionExtra}, ... }
'''Spring.GetActionHotKeys'''
( string action ) -> nil | { [1] = string hotKey, ... }

=== Console ===
'''Spring.GetLastMessagePositions'''
( ) -> nil | {
[1] = { number X, number Y, number Z },
...
}
'''Spring.GetConsoleBuffer'''
( [number maxLines] ) -> nil | {
[1] = {
text = string,
priority = number
}, ...
}
'''Spring.GetCurrentTooltip'''
( ) -> string

== FPS & GetDrawFrame ==
'''Spring.GetFPS'''
( ) -> number
'''Spring.GetDrawFrame'''
( ) -> number low 16bit, number high 16bit

== Time ==
'''Spring.GetFrameTimeOffset'''
( ) -> nil | number
'''Spring.GetLastUpdateSeconds'''
( ) -> nil | number
'''Spring.GetHasLag'''
( ) -> boolean
'''Spring.GetTimer'''
( ) -> timer
'''Spring.DiffTimers'''
( timer cur, timer ago) -> number seconds

== Rendering ==

'''Spring.GetMapSquareTexture'''
(number texSqrX, number texSqrY, number texMipLvl, string luaTexName) -> boolean success

[[category: Lua]]

FAQ:trouble

2011-06-21T21:35:45Z

Braindamage: spring allows midgame join since almost 1 year

[[Category:FAQ]]

=Troubleshooting=

==Network==

===My buddy can not connect to a game I've opened. What can we do?===
The engine uses UDP port 8452 by default, which can be changed in the lobby. If you are behind a router, and are having problems hosting, try forwarding the correct port and also make sure the firewall is not blocking it. If you do not know what a port or a firewall is, use a relay host instead: when hosting a game, tick the check-box labeled "Use relayhost".

==Graphics==

===I am having really bad framerates (fps) on my dual core! What am I doing wrong?===
Some of this helped other users:

* This error is sometimes reported by people having multicore-CPUs. To solve this, you could try to restrict it to run on one core. Enable "SetCoreAffinity=1" in your springsettings.cfg or ~/.springrc.
* Installing the latest processor drivers and Windows hotfixes for your system may also help.
* Also you may try multithreaded version of Spring, which comes with the installation pack labeled as 'Multi-threaded executable' option. WARNING: `multithreaded` means something different in this context than 99.9% of the ppl think!!! Also this engine version is LESS STABLE and is known to not work with most Lua widgets!!!
* Also try to disabling the "Exhaust" effect on planes could help: Press f11 while ingame, disable LUPS and Lups manager (by clicking on them to make them turn red)

===How to Alt-Tab out of full-screen on Linux?===
Play windowed with ''/grabinput'', or [http://springrts.com/phpbb/viewtopic.php?p=449972#p449972 use devilspie].

===I use Linux with Open-Source Gfx drivers, and the map is all white!===
Due to patents S3TC texture support is disabled by default. To enable it you need the tool driconf (note, you no longer require libdxtn):

<code><pre>
$ sudo apt-get install libgl1-mesa-dev driconf 
$ driconf 
</pre></code>

On the "Image Quality" tab activate "Enable S3TC texture compression even if software support is not available".

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=20&t=20809 Spring on Intel or ATI 'open-source' drivers]

===It crashes, hangs, ...===
Possible fixes are:
* updating your graphics driver
* lowering the graphic-settings at SpringSettings
* disabling graphics effects at SpringSettings

===Nvidia===

====Nvidia: I am having really bad framerates (FPS)!====
Turn off 'threaded optimizations' for Spring in the nVidia control panel, enable "Compress textures" in SpringSettings.

====It crashes====

try disabling shadows (SpringSettings)

===Intel===

====Why does spring hang for a few seconds?====
This bug occurs on maps like FolsomDamDeluxeV2, Tangerline. FPS suddenly drops to 1 and game runs very slowly. This seems to be an Intel driver bug. For Windows Vista/7 try updating driver up to 8.15.10.2246 or newer. For Windows XP there is no solution yet.

Related forum threads:
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23541 Intel HD Graphics Driver issue?]
* [http://springrts.com/phpbb/viewtopic.php?f=11&t=23081 Performance issues on Intel X4500]

====Fonts are unreadable====
[[File:IntelBorkedFonts.png|200px]]

This is a driver bug, try to update/downgrade your driver.

====It crashes, hangs etc...====
Possible fixes are:
* disabling texture-compression at SpringSettings
* disabling reflective units at SpringSettings
* [http://downloadcenter.intel.com/ updating your driver]
* use linux! (yes, this hint sucks, but the open-source-drivers seems to work better...)

===ATI/AMD===
First of all, if you encourage a graphics related problem on ATI/AMD graphic device update your drivers to the latest version [http://support.amd.com/us/gpudownload/Pages/index.aspx ATI/AMD dowload].

==== I've got the most recent drivers and the game crashes in atioglxx.dll====
As of Spring 0.80.5, use only basic or dynamic water. Bump water with disabled shore waves should also work. Reflective or refractive water will make the game crash after 15-20 minutes due to a memory leak.

Spring 0.81.2 and/or Catalyst 10.2 drivers or newer should fix this problem.

if the game crashes immediatly after the loading screen is finished ("Finalizing") in the Zero-K or Gundam mods and the video card is based on the RV670 GPU (some models of: 3690, 3850, 3870, 4570, 4730, 3730, 3610, 4580, 4750, 3750, 2600 XT/PRO, 3830) Catalyst 8.12 drivers may fix it (windows xp 32-bit, possibly other NT5-based 32-bit platforms), however even with that driver there may still be a crash (not immediatly after the loading screen, as soon as the simulations starts) in Annihilation-based mods that use RED UI, the same lua-based atioglxx.dll crash also happens with the 1944 mod.

also note that later versions of Catalyst drivers for these cards reduce performance in OpenGL applications (windows xp 32-bit, possibly other NT5-based 32-bit platforms) (found at least in: spring, quake3 and Nexuiz), for spring the most significant drop (by ~15%) appears in 9.10 and higher Catalyst versions (more than 15%), if you have one of the lower-performing models of these and don't use shadows you may want to try the Catalyst 8.3 and 8.4 drivers (they do not support shadows but should work ~5% faster compared to 8.12) but those drivers may be less stable

====I've got a notebook and official ATI/AMD drivers refuse to install, what to do?====
First of all, make sure you're installing the 'AMD Mobility Radeon' driver pack branch.
Use [http://www.driverheaven.net/modtool.php ATI Mobility Modder] or unofficial drivers - DNA or Omega. Use [http://google.com Google] or get them from [http://downloads.guru3d.com/Videocards----ATI-Catalyst-(Modified)_c24.html guru3d].

====UI disapears after 5-10 mins of play on old ATI videocards====
In cmdcolors.txt, simply comment out or remove the following lines:
stipplePattern 0xffcc
stippleFactor 1
stippleSpeed 1.0
The problem detected on:
* ATI Radeon X3200 with latest drivers ([http://springrts.com/phpbb/viewtopic.php?f=11&t=20817 ref])
* ATI Radeon 9500 with Omega drivers 3.8.442 ([http://springrts.com/phpbb/viewtopic.php?f=11&t=23526 ref])

====I see the complete screen full of red/green/yellow or giant dots on minimap====

[[File:Redui-minimap-bug.pngâ€Ž|200px]]

This is a bug somewhere in LUA drawing with ATI/AMD. Disable widgets that draw via F11 menu to find the one. There is no real fix. A Widget causing this is "Red UI Minimap". Setting "Max nano simultaneous particles" (SpringSettings) seems to help, too.

====The textures looks scary====
[[File:Ati-drawing-issues.jpg|200px]]

This is a known ATI/AMD-bug. Try using different driver, preferably other than 10.5, 10.6, 10.7 -> newer driver pack with fixed OpenGL driver should be fine.

====It crashes always at start, hangs etc...====
Possible fixes are:
* using basic water (SpringSettings)
* disabling vsync (SpringSettings)
* disabling Pixelbuffer objects (SpringSettings)
* disabling Anti-Aliasing (SpringSettings)
* updating or even downgrading [http://support.amd.com/ ATI driver]: ATI/AMD OpenGL drivers are very buggy, blame ATI/AMD for that!
* set AtiHacks=1 (~/.springrc or springsettings.cfg)

==Sound==

===The Sound is crackling/pausing in Windows, what can i do?===
Try:
* Update the sounds driver
* Enable SystemSoundsService in Vista/Seven

===I am having sound problems under Linux! What can i do?===
In more then 90% of the cases, this is caused by PulseAudio. If this is the problem, there are two known solutions to solve it. Use one of them.

disable non-ALSA (preferred)

Make sure you have the OpenAL-Soft configuration utility. You might want to run:

<code><pre>
# install
sudo apt-get install alsoft-conf
# run
alsoft-conf
</pre></code>

In the "backend" tab, keep only "ALSA" on the left column, then save. Done!

''Side Note:'' ALSA is redirected to the PulseAudio layer when installed.

remove PulseAudio (alternative)

You can safely remove PulseAudio from your system. To do this, open your favorite package manager (eg. Synaptic under Ubuntu), and search for packages with "pulse" in their name. From these, keep only the ones with names that start with "lib", and remove all others.

==Misc==

===I have a problem that is not described here! What can i do?===
There is a number of things you can do, among these are:
* Search in the [http://springrts.com/phpbb/viewforum.php?f=11 Help & Bugs Forum], and ask if you can not find a suiting topic.
* Look at the [[Gentoo_install#Linux_specific_Troubleshooting|Linux only FAQ]].
* Ask for help in the lobby in a suiting channel, eg: #springlobby, #de, #fr, #ai, #main
* Ask the FAQ-Bot in the lobby in channel #springlobby. To get a list of topics, write ''!faqlist'' and then use ''!faq <topic-name>'' to get the help text. For example, try ''!faq rename''.

LuaCallinReturn

2011-06-19T14:47:17Z

Braindamage: added GameProgress

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

===Lua Call-Ins, with parameters===

''Here are the known reserved parameter values for all Lua Call-Ins. If you add new Call-Ins to Spring, please document them here.''

==Commands, general-purpose:==

Shutdown() --> none.

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"

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

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.

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"

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam"

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam"

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"

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

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

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag"

==Drawing:==

* 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"

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

[[category: Lua]]

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

Download

2011-01-20T23:49:52Z

Braindamage: Spring Engine Updates -> Spring Engine ( no games included )

{{#css:
#content * {font-family: 'Bitstream Vera Sans', 'Trebuchet MS', 'Arial', 'Myriad Pro', 'FreeSans';}
}}
= Downloads =
<center>
{|style="margin-top: 15px; padding: 10px; background:rgba(45,180,19,0.5); border: 1px solid rgba(0,0,0,0.5); border-radius: 6px 6px 6px 6px; box-shadow: 0 2px 6px rgba(0,0,0,0.3), inset 0 1px 2px rgba(255,255,255,0.5), inset 0 10px 8px rgba(255,255,255,0.3);" |
| If you just want to get ready to play, you want this:
|-
| style="margin-top: 15px; text-align: center" | [[GamesDownloads|Games Downloads]]
|}
</center>

= Spring Engine (no games included) =
Latest stable version is: '''{{StableEngineVersion}}'''

{|
| style="padding-right:10px"| [[Image:Window.png]]
| '''Installer: [http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}.exe/download spring_{{StableEngineVersion}}.exe ~21MB]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}.exe {mirror}]''' 
'''Portable: [http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}_portable.7z/download spring_{{StableEngineVersion}}_portable.7z ~18MB]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}portable.7z {mirror}]
|}

{|
| style="padding-right:10px"| [[Image:Tux-G2.pngâ€Ž]]
| follow the '''[[SetupGuide|Linux Setup guide]]'''
|}

{|
| style="padding-right:10px"| [[Image:Apple.png]]
| ''' ''No download yet'' '''
The Mac OS X port is rough and unfinished. Help with its development would be greatly appreciated. More information on the current state of this port can be found '''[[Spring_on_MacOSX|here]]'''.
|}

= Testing/Nightly Builds =
Used for testing latest engine developments.
[http://springrts.com/dl/buildbot/ list of all test builds]

= Source Code =
== git ==
'''[http://github.com/spring/spring Spring project page at github]''' [http://status.github.com (status page)]
=== Getting the Source ===
<code><pre>git clone git://github.com/spring/spring.git</pre></code>
This however gives you the bleeding edge, if you want to play online then run:
<code>git checkout {{StableEngineVersion}}</code>
from within the source directory. This will provide the correct source code
=== Alternate git url ===
<code><pre>git://springrts.git.sourceforge.net/gitroot/springrts/springrts</pre></code>

== Latest Stable Snapshot ==
This tarball is the same as that used to build the last public release. See [[Building spring]] for build instructions.

The packages below target Linux only and do not contain certain files required to compile using CMake on Windows.

'''[http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}_src.tar.lzma/download spring_{{StableEngineVersion}}_src.tar.lzma]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}_src.tar.lzma {mirror}]

'''[http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}_src.tar.gz/download spring_{{StableEngineVersion}}_src.tar.gz]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}_src.tar.gz {mirror}]

= Other springrts.com hosted projects =
== TASClient ==
An alternative windows only lobby client.

'''[http://springrts.com/dl/tasclient/TASClientLatest.7z Download TASClient]'''

== Lobby server==
If you do not want (or are unable) to use the public lobby server, you can download the server software here to run your own. See the readme '''[http://springrts.com/dl/tasserver_readme.txt here]'''.

'''[http://springrts.com/dl/TASServer.jar Click here to download]''' 100.7kb, added 2008-03-02 (requires Java Runtime Environment)
__NOTOC__

Download

2010-09-14T21:10:27Z

Braindamage: Removed deprecated selection editor

{{#css:
#content * {font-family: 'Bitstream Vera Sans', 'Trebuchet MS', 'Arial', 'Myriad Pro', 'FreeSans';}
}}
= Downloads =
<center>
{|style="margin-top: 15px; padding: 10px; background:rgba(45,180,19,0.5); border: 1px solid rgba(0,0,0,0.5); border-radius: 6px 6px 6px 6px; box-shadow: 0 2px 6px rgba(0,0,0,0.3), inset 0 1px 2px rgba(255,255,255,0.5), inset 0 10px 8px rgba(255,255,255,0.3);" |
| If you just want to get ready to play, you want this:
|-
| style="margin-top: 15px; text-align: center" | [[GamesDownloads|Games Downloads]]
|}
</center>

= Spring Engine Updates =
Latest stable version is: '''{{StableEngineVersion}}'''

{|
| style="padding-right:10px"| [[Image:Window.png]]
| '''Installer: [http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}.exe/download spring_{{StableEngineVersion}}.exe ~21MB]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}.exe {mirror}]''' 
'''Portable: [http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}_portable.7z/download spring_{{StableEngineVersion}}_portable.7z ~18MB]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}portable.7z {mirror}]
|}

{|
| style="padding-right:10px"| [[Image:Tux-G2.pngâ€Ž]]
| follow the '''[[SetupGuide|Linux Setup guide]]'''
|}

{|
| style="padding-right:10px"| [[Image:Apple.png]]
| ''' ''No download yet'' '''
The Mac OS X port is rough and unfinished. Help with its development would be greatly appreciated. More information on the current state of this port can be found '''[[Spring_on_MacOSX|here]]'''.
|}

= Testing/Nightly Builds =
Used for testing latest engine developments.
[http://springrts.com/dl/buildbot/ list of all test builds]

= Source Code =
== git ==
'''[http://github.com/spring/spring Spring project page at github]''' [http://status.github.com (status page)]
=== Getting the Source ===
<code><pre>git clone git://github.com/spring/spring.git</pre></code>
This however gives you the bleeding edge, if you want to play online then run:
<code>git checkout {{StableEngineVersion}}</code>
from within the source directory. This will provide the correct source code
=== Alternate git url ===
<code><pre>git://springrts.git.sourceforge.net/gitroot/springrts/springrts</pre></code>

== Latest Stable Snapshot ==
This tarball is the same as that used to build the last public release. See [[Building spring]] for build instructions.

The packages below target Linux only and do not contain certain files required to compile using CMake on Windows.

'''[http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}_src.tar.lzma/download spring_{{StableEngineVersion}}_src.tar.lzma]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}_src.tar.lzma {mirror}]

'''[http://sourceforge.net/projects/springrts/files/springrts/spring-{{StableEngineVersion}}/spring_{{StableEngineVersion}}_src.tar.gz/download spring_{{StableEngineVersion}}_src.tar.gz]''' - [http://springrts.com/dl/spring_{{StableEngineVersion}}_src.tar.gz {mirror}]

= Other springrts.com hosted projects =
== TASClient ==
An alternative windows only lobby client.

'''[http://springrts.com/dl/tasclient/TASClientLatest.7z Download TASClient]'''

== Lobby server==
If you do not want (or are unable) to use the public lobby server, you can download the server software here to run your own. See the readme '''[http://springrts.com/dl/tasserver_readme.txt here]'''.

'''[http://springrts.com/dl/TASServer.jar Click here to download]''' 100.7kb, added 2008-03-02 (requires Java Runtime Environment)
__NOTOC__

LuaCallinReturn

2010-09-09T22:01:04Z

Braindamage: added info about GameOver call-in

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

===Lua Call-Ins, with parameters===

''Here are the known reserved parameter values for all Lua Call-Ins. If you add new Call-Ins to Spring, please document them here.''

==Commands, general-purpose:==

Shutdown() --> none.

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"

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

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

MousePress() --> "x, y, button"

MouseRelease() --> "x, y, button"

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"

==Unit-Specific:==

UnitPreDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam"

UnitDamaged() --> "unitID, unitDefID, unitTeam, damage, paralyzer, weaponID, attackerID, attackerDefID, attackerTeam"

UnitCreated() --> "unitID, unitDefID, teamID" ... I hope that's self-explanatory

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"

==Feature-Specific:==

FeatureCreated() --> "featureID, allyTeam"

FeatureDestroyed() --> "featureID, allyTeam"

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

UnitCmdDone() --> "unitID, unitDefID, unitTeam, cmdID, cmdTag"

==Drawing:==

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

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.

==Projectiles:==

ProjectileCreated() --> "proID, proOwnerID"

ProjectileDestroyed() --> "proID"

[[category: Lua]]

Lua SyncedCtrl

2010-09-09T21:56:23Z

Braindamage: Added doc about new call-out to handle game end

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

= Game End =
'''Spring.KillTeam''' New in version 0.83.x 
( number teamID ) -> nil
 will declare a team to be dead ( no further orders can be assigned to such teams's units )

'''Spring.GameOver''' New in version 0.83.x 
( [ [1] = allyTeamID1, [2] = allyTeamID2, .. ] ) -> nil
 will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed

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

'''Spring.SetTeamResource'''
( number teamID, string res, number amount ) -> nil

possible values for res are:
"m" = metal
"e" = energy
"ms" = metal storage
"es" = energy storage


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

'''Spring.ShareTeamResource''' 0.82 and later
( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

= Unit Handling =
'''Spring.CreateUnit''' note: offmap positions are clamped! (you still can use MoveCtrl todo so)
( string "defName" | number unitDefID,
number x, number y, number z,
(number facing | string "facing"),
number teamID,
[boolean build = false] ) -> number unitID

possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
if build is true the unit is created in "being built" state, with buildProgress = 0


'''Spring.DestroyUnit'''
( number unitID,
[boolean selfd = false,]
[boolean reclaimed = false,]
[number attackerID] ) -> nil

selfd := makes the unit act like it self-destructed
reclaimed := don't show any DeathSequences, don't leave a wreckage.
NOTE this does _not_ give back the resources to the team!


'''Spring.TransferUnit'''
( number unitID,
numer newTeamID,
[boolean given = true] ) -> nil
if given=false, the unit is captured

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

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

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

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

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

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

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

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

'''Spring.SetUnitLineage''' Removed from version 0.83.x 
( number unitID, number teamID [, boolean isRoot] ) -> nil

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

'''Spring.SetUnitTarget'''
( number unitID,
number enemyUnitID | number x, number y, number z,
[ boolean dgun = false ] ) -> nil

'''Spring.SetUnitBlocking'''
( number unitID, boolean blocking [, boolean collide ] ) -> nil

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

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

'''Spring.SetUnitArmored'''
( number unitID, boolean armored ) -> nil

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

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

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,]
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}

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


'''Spring.SetUnitPieceCollisionVolumeData'''
( number unitID, number pieceIndex, boolean affectLocal, boolean affectGlobal,
boolean enableLocal, boolean enableGlobal, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil

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

'''Spring.SetUnitMoveGoal''' used by default commands to get in build-,attackrange etc.
( number unitID, number x, number y, number z,
[, number radius = 0 [, number speed = unit->maxSpeed * 2 ] ] ) -> nil

'''Spring.SetUnitPhysics'''
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
) -> nil

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

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

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

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

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

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

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


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

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

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

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

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

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

'''Spring.SetUnitLosState'''
( number unitID, number allyTeam, number los | table losTypes ) -> nil
see above for more info on the arguments

'''Spring.SetUnitSensorRadius'''
( number unitID, string type, number radius ) -> nil | number newRadius
type can be:
"los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"

== Unit Ressourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil

possible values for res are: "[u|c][u|m][m|e]"
unconditional | conditional
use | make
metal | energy


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

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

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

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

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

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

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

'''Spring.SetFeatureResurrect'''
( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil

possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3


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

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

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

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

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

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

'''Spring.CallCOBScriptCB''' 
broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

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

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

'''Spring.GetUnitCOBValue'''
( number unitID [, boolean splitData=false], number COBValue
[, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
-> number result | number result1, number result2
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]

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

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

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

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

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

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

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

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

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

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

'''Spring.SetHeightMapFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
'''Spring.AddHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
the terraform argument is a scaling factor:
so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.

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

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

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

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

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil

structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}


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

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

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

'''Spring.SetUnitToFeature'''
( boolean tofeature ) -> nil

'''Spring.SetExperienceGrade'''
( number expGrade
[, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]] ) -> nil

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


'''Spring.SpawnCEG'''
( string "cegname",
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil

= Projectiles =
'''Spring.SetProjectileMoveControl''' (disables engine movecontrol, so lua can fully control the physics)
( number projID, boolean enable ) -> nil
'''Spring.SetProjectilePosition'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileVelocity'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
( number projID ) -> nil
'''Spring.SetProjectileGravity'''
( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle'''
( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed'''
( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
( number projID, string ceg_name ) -> nil

[[category: Lua]]

Lua SyncedRead

2010-09-09T21:46:26Z

Braindamage: added warning about deprecated functions

[[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

=== Rules ===
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!) 
'''Spring.GetRulesInfoMap''' REMOVED in 0.82!
( ) -> { [key1] = string value1, [key2] = string value2, ... }
( string "key" ) -> string

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

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

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

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

=== Speed/Time ===
'''Spring.GetGameSpeed'''
( ) -> number userSpeedFactor, number speedFactor, boolean paused
'''Spring.GetGameFrame'''
( ) -> number frameNum%dayFrames, number frameNum/dayFrames
'''Spring.GetGameSeconds'''
( ) -> number seconds

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

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

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

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

=== Player,Team,Ally Lists/Info ===
'''Spring.GetPlayerList'''
( [number teamID = -1 | boolean onlyActive = false] [, number teamID | boolean onlyActive])
-> nil | { [1] = number playerID, etc... }
'''Spring.GetTeamList'''
( [number allyTeamID = -1] ) -> nil | { [1] = number teamID, etc... }
'''Spring.GetAllyTeamList'''
( ) -> { [1] = number allyTeamID, etc... }

'''Spring.GetPlayerInfo'''
( number playerID ) ->
nil | string "name", (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 ) ->
nil | number teamID, (bug in pre 0.82)
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)

'''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
'''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"

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

=== Unit Informations ===
'''Spring.ValidUnitID'''
( number unitID ) -> boolean
'''Spring.GetUnitIsDead'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitTooltip'''
( number unitID ) -> nil | string tooltip
'''Spring.GetUnitDefID'''
( number unitID ) -> nil | number unitDefID
'''Spring.GetUnitTeam'''
( number unitID ) -> nil | number teamID
'''Spring.GetUnitAllyTeam'''
( number unitID ) -> nil | number allyID
'''Spring.GetUnitLineage''' 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
'''Spring.GetUnitArmored'''
( number unitID ) -> nil | boolean
'''Spring.GetUnitIsStunned'''
( number unitID ) -> nil | boolean stunned_or_inbuild, boolean stunned, boolean inbuild
'''Spring.GetUnitResources'''
( number unitID ) -> nil | number metalMake, number metalUse,
number energyMake, number energyUse
'''Spring.GetUnitMetalExtraction''' 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.GetUnitPosition'''
( number unitID ) -> nil | number x, number y, number z
returns the center position of the unit (midpos).

'''Spring.GetUnitBasePosition'''
( 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
'''Spring.GetUnitHeading'''
( number unitID ) -> nil | number heading
'''Spring.GetUnitVelocity'''
( number unitID ) -> nil | number velx, number vely, number velz
'''Spring.GetUnitBuildFacing'''
( number unitID ) -> nil | number
'''Spring.GetUnitIsBuilding'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitTransporter'''
( number unitID ) -> nil | number unitID
'''Spring.GetUnitIsTransporting'''
( number unitID ) -> nil | { [1] = number unitID, etc... }
'''Spring.GetUnitShieldState'''
( number unitID ) -> 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 |
{ ["los" = true] [, "radar" = true] [, "typed" = true] }
'''Spring.GetUnitSeparation''' (returns the distance of 2 units)
( number unitID1, number unitID2 [, boolean 2D ] ) -> nil | number distance
'''Spring.GetUnitDefDimensions'''
( number unitDefID ) -> nil |
{
"height" = number,
"radius" = number,
"midx" = number,
"minx" = number,
"maxx" = number,
"midy" = number,
"miny" = number,
"maxy" = number,
"midz" = number,
"minz" = number,
"maxz" = number
}
'''Spring.GetUnitWeaponVectors'''
( number unitID, number weaponNum ) -> nil | number posX, number posY, number posZ,
number dirX, number dirY, number dirZ
'''Spring.GetUnitWeaponState'''
( number unitID, number weaponNum ) -> nil |
boolean angleGood, boolean loaded, number reloadFrame, number salvoLeft, number numStockpiled
( number unitID, number weaponNum, string tag ) -> nil | number
`tag` can be:
"reloadState" == "reloadFrame"
"reloadTime"
"accuracy"
"sprayAngle"
"range"
"projectileSpeed"
"burst"
"burstRate"
"projectiles"
'''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 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 },
}
'''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'''
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}

'''Spring.GetCommandQueue''' (same as Spring.GetUnitCommands)
( number unitID [, number count] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.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] ) -> nil | commandQueueTable = {
[1] = {
"id" = number,
"params" = { [1] = number, ...},
"options" = {
"coded" = number,
"alt" = boolean,
"ctrl" = boolean,
"shift" = boolean,
"right" = boolean,
"internal" = boolean,
"meta" = boolean
}
}, ...
}
'''Spring.GetFactoryCounts''' (used to get the buildqueue of a factory, seems screwed o_O)
( number unitID [, number count [, boolean addCMDs ] ] ) -> nil | commandQueueTable = {
[2] = { [number unitDefID | number -cmdID] = number count }, ...
}

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

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

== Features ==
=== GetFeatures ===
'''Spring.GetFeaturesInRectangle'''
( number xmin, number zmin, number xmax, number zmax [,number teamID] )
-> nil | featureTable = { [1] = number featureID, etc... }
'''Spring.GetAllFeatures'''
( ) -> nil | { [1] = number featureID, ... }

=== Feature Informations ===
'''Spring.ValidFeatureID'''
( number featureID ) -> boolean
'''Spring.GetFeatureDefID'''
( number featureID ) -> nil | number featureDefID
'''Spring.GetFeatureTeam'''
( number featureID ) -> nil | number teamID
'''Spring.GetFeatureAllyTeam'''
( number featureID ) -> nil | number allyID
'''Spring.GetFeatureHealth'''
( number featureID ) -> nil | number health, number maxHealth, number resurrectProgress
'''Spring.GetFeatureHeight'''
( number featureID ) -> nil | number
'''Spring.GetFeatureRadius'''
( number featureID ) -> nil | number
'''Spring.GetFeaturePosition'''
( number featureID ) -> nil | number x, number y, number z
'''Spring.GetFeatureDirection'''
( number featureID ) -> nil | number dirx, number diry, number dirz
'''Spring.GetFeatureHeading'''
( number featureID ) -> nil | number heading
'''Spring.GetFeatureResources'''
( number featureID ) -> nil | number RemainingMetal, number maxMetal,
number RemainingEnergy, number maxEnergy, number reclaimLeft
'''Spring.GetFeatureNoSelect'''
( number featureID ) -> nil | boolean noSelect
'''Spring.GetFeatureResurrect'''
( number featureID ) -> nil | string UnitDefName, number buildFacing

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

=== Test Building ===
'''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 != 0 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'''
( number unitDefID, number x, number y, number z ) -> 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'''
( number x, number y, number z [, number allyID] )
-> boolean LosOrRadar, boolean inLos, boolean inRadar
'''Spring.GetClosestValidPosition''' //NOT FINISHED YET
( number unitDefID, number x, number z, number r ) -> nil

== Projectiles ==

'''Spring.GetProjectileName'''
( number projectileID ) -> nil | string name
'''Spring.GetProjectileType'''
( number projectileID ) -> nil | boolean weapon, boolean piece
'''Spring.GetProjectilePosition'''
( number projectileID ) -> nil | number px, number py, number pz
'''Spring.GetProjectileVelocity'''
( number projectileID ) -> nil | number vx, number vy, number vz
'''Spring.GetProjectileGravity'''
( number projectileID ) -> nil | number gravity
'''Spring.GetProjectileSpinAngle'''
( number projectileID ) -> nil | number angle
'''Spring.GetProjectileSpinSpeed'''
( number projectileID ) -> nil | number spinSpeed
'''Spring.GetProjectileSpinVec'''
( number projectileID ) -> nil | number x, number y, number z

[[category: Lua]]

Lua SyncedCtrl

2010-09-09T21:45:52Z

Braindamage: added warning about deprecated functions

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

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

'''Spring.SetTeamResource'''
( number teamID, string res, number amount ) -> nil

possible values for res are:
"m" = metal
"e" = energy
"ms" = metal storage
"es" = energy storage


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

'''Spring.ShareTeamResource''' 0.82 and later
( number teamID_src, number teamID_recv, string "metal" | "energy", number amount ) -> nil

= Unit Handling =
'''Spring.CreateUnit''' note: offmap positions are clamped! (you still can use MoveCtrl todo so)
( string "defName" | number unitDefID,
number x, number y, number z,
(number facing | string "facing"),
number teamID,
[boolean build = false] ) -> number unitID

possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3
if build is true the unit is created in "being built" state, with buildProgress = 0


'''Spring.DestroyUnit'''
( number unitID,
[boolean selfd = false,]
[boolean reclaimed = false,]
[number attackerID] ) -> nil

selfd := makes the unit act like it self-destructed
reclaimed := don't show any DeathSequences, don't leave a wreckage.
NOTE this does _not_ give back the resources to the team!


'''Spring.TransferUnit'''
( number unitID,
numer newTeamID,
[boolean given = true] ) -> nil
if given=false, the unit is captured

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

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

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

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

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

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

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

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

'''Spring.SetUnitLineage''' Removed from version 0.83.x 
( number unitID, number teamID [, boolean isRoot] ) -> nil

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

'''Spring.SetUnitTarget'''
( number unitID,
number enemyUnitID | number x, number y, number z,
[ boolean dgun = false ] ) -> nil

'''Spring.SetUnitBlocking'''
( number unitID, boolean blocking [, boolean collide ] ) -> nil

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

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

'''Spring.SetUnitArmored'''
( number unitID, boolean armored ) -> nil

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

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

'''Spring.SetUnitWeaponState'''
( number unitID, number weaponNum, table states ) -> nil
( number unitID, number weaponNum, string key, number value ) -> nil
format of the states table:
{
["reloadState" = number value,]
["reloadFrame" = number value,] (synonym for reloadState!)
["reloadTime" = number value,]
["accuracy" = number value,]
["sprayAngle" = number value,]
["range" = number value,]
["projectileSpeed" = number value,]
["burst" = number value,]
["burstRate" = number value,]
["projectiles" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}

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


'''Spring.SetUnitPieceCollisionVolumeData'''
( number unitID, number pieceIndex, boolean affectLocal, boolean affectGlobal,
boolean enableLocal, boolean enableGlobal, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetX,
number vType, number tType, number Axis
) -> nil

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

'''Spring.SetUnitMoveGoal''' used by default commands to get in build-,attackrange etc.
( number unitID, number x, number y, number z,
[, number radius = 0 [, number speed = unit->maxSpeed * 2 ] ] ) -> nil

'''Spring.SetUnitPhysics'''
( number unitID,
number posx, number posy, number posz,
number velx, number vely, number velz,
number rotx, number roty, number rotz,
) -> nil

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

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

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

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

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

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

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


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

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

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

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

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

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

'''Spring.SetUnitLosState'''
( number unitID, number allyTeam, number los | table losTypes ) -> nil
see above for more info on the arguments

'''Spring.SetUnitSensorRadius'''
( number unitID, string type, number radius ) -> nil | number newRadius
type can be:
"los","airLos","radar","sonar","seismic","radarJammer","sonarJammer"

== Unit Ressourcing ==
'''Spring.SetUnitResourcing'''
( number unitID,
string res, number amount |
{ res = number amount, ... }
) -> nil

possible values for res are: "[u|c][u|m][m|e]"
unconditional | conditional
use | make
metal | energy


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

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

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

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

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

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

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

'''Spring.SetFeatureResurrect'''
( number featureID, string "UnitDefName?" [, number facing | string "facing" ] ) -> nil

possible values for facing are:
"south" | "s" | 0
"east" | "e" | 1
"north" | "n" | 2
"west" | "w" | 3


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

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

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

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

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

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

'''Spring.CallCOBScriptCB''' 
broken in 0.78.2.1; will be removed with the introduction of Lua as COB replacement
( number unitID, number funcID | string funcName, number retArgs, COBArg1, COBArg2, ... )
-> nil | number returnValue, number CallbackData, number retArg1, number retArg2, ...

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

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

'''Spring.GetUnitCOBValue'''
( number unitID [, boolean splitData=false], number COBValue
[, number param1 [,number param2 [, number param3 [, number param4 ] ] ] ] )
-> number result | number result1, number result2
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]
'''Spring.SetUnitCOBValue'''
( number unitID, number COBValue, number param1 [,number param2] ) -> nil
you find the possible values for `COBValue` in [[Lua_ConstCOB#Get.2FSet|Lua_ConstCOB]]

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

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

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

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

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

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

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

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

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

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

'''Spring.SetHeightMapFunc'''
( lua_function [, arg1 ,[ arg2 [, ... ] ] ) -> nil | number absTotalHeightMapAmountChanged
'''Spring.AddHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height ) -> nil | number newHeight
'''Spring.SetHeightMap''' can only be called in SetHeightMapFunc()
( number x, number z, number height [,number terraform = 1] ) -> nil | number absHeightDiff
the terraform argument is a scaling factor:
so if 0 nothing will be changed (the terraform starts) and if it is 1 the terraform will be finished.

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

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

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

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

'''Spring.EditUnitCmdDesc'''
( number unitID, number cmdDescID, table cmdArray ) -> nil

structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}


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

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

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

'''Spring.SetUnitToFeature'''
( boolean tofeature ) -> nil

'''Spring.SetExperienceGrade'''
( number expGrade
[, number ExpPowerScale [, number ExpHealthScale [, number ExpReloadScale ]]] ) -> nil

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


'''Spring.SpawnCEG'''
( string "cegname",
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0, number damage = 0
) -> nil

= Projectiles =
'''Spring.SetProjectileMoveControl''' (disables engine movecontrol, so lua can fully control the physics)
( number projID, boolean enable ) -> nil
'''Spring.SetProjectilePosition'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileVelocity'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0 ]]] ) -> nil
'''Spring.SetProjectileCollision'''
( number projID ) -> nil
'''Spring.SetProjectileGravity'''
( number projID [, number grav = 0] ) -> nil
'''Spring.SetProjectileSpinAngle'''
( number projID [, number spinAngle = 0] ) -> nil
'''Spring.SetProjectileSpinSpeed'''
( number projID [, number speed = 0] ) -> nil
'''Spring.SetProjectileSpinVec'''
( number projID [, number x = 0 [, number y = 0 [, number z = 0]]] ) -> nil
'''Spring.SetProjectileCEG'''
( number projID, string ceg_name ) -> nil

[[category: Lua]]

Lua ConstGame

2010-09-09T21:44:02Z

Braindamage: added warning about deprecated functions

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

= Engine =
string '''Game.version'''

number '''Game.gameID''' Not implemented as of version 0.81.2.1

number '''Game.maxUnits''' 
number '''Game.maxTeams''' 
number '''Game.maxPlayers''' 
number '''Game.squareSize''' 
number '''Game.gameSpeed'''

= Host =
number '''Game.gameMode''' Removed from version 0.83.x 
number '''Game.startPosType'''

boolean '''Game.commEnds''' Removed from version 0.83.x 
boolean '''Game.limitDGun''' Removed from version 0.83.x 
boolean '''Game.ghostedBuildings'''

= Checksums =
string '''Game.mapChecksum''' 
string '''Game.modChecksum'''

= Map =
bool '''Game.mapDamage''' 
string '''Game.mapName''' 
string '''Game.mapHumanName''' 
number '''Game.mapX''' 
number '''Game.mapY''' 
number '''Game.mapSizeX''' in worldspace/opengl coords 
number '''Game.mapSizeZ''' in worldspace/opengl coords 
number '''Game.gravity''' 
number '''Game.tidal''' 
number '''Game.windMin''' 
number '''Game.windMax''' 
number '''Game.extractorRadius''' 
number '''Game.waterDamage'''

= Mod =
string '''Game.modName''' 
string '''Game.modShortName''' 
string '''Game.modVersion''' 
string '''Game.modMutator''' 
string '''Game.modDesc'''

boolean '''Game.allowTeamColors''' 
number '''Game.transportAir''' 
number '''Game.transportShip''' 
number '''Game.transportHover''' 
number '''Game.transportGround''' 
number '''Game.fireAtKilled''' 
number '''Game.fireAtCrashing''' 
boolean '''Game.requireSonarUnderWater'''

= Constructor =
boolean '''Game.constructionDecay''' 
number '''Game.constructionDecayTime''' 
number '''Game.constructionDecaySpeed''' 

number '''Game.multiReclaim''' 
number '''Game.reclaimMethod''' 
number '''Game.reclaimUnitMethod''' 
number '''Game.reclaimUnitEnergyCostFactor''' 
number '''Game.reclaimUnitEfficiency''' 
number '''Game.reclaimFeatureEnergyCostFactor''' 
boolean '''Game.reclaimAllowEnemies''' 
boolean '''Game.reclaimAllowAllies''' 
number '''Game.repairEnergyCostFactor''' 
number '''Game.resurrectEnergyCostFactor''' 
number '''Game.captureEnergyCostFactor'''

= Categories =
table '''Game.springCategories'''

example: {
["vtol"] = 0, ["special"] = 1, ["noweapon"] = 2,
["notair"] = 3, ["notsub"] = 4, ["all"] = 5,
["weapon"] = 6, ["notship"] = 7, ["notland"] = 8,
["mobile"] = 9, ["kbot"] = 10, ["antigator"] = 11,
["tank"] = 12, ["plant"] = 13, ["ship"] = 14,
["antiemg"] = 15, ["antilaser"] = 16, ["antiflame"] = 17,
["underwater"] = 18, ["hover"] = 19, ["phib"] = 20,
["constr"] = 21, ["strategic"] = 22, ["commander"] = 23,
["paral"] = 24, ["jam"] = 25, ["mine"] = 26,
["kamikaze"] = 27, ["minelayer"] = 28, ["notstructure"] = 29,
["air"] = 30
}
table '''Game.armorTypes''' (bidirectional)

example: {
[1] = amphibious, [2] = anniddm, [3] = antibomber,
[4] = antifighter, [5] = antiraider, [6] = atl,
[7] = blackhydra, [8] = bombers, [9] = commanders,
[10] = crawlingbombs, ...

["amphibious"] = 1, ["anniddm"] = 2, ["antibomber"] = 3
["antifighter"] = 4, ["antiraider"] = 5, ["atl"] = 6
["blackhydra"] = 7, ["bombers"] = 8, ["commanders"] = 9
["crawlingbombs"]= 10, ...
}

= Water Visuals =
boolean '''Game.waterVoid''' 
boolean '''Game.waterPlane''' 
string '''Game.waterTexture''' 
number '''Game.waterRepeatX''' 
number '''Game.waterRepeatY''' 
string '''Game.waterFoamTexture''' 
string '''Game.waterNormalTexture''' 
table '''Game.waterCausticTextures''' = {"tex1","tex2",..} 
color '''Game.waterAbsorb''' = { number r, number g, number b} 
color '''Game.waterBaseColor''' 
color '''Game.waterMinColor''' 
color '''Game.waterSurfaceColor''' 
number '''Game.waterSurfaceAlpha''' 
color '''Game.waterSpecularColor''' 
number '''Game.waterSpecularFactor''' 
color '''Game.waterPlaneColor''' 
number '''Game.waterFresnelMin''' 
number '''Game.waterFresnelMax''' 
number '''Game.waterFresnelPower''' 
color '''Game.fogColor''' 
color '''Game.groundAmbientColor''' 
color '''Game.groundSpecularColor''' 
color '''Game.groundSunColor'''

[[category: Lua]]

Simple Game Tutorial

2010-08-23T11:54:22Z

Braindamage: added comment about filename vs unitsync name for dependency

Until I Finish [[Mod Development]] is the place to go.

This Tutorial Aims to get a person from knowing nothing about Spring to the point where they can create and edit mods.

Right now I am working from memory so you may want to correct me when I'm wrong, I will try to cross link from my summaries to the appropriate articles available in other places.

I will not go too deep into making 3do's because they are old and dumb... but I'll try to make note of the differences here.

I don't know anything about scripting right now, so that section is likely to be sparse when I write it, I hope that someone will expand on it.

=Book 1: The First Unit=

==Step 1:Planning==
Who cares about planning, you know what you're doing... just come up with an idea for a mod... I made a chess set... if you don't have a real idea and just want to make a model show up in the game... then yeah... this is the place to start... I'd do that if I were you.

Another good thing to do at this point is to creat a "working directory", and inside it create a directory with the name that your mod will have... after many headaches I decided it's best to put this in the root directory of your system so it's really easy to find when you are switching around back and forth between folders and keep having to find your files over and over again.

==Step 2:Getting The Tools==
You will need a bunch of stuff... here's the list (I assume you are using windows)

''Want:''
*[http://taspring.clan-sy.com/download.php Spring] - The main program, you will likely need this to test if you've screwed up
*A Tiny Map (2x2) - to test your mod fast (suggest [http://www.fileuniverse.com/?p=showitem&ID=2534 Simple Chess Map])

''Need:''
*'''Program listings can be found here:''' '''[http://taspring.clan-sy.com/wiki/Map%2C_Mod%2C_And_Unit_Development_Programs Map, Mod, And Unit Development Programs]'''
*3D Modeling Program - '''See above link'''
*Notepad - to edit all the miriad of text files
*A Graphical Editing Program - needs to handle RGBA TGAs (aka tga's with alpha channels), I suggest Photoshop if you have it, or The GIMP... needed for all of the texture making for UVmapping stuff... '''See above link'''
*Upspring 1.3 - To convert your models to the approprite s3o format (if you want to fight with 3do builder, then go ahead... a good trick is to get your model into upspring first and adjust all the hierachy, then save it as an 3do... but why bother?). '''See above link'''
*Scriptor - to make and compile your units "animation script"... or steal someone else's and make it work for your unit. '''See above link'''
*Compression Utility - (I suggest [http://www.7-zip.org/ 7zip] - even if you are using zip compression and not 7zip, it's still good to have)

==Step 3:Making a 3D Model==

Go into your 3D modelling program and make a 3D model, [http://taspring.clan-sy.com/w/images/b/b4/WingsCombine.PNG combine] all the objects and UV map the model, then separate it out into any parts that need to move independently of each other. Then Export the UV map as an Image File and Export the whole thing as a 3ds file. Put the original wings file, the UVMap image and the 3ds file into your working directory so you can find them later.

Wings 3D UV Mapping tutorial has been started here - [[Units:CreateModel]]

==Step 4:Fixing Your Images==

[[Basic s3o unit making guide|This Article includes a UVMapping Guide]]

Open up your UVMap in Photoshop (or whatever) go to the layer/chooser thingy and go to the Channels Tab, add a new layer (it should default to alpha) and fill it with 99% black so you can see your texture in upspring. If you want to can paint the UVmap and put white (1% black) on the alpha channel where you want your team colours to show up (you can use something between 1% and 99% to get a blend of your team colour along with the texture... for example 50% will give you your texture with 50% of the team colour mixed in...)

I don't know how to do glow maps... XXreminder for someone to create a Glowmapping tutorial... you don't acctually need one for the model to show up.

Save these images both in the working directory.

Save a copy of these images in tga format into <working directory>/<mod name>/unittextures

==Step 5:Upspring==

===Importing Your 3ds===
Open Upspring 1.3, go to file>load model and navigate to and open your 3DS model you exported, you should see the model in upspring as a 3d mesh. Go to the model tab and set the radius and height values to something other then zero... this defines where the health bar will show up, and more importantly, how big the collision sphere will be.

You will also need to use all of the other tools on those tabs to resize and rotate and move your model to the right place... wings makes models that are 90 degrees off and about 30 times smaller than most spring models... make sure you click the "apply transform" button after any changes that you actually want to show up in the game.

Also, you will want to make the hierachy work using the cut, paste, and add empty buttons. You will need an object called "base" that all the other objects are connected to... the "origin object"... sometimes you get lucky and wings exports it properly... usually not.

===Importing Your UV and Glowmaps===

Go to the textures tab and make your UV/texture/team-colour map as "texture1" and your UV/glow/reflectivity map as "texture2"... it should show up correctly in the preview pane.

===Exporting Your s3o===
Choose File>Save Model As then in the drop down select "s3o" and type an appropriate name. This model should be saved to your working directory, and a copy of it made to <working directory>/<mod name>/objects3d/

==Step 6: Lua files==

===UnitName.lua===


<pre>
unitDef = {
unitname = [[arm_spider]],
name = [[Weaver]],
description = [[Cloaking Construction Spider, Builds at 9 m/s]],
acceleration = 0.15,
bmcode = [[1]],
brakeRate = 0.15,
buildCostEnergy = 230,
buildCostMetal = 230,
buildDistance = 80,
builder = true,

buildoptions = {
},

buildPic = [[arm_spider.png]],
buildTime = 230,
canAttack = false,
canGuard = true,
canMove = true,
canPatrol = true,
canreclamate = [[1]],
canstop = [[1]],
category = [[LAND UNARMED]],
cloakCost = 1,
cloakCostMoving = 2,
corpse = [[DEAD]],

customParams = {
description_bp = [[Aranha e de construÃƒÂ§?o, ConstrÃƒÂ³i a 6 m/s]],
description_es = [[Ara?a de construcciÃƒÂ³n, construye a 6 m/s]],
description_fi = [[Rakentaja/kaikuluotainkiipeilij?, rakentaa 6m/s nopeudella]],
description_fr = [[Araign?e de Construction, Construit ? 6 m/s]],
description_it = [[Ragno do costruzione occultante, costruisce a 6 m/s]],
description_pl = [[Paj?k konstruktor, buduje z pr?dko?ci? 6m/s]],
helptext = [[The Weaver is a constructor that can climb over any obstacle and build defenses on high ground.]],
helptext_bp = [[Weaver ÃƒÂ© o construtor escalador camuflÃƒÂ¡vel de NOVA. Pode subir qualquer obstÃƒÂ¡culo, mas constrÃƒÂ³i mais devagar que construtores normais.]],
helptext_es = [[El Weaver es el constructor que puede treparse sobre qualquier obstÃƒÂ¡culo y construir defensas en terreno alto]],
helptext_fi = [[Weaver pystyy liikkumaan vaikeakulkuisimmassakin maastossa ja rakentamaan vaivatta my?s useimmille muille rakentajille saavuttamattomiin paikkoihin.]],
helptext_fr = [[Le weaver est un robot de construction tout terrain qui peut batir des d?fenses en terrain ?lev?.]],
helptext_it = [[Il Weaver ÃƒÂ© un costruttore che puo arrampicarsi su qualunque ostacolo e costruire difese nel terreno alto]],
helptext_pl = [[Weaver jest konstruktorem mog?cym wspina? si? po ka?dej powierzchni oraz posiadaj?cym mo?liwo?? maskowania si?]],
},

defaultmissiontype = [[Standby]],
designation = [[ARM-MLSPD]],
energyMake = 0.15,
energyUse = 0,
explodeAs = [[BIG_UNITEX]],
footprintX = 3,
footprintZ = 3,
iconType = [[builder]],
mass = 115,
maxDamage = 750,
maxslope = 16,
maxSlope = 72,
maxVelocity = 1.7,
maxWaterDepth = 22,
metalMake = 0.15,
movementClass = [[TKBOT3]],
noAutoFire = false,
noChaseCategory = [[TERRAFORM SATELLITE FIXEDWING GUNSHIP HOVER SHIP SWIM SUB LAND FLOAT SINK]],
objectName = [[ARMMLSPD]],
radarDistanceJam = 256,
seismicSignature = 16,
selfDestructAs = [[BIG_UNITEX]],
showNanoSpray = false,
side = [[ARM]],
sightDistance = 295,
smoothAnim = true,
steeringmode = [[1]],
TEDClass = [[CNSTR]],
terraformSpeed = 450,
threed = [[1]],
turninplace = 0,
turnRate = 1020,
workerTime = 9,
zbuffer = [[1]],

featureDefs = {

DEAD = {
description = [[Wreckage - Weaver]],
blocking = true,
category = [[arm_corpses]],
damage = 850,
featureDead = [[DEAD2]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[40]],
hitdensity = [[100]],
metal = 92,
object = [[ARMMLSPD_dead]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

DEAD2 = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featureDead = [[HEAP]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 92,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

HEAP = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 46,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 46,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

},

}

return lowerkeys({ arm_spider = unitDef })
</pre>

Save this file as a lua file in <working directory>/<mod name>/units/

===modinfo.lua===

modinfo.lua is a lua file that defines a number of things that are used when loading a mod, most of the information is self explanitory but basically what you are doing is defining what is going to show up in whatever mod-selection interface you use as well as what other files need to be loaded into memory in order for your mod to work.

====Making a New Mod with your unit/units====
The following is an example of what will be in your modinfo.lua file if you are starting from scratch and making your own mod. This is also good when you are just testing one unit to see if it works.

<pre>
return {
-- The name is shown in the selection interface
game = "MyMod",
shortGame = "MM",
name = "My Mod",
shortName = "MM",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "My Mod That I Made",
url = "http://www.theplacepeoplecangetthelatestversionofyourmod.com",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
"Spring content v1",
"Spring Cursors",
"Spring Bitmaps",
-- Number of other content names this one replaces
added comment about filename vs unitsync name for dependency
},
}
</pre>

====Adding Your Unit to an Existing Mod====
The following is an example of what will be in your modinfo.lua file if you are adding new units to an existing mod (in this case XTA SE v066), this is good for adding units to the build tree of an existing mod or adding a whole new team.

<pre>
-- Description of the mod control file recognized by spring:
return {
-- The name is shown in the selection interface
game = "XTASE_MyUnits",
shortGame = "XTASEMU",
name = "XTASEv0.66 with+My Units",
shortName = "XTASEMU",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "xta_se_v066 with the cool tank I made",
url = "http://www.fileuniverse.com/exactlocationblahblahblah",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
"XTAsev066",
"Spring Cursors",
"Spring content v1",
-- Number of other archives this one replaces
--do not used filenames, use the internal name, or downloader programs will fail to download the dependencies automatically
},
}
</pre>

If you are not depending on OTA files, you will have to supply your own cursors.

There are some extra bits in these examples, but I work on the "better safe than sorry" principle... which is to wait for someone who knows what they are doing to fix my articles.

You will want to save this file as plain text in <working directory>/<mod name>/

===armorDefs.lua===

I'm not exactly sure how this works, but the file needs to exist, so either steal one from another mod and modify it... or just make a file that looks like this.

<pre>
local armorDefs = {
}
</pre>

You will want to save this file as a lua file in <working directory>/<mod name>/gamedata

===sidedata.lua===

Start by stealing the sidedata.lua file from your dependency mod if you have one, then edit it to include your units/side.

Basically this file is in the form:

<pre>
local sideData = {
[1] = {
name = 'Good Guys',
startunit = 'GG_comm',
},
}
</pre>

There are also additional "[X]" entries for each side/team/commander-choice available in the mod-selector you choose.

You will save this file as lua file in <working directory>/<mod name>/gamedata/

===moveDefs.lua===
This file determines the footprint of your units, the angle of slopes they can climb and in how deep water they can drive. It contains several entries, all in the following format:

<pre>
local moveDefs = {
KBOT1 = { -- This is the name. Unit files refer to this name.
footprintx = 1, -- This is how big the X dimension is of the footprint in Spring units probably?
footprintz = 1, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxwaterdepth = 15, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxslope = 36, -- The maximum angle of slopes this unit can climb.
crushstrength = 5, -- This determines if the unit/unit class can crush certain features
},
-- etc..
}
</pre>

===sounds.lua===
This file refers to all the sounds your units make, so Spring knows which sound file is linked to what action. It contains entries in the following format.

<pre>
local Sounds = {
SoundItems = {
IncomingChat = {
file = "sounds/nexuiz/talk.wav",
priority = 15,
preload = true,
},
MultiSelect = {
file = "sounds/ota/button9.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
MapPoint = {
file = "sounds/bzflag/teamgrab.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
FailedCommand = {
file = "sounds/openQuarz/pkup.wav",
gain = 0.75,
priority = 15,
preload = true,
in3d = false,
},
}
</pre>
}

==Step 7:Adding a Build Pic==

Add a 96x96 BMP to your <working directory>/<mod name>/unitpics/ folder named either "UnitName.bmp" or whatever you specified in the "BuildPic=" line of your fbi.

==Step 8:Adding a Side Pic==

Add a 16x16 BMP to your <working directory>/<mod name>/sidepics/ folder named "teamname.bmp" or whatever you specified in the "name=" line of your SIDEDATA.TDF for each side/team you have added.

==Step 9:Scriptor==

===Stealing a Script===
Open someone else's script in scriptor that works the way you want your script to work, look at the top where it's talking about "piece names"... then change those piece names to be the piece names of your unit and do a find/replace to make all the places where those pieces show up to be your pieces too. Compile it so its name is the same as the "UnitName=" value in your "UnitName.fbi".

XXreminder to someone to link to a proper scripting tutorial

Put the bos and cob files for your unit script in <working directory>/<mod name>/scripts

==Step 10:Compiling Your Mod==

You may want to check your mod directory and make sure it follows the structure defined [[Mod_Development:Archives|here]].

navigate to your <working directory>/<mod name> and select everything and choose "add to archive <mod name>.7z".

make a copy of this file called <mod name>v0.7z in your working directory so you don't screw anything up later, then make a copy of it called <mod name>.sd7 in the mods directory of spring.

An alternative, added in more recent versions is the ".SDD" folder, to use this, copy the entire <mod name> folder in the mods directory of spring and rename it as "<mod name>.SDD". The advantage to the ".SDD" method is that you can tweak settings and add files without recompressing your mod all the time. When it comes time to distribute your mod use ".sd7".

EXAMPLES:
If your mod is called JoesMod you will have a file called "JoesMod.sd7" or a folder called "JoesMod.SDD" in your spring mods directory.

==Step 11:Testing Your Mod==
Open Up your lobby client, pick your mod from the drop-down list of the games in host battle or singleplayer mode if your lobby supports it(if it doesn't show up you screwed up your modinfo.txt), choose your tiny map from the map list and press start. If it doesn't break and your unit shows up, you have created all the neccessary files... yay!

Gotchas:
*If it doesn't work, check you didn't zip the folder itself, but the contents, ie if you open mymod.sd7 with 7zip, you should see folders such as "unittextures" rather than a folder "mymod" containing unittextures.

[[Category:Mod development]]

Simple Game Tutorial

2010-08-23T11:54:04Z

Braindamage: added comment about filename vs unitsync name for dependency

Until I Finish [[Mod Development]] is the place to go.

This Tutorial Aims to get a person from knowing nothing about Spring to the point where they can create and edit mods.

Right now I am working from memory so you may want to correct me when I'm wrong, I will try to cross link from my summaries to the appropriate articles available in other places.

I will not go too deep into making 3do's because they are old and dumb... but I'll try to make note of the differences here.

I don't know anything about scripting right now, so that section is likely to be sparse when I write it, I hope that someone will expand on it.

=Book 1: The First Unit=

==Step 1:Planning==
Who cares about planning, you know what you're doing... just come up with an idea for a mod... I made a chess set... if you don't have a real idea and just want to make a model show up in the game... then yeah... this is the place to start... I'd do that if I were you.

Another good thing to do at this point is to creat a "working directory", and inside it create a directory with the name that your mod will have... after many headaches I decided it's best to put this in the root directory of your system so it's really easy to find when you are switching around back and forth between folders and keep having to find your files over and over again.

==Step 2:Getting The Tools==
You will need a bunch of stuff... here's the list (I assume you are using windows)

''Want:''
*[http://taspring.clan-sy.com/download.php Spring] - The main program, you will likely need this to test if you've screwed up
*A Tiny Map (2x2) - to test your mod fast (suggest [http://www.fileuniverse.com/?p=showitem&ID=2534 Simple Chess Map])

''Need:''
*'''Program listings can be found here:''' '''[http://taspring.clan-sy.com/wiki/Map%2C_Mod%2C_And_Unit_Development_Programs Map, Mod, And Unit Development Programs]'''
*3D Modeling Program - '''See above link'''
*Notepad - to edit all the miriad of text files
*A Graphical Editing Program - needs to handle RGBA TGAs (aka tga's with alpha channels), I suggest Photoshop if you have it, or The GIMP... needed for all of the texture making for UVmapping stuff... '''See above link'''
*Upspring 1.3 - To convert your models to the approprite s3o format (if you want to fight with 3do builder, then go ahead... a good trick is to get your model into upspring first and adjust all the hierachy, then save it as an 3do... but why bother?). '''See above link'''
*Scriptor - to make and compile your units "animation script"... or steal someone else's and make it work for your unit. '''See above link'''
*Compression Utility - (I suggest [http://www.7-zip.org/ 7zip] - even if you are using zip compression and not 7zip, it's still good to have)

==Step 3:Making a 3D Model==

Go into your 3D modelling program and make a 3D model, [http://taspring.clan-sy.com/w/images/b/b4/WingsCombine.PNG combine] all the objects and UV map the model, then separate it out into any parts that need to move independently of each other. Then Export the UV map as an Image File and Export the whole thing as a 3ds file. Put the original wings file, the UVMap image and the 3ds file into your working directory so you can find them later.

Wings 3D UV Mapping tutorial has been started here - [[Units:CreateModel]]

==Step 4:Fixing Your Images==

[[Basic s3o unit making guide|This Article includes a UVMapping Guide]]

Open up your UVMap in Photoshop (or whatever) go to the layer/chooser thingy and go to the Channels Tab, add a new layer (it should default to alpha) and fill it with 99% black so you can see your texture in upspring. If you want to can paint the UVmap and put white (1% black) on the alpha channel where you want your team colours to show up (you can use something between 1% and 99% to get a blend of your team colour along with the texture... for example 50% will give you your texture with 50% of the team colour mixed in...)

I don't know how to do glow maps... XXreminder for someone to create a Glowmapping tutorial... you don't acctually need one for the model to show up.

Save these images both in the working directory.

Save a copy of these images in tga format into <working directory>/<mod name>/unittextures

==Step 5:Upspring==

===Importing Your 3ds===
Open Upspring 1.3, go to file>load model and navigate to and open your 3DS model you exported, you should see the model in upspring as a 3d mesh. Go to the model tab and set the radius and height values to something other then zero... this defines where the health bar will show up, and more importantly, how big the collision sphere will be.

You will also need to use all of the other tools on those tabs to resize and rotate and move your model to the right place... wings makes models that are 90 degrees off and about 30 times smaller than most spring models... make sure you click the "apply transform" button after any changes that you actually want to show up in the game.

Also, you will want to make the hierachy work using the cut, paste, and add empty buttons. You will need an object called "base" that all the other objects are connected to... the "origin object"... sometimes you get lucky and wings exports it properly... usually not.

===Importing Your UV and Glowmaps===

Go to the textures tab and make your UV/texture/team-colour map as "texture1" and your UV/glow/reflectivity map as "texture2"... it should show up correctly in the preview pane.

===Exporting Your s3o===
Choose File>Save Model As then in the drop down select "s3o" and type an appropriate name. This model should be saved to your working directory, and a copy of it made to <working directory>/<mod name>/objects3d/

==Step 6: Lua files==

===UnitName.lua===


<pre>
unitDef = {
unitname = [[arm_spider]],
name = [[Weaver]],
description = [[Cloaking Construction Spider, Builds at 9 m/s]],
acceleration = 0.15,
bmcode = [[1]],
brakeRate = 0.15,
buildCostEnergy = 230,
buildCostMetal = 230,
buildDistance = 80,
builder = true,

buildoptions = {
},

buildPic = [[arm_spider.png]],
buildTime = 230,
canAttack = false,
canGuard = true,
canMove = true,
canPatrol = true,
canreclamate = [[1]],
canstop = [[1]],
category = [[LAND UNARMED]],
cloakCost = 1,
cloakCostMoving = 2,
corpse = [[DEAD]],

customParams = {
description_bp = [[Aranha e de construÃƒÂ§?o, ConstrÃƒÂ³i a 6 m/s]],
description_es = [[Ara?a de construcciÃƒÂ³n, construye a 6 m/s]],
description_fi = [[Rakentaja/kaikuluotainkiipeilij?, rakentaa 6m/s nopeudella]],
description_fr = [[Araign?e de Construction, Construit ? 6 m/s]],
description_it = [[Ragno do costruzione occultante, costruisce a 6 m/s]],
description_pl = [[Paj?k konstruktor, buduje z pr?dko?ci? 6m/s]],
helptext = [[The Weaver is a constructor that can climb over any obstacle and build defenses on high ground.]],
helptext_bp = [[Weaver ÃƒÂ© o construtor escalador camuflÃƒÂ¡vel de NOVA. Pode subir qualquer obstÃƒÂ¡culo, mas constrÃƒÂ³i mais devagar que construtores normais.]],
helptext_es = [[El Weaver es el constructor que puede treparse sobre qualquier obstÃƒÂ¡culo y construir defensas en terreno alto]],
helptext_fi = [[Weaver pystyy liikkumaan vaikeakulkuisimmassakin maastossa ja rakentamaan vaivatta my?s useimmille muille rakentajille saavuttamattomiin paikkoihin.]],
helptext_fr = [[Le weaver est un robot de construction tout terrain qui peut batir des d?fenses en terrain ?lev?.]],
helptext_it = [[Il Weaver ÃƒÂ© un costruttore che puo arrampicarsi su qualunque ostacolo e costruire difese nel terreno alto]],
helptext_pl = [[Weaver jest konstruktorem mog?cym wspina? si? po ka?dej powierzchni oraz posiadaj?cym mo?liwo?? maskowania si?]],
},

defaultmissiontype = [[Standby]],
designation = [[ARM-MLSPD]],
energyMake = 0.15,
energyUse = 0,
explodeAs = [[BIG_UNITEX]],
footprintX = 3,
footprintZ = 3,
iconType = [[builder]],
mass = 115,
maxDamage = 750,
maxslope = 16,
maxSlope = 72,
maxVelocity = 1.7,
maxWaterDepth = 22,
metalMake = 0.15,
movementClass = [[TKBOT3]],
noAutoFire = false,
noChaseCategory = [[TERRAFORM SATELLITE FIXEDWING GUNSHIP HOVER SHIP SWIM SUB LAND FLOAT SINK]],
objectName = [[ARMMLSPD]],
radarDistanceJam = 256,
seismicSignature = 16,
selfDestructAs = [[BIG_UNITEX]],
showNanoSpray = false,
side = [[ARM]],
sightDistance = 295,
smoothAnim = true,
steeringmode = [[1]],
TEDClass = [[CNSTR]],
terraformSpeed = 450,
threed = [[1]],
turninplace = 0,
turnRate = 1020,
workerTime = 9,
zbuffer = [[1]],

featureDefs = {

DEAD = {
description = [[Wreckage - Weaver]],
blocking = true,
category = [[arm_corpses]],
damage = 850,
featureDead = [[DEAD2]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[40]],
hitdensity = [[100]],
metal = 92,
object = [[ARMMLSPD_dead]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

DEAD2 = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featureDead = [[HEAP]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 92,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

HEAP = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 46,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 46,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

},

}

return lowerkeys({ arm_spider = unitDef })
</pre>

Save this file as a lua file in <working directory>/<mod name>/units/

===modinfo.lua===

modinfo.lua is a lua file that defines a number of things that are used when loading a mod, most of the information is self explanitory but basically what you are doing is defining what is going to show up in whatever mod-selection interface you use as well as what other files need to be loaded into memory in order for your mod to work.

====Making a New Mod with your unit/units====
The following is an example of what will be in your modinfo.lua file if you are starting from scratch and making your own mod. This is also good when you are just testing one unit to see if it works.

<pre>
return {
-- The name is shown in the selection interface
game = "MyMod",
shortGame = "MM",
name = "My Mod",
shortName = "MM",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "My Mod That I Made",
url = "http://www.theplacepeoplecangetthelatestversionofyourmod.com",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
"Spring content v1",
"Spring Cursors",
"Spring Bitmaps",
-- Number of other content names this one replaces
},
}
</pre>

====Adding Your Unit to an Existing Mod====
The following is an example of what will be in your modinfo.lua file if you are adding new units to an existing mod (in this case XTA SE v066), this is good for adding units to the build tree of an existing mod or adding a whole new team.

<pre>
-- Description of the mod control file recognized by spring:
return {
-- The name is shown in the selection interface
game = "XTASE_MyUnits",
shortGame = "XTASEMU",
name = "XTASEv0.66 with+My Units",
shortName = "XTASEMU",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "xta_se_v066 with the cool tank I made",
url = "http://www.fileuniverse.com/exactlocationblahblahblah",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
"XTAsev066",
"Spring Cursors",
"Spring content v1",
-- Number of other archives this one replaces
--do not used filenames, use the internal name, or downloader programs will fail to download the dependencies automatically
},
}
</pre>

If you are not depending on OTA files, you will have to supply your own cursors.

There are some extra bits in these examples, but I work on the "better safe than sorry" principle... which is to wait for someone who knows what they are doing to fix my articles.

You will want to save this file as plain text in <working directory>/<mod name>/

===armorDefs.lua===

I'm not exactly sure how this works, but the file needs to exist, so either steal one from another mod and modify it... or just make a file that looks like this.

<pre>
local armorDefs = {
}
</pre>

You will want to save this file as a lua file in <working directory>/<mod name>/gamedata

===sidedata.lua===

Start by stealing the sidedata.lua file from your dependency mod if you have one, then edit it to include your units/side.

Basically this file is in the form:

<pre>
local sideData = {
[1] = {
name = 'Good Guys',
startunit = 'GG_comm',
},
}
</pre>

There are also additional "[X]" entries for each side/team/commander-choice available in the mod-selector you choose.

You will save this file as lua file in <working directory>/<mod name>/gamedata/

===moveDefs.lua===
This file determines the footprint of your units, the angle of slopes they can climb and in how deep water they can drive. It contains several entries, all in the following format:

<pre>
local moveDefs = {
KBOT1 = { -- This is the name. Unit files refer to this name.
footprintx = 1, -- This is how big the X dimension is of the footprint in Spring units probably?
footprintz = 1, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxwaterdepth = 15, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxslope = 36, -- The maximum angle of slopes this unit can climb.
crushstrength = 5, -- This determines if the unit/unit class can crush certain features
},
-- etc..
}
</pre>

===sounds.lua===
This file refers to all the sounds your units make, so Spring knows which sound file is linked to what action. It contains entries in the following format.

<pre>
local Sounds = {
SoundItems = {
IncomingChat = {
file = "sounds/nexuiz/talk.wav",
priority = 15,
preload = true,
},
MultiSelect = {
file = "sounds/ota/button9.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
MapPoint = {
file = "sounds/bzflag/teamgrab.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
FailedCommand = {
file = "sounds/openQuarz/pkup.wav",
gain = 0.75,
priority = 15,
preload = true,
in3d = false,
},
}
</pre>
}

==Step 7:Adding a Build Pic==

Add a 96x96 BMP to your <working directory>/<mod name>/unitpics/ folder named either "UnitName.bmp" or whatever you specified in the "BuildPic=" line of your fbi.

==Step 8:Adding a Side Pic==

Add a 16x16 BMP to your <working directory>/<mod name>/sidepics/ folder named "teamname.bmp" or whatever you specified in the "name=" line of your SIDEDATA.TDF for each side/team you have added.

==Step 9:Scriptor==

===Stealing a Script===
Open someone else's script in scriptor that works the way you want your script to work, look at the top where it's talking about "piece names"... then change those piece names to be the piece names of your unit and do a find/replace to make all the places where those pieces show up to be your pieces too. Compile it so its name is the same as the "UnitName=" value in your "UnitName.fbi".

XXreminder to someone to link to a proper scripting tutorial

Put the bos and cob files for your unit script in <working directory>/<mod name>/scripts

==Step 10:Compiling Your Mod==

You may want to check your mod directory and make sure it follows the structure defined [[Mod_Development:Archives|here]].

navigate to your <working directory>/<mod name> and select everything and choose "add to archive <mod name>.7z".

make a copy of this file called <mod name>v0.7z in your working directory so you don't screw anything up later, then make a copy of it called <mod name>.sd7 in the mods directory of spring.

An alternative, added in more recent versions is the ".SDD" folder, to use this, copy the entire <mod name> folder in the mods directory of spring and rename it as "<mod name>.SDD". The advantage to the ".SDD" method is that you can tweak settings and add files without recompressing your mod all the time. When it comes time to distribute your mod use ".sd7".

EXAMPLES:
If your mod is called JoesMod you will have a file called "JoesMod.sd7" or a folder called "JoesMod.SDD" in your spring mods directory.

==Step 11:Testing Your Mod==
Open Up your lobby client, pick your mod from the drop-down list of the games in host battle or singleplayer mode if your lobby supports it(if it doesn't show up you screwed up your modinfo.txt), choose your tiny map from the map list and press start. If it doesn't break and your unit shows up, you have created all the neccessary files... yay!

Gotchas:
*If it doesn't work, check you didn't zip the folder itself, but the contents, ie if you open mymod.sd7 with 7zip, you should see folders such as "unittextures" rather than a folder "mymod" containing unittextures.

[[Category:Mod development]]

Game specification

2010-08-23T11:52:40Z

Braindamage: use unitsync names, not filenames!

===Overview===

This is a specification of how Spring will support mods and switching between them.

Spring looks for games in the folders "maps", "base" and "mods", and all their subfolders. It is recommended to put your game in a subfolder of /mods. Spring supports multiple subfolders within /mods: '''/mods/my_nifty_game/game.sdd''' and '''/mods/my_nifty_game/game_support.sdz''' are both correct.

On startup, Spring will search these folders and their subfolders for files called "modinfo.lua". This file declares all ''dependencies'' of this game, such as additional graphics, sounds and the like.

The general idea is that this file should be used as a manifest file to let Spring know what to do with the archive it is found inside, so each archive file in the mods directory is supposed to have one. Archive files that do not contain this file are ignored, and aren't available to Spring's Virtual File System.

===Modinfo.lua Example===
Modinfo.lua, like any Lua language file, can contain active code, should you want it to. But it is mainly just designed to refer Spring's Virtual File System (VFS) to the correct game files and any dependencies of your project.

Here is an example:

<pre>return
{
game='myNiftyGame',
shortGame='mNg',
name='My Nifty Game',
mutator='official',
version='1.0',
description='The Awesome Game I Made.',
url='http://www.my_nifty_url.com/',
modtype=1,
depend= {
"Content 1",
"Content 2",
--do not used filenames, use the internal name, or downloader programs will fail to download the dependencies automatically
},
}</pre>

'''Dependencies''' are files that your game depends on to operate. This may be anything- a map, another game, a folder named "my_nifty_sounds.sdd" that has a bunch of sounds in it and a modinfo.lua file to identify it as a valid file archive to Spring- basically anything goes, so long as it, like your game, is identified as a usable archive by having a modinfo.lua file in it.

These files are loaded in the order listed. So if depend02.sdd contains a file with the same name as depend01.sdd, it will overwrite that file.

'''Modtype''' determines whether Spring's archive system sees the game as a game, or as an "invisible" file that can only be called as a Dependency. If set to any number except for 1, it will not be visible to end-users as a "game", but you can still refer to it in the depend table.

===Replacements===

When releasing new versions of a mod it is recommended that a new unique filename is used. In this manner it would be possible for the lobby to download archives from a fast webserver based on the filename.

But if a new name is used for a support archive with content for example, it would break other mods that depend on the archive. To avoid this, replacements can be used.

Replacements simply specifies which other archives this one replaces. So if a new archive specifies that it replaces old_archive.sdz, any other mod that depends on old_archive.sdz would now use the new one instead.

It is probably not always a good idea to use this for new versions of a mod however, since if you hide the old version people would not be able to switch between the old and the new version. So only use replacements when you are sure that it is what you want.

===Distribution===

If a player does not have a certain game's files when trying to join a game online, the Lobbies are designed to let them know that they don't have the game. If you have uploaded your game to the various services that are supported by the Lobby applications, players can automatically download the game. Also, SpringDownloader allows players to share the game's file with others easily. Modinfo.lua lets both the Lobby application and Spring know what your game is, and whether it "knows" where it can be downloaded from.

[[Category:Mod development]]

Simple Game Tutorial

2010-08-23T11:50:45Z

Braindamage: user unitsync names, not filenames!

Until I Finish [[Mod Development]] is the place to go.

This Tutorial Aims to get a person from knowing nothing about Spring to the point where they can create and edit mods.

Right now I am working from memory so you may want to correct me when I'm wrong, I will try to cross link from my summaries to the appropriate articles available in other places.

I will not go too deep into making 3do's because they are old and dumb... but I'll try to make note of the differences here.

I don't know anything about scripting right now, so that section is likely to be sparse when I write it, I hope that someone will expand on it.

=Book 1: The First Unit=

==Step 1:Planning==
Who cares about planning, you know what you're doing... just come up with an idea for a mod... I made a chess set... if you don't have a real idea and just want to make a model show up in the game... then yeah... this is the place to start... I'd do that if I were you.

Another good thing to do at this point is to creat a "working directory", and inside it create a directory with the name that your mod will have... after many headaches I decided it's best to put this in the root directory of your system so it's really easy to find when you are switching around back and forth between folders and keep having to find your files over and over again.

==Step 2:Getting The Tools==
You will need a bunch of stuff... here's the list (I assume you are using windows)

''Want:''
*[http://taspring.clan-sy.com/download.php Spring] - The main program, you will likely need this to test if you've screwed up
*A Tiny Map (2x2) - to test your mod fast (suggest [http://www.fileuniverse.com/?p=showitem&ID=2534 Simple Chess Map])

''Need:''
*'''Program listings can be found here:''' '''[http://taspring.clan-sy.com/wiki/Map%2C_Mod%2C_And_Unit_Development_Programs Map, Mod, And Unit Development Programs]'''
*3D Modeling Program - '''See above link'''
*Notepad - to edit all the miriad of text files
*A Graphical Editing Program - needs to handle RGBA TGAs (aka tga's with alpha channels), I suggest Photoshop if you have it, or The GIMP... needed for all of the texture making for UVmapping stuff... '''See above link'''
*Upspring 1.3 - To convert your models to the approprite s3o format (if you want to fight with 3do builder, then go ahead... a good trick is to get your model into upspring first and adjust all the hierachy, then save it as an 3do... but why bother?). '''See above link'''
*Scriptor - to make and compile your units "animation script"... or steal someone else's and make it work for your unit. '''See above link'''
*Compression Utility - (I suggest [http://www.7-zip.org/ 7zip] - even if you are using zip compression and not 7zip, it's still good to have)

==Step 3:Making a 3D Model==

Go into your 3D modelling program and make a 3D model, [http://taspring.clan-sy.com/w/images/b/b4/WingsCombine.PNG combine] all the objects and UV map the model, then separate it out into any parts that need to move independently of each other. Then Export the UV map as an Image File and Export the whole thing as a 3ds file. Put the original wings file, the UVMap image and the 3ds file into your working directory so you can find them later.

Wings 3D UV Mapping tutorial has been started here - [[Units:CreateModel]]

==Step 4:Fixing Your Images==

[[Basic s3o unit making guide|This Article includes a UVMapping Guide]]

Open up your UVMap in Photoshop (or whatever) go to the layer/chooser thingy and go to the Channels Tab, add a new layer (it should default to alpha) and fill it with 99% black so you can see your texture in upspring. If you want to can paint the UVmap and put white (1% black) on the alpha channel where you want your team colours to show up (you can use something between 1% and 99% to get a blend of your team colour along with the texture... for example 50% will give you your texture with 50% of the team colour mixed in...)

I don't know how to do glow maps... XXreminder for someone to create a Glowmapping tutorial... you don't acctually need one for the model to show up.

Save these images both in the working directory.

Save a copy of these images in tga format into <working directory>/<mod name>/unittextures

==Step 5:Upspring==

===Importing Your 3ds===
Open Upspring 1.3, go to file>load model and navigate to and open your 3DS model you exported, you should see the model in upspring as a 3d mesh. Go to the model tab and set the radius and height values to something other then zero... this defines where the health bar will show up, and more importantly, how big the collision sphere will be.

You will also need to use all of the other tools on those tabs to resize and rotate and move your model to the right place... wings makes models that are 90 degrees off and about 30 times smaller than most spring models... make sure you click the "apply transform" button after any changes that you actually want to show up in the game.

Also, you will want to make the hierachy work using the cut, paste, and add empty buttons. You will need an object called "base" that all the other objects are connected to... the "origin object"... sometimes you get lucky and wings exports it properly... usually not.

===Importing Your UV and Glowmaps===

Go to the textures tab and make your UV/texture/team-colour map as "texture1" and your UV/glow/reflectivity map as "texture2"... it should show up correctly in the preview pane.

===Exporting Your s3o===
Choose File>Save Model As then in the drop down select "s3o" and type an appropriate name. This model should be saved to your working directory, and a copy of it made to <working directory>/<mod name>/objects3d/

==Step 6: Lua files==

===UnitName.lua===


<pre>
unitDef = {
unitname = [[arm_spider]],
name = [[Weaver]],
description = [[Cloaking Construction Spider, Builds at 9 m/s]],
acceleration = 0.15,
bmcode = [[1]],
brakeRate = 0.15,
buildCostEnergy = 230,
buildCostMetal = 230,
buildDistance = 80,
builder = true,

buildoptions = {
},

buildPic = [[arm_spider.png]],
buildTime = 230,
canAttack = false,
canGuard = true,
canMove = true,
canPatrol = true,
canreclamate = [[1]],
canstop = [[1]],
category = [[LAND UNARMED]],
cloakCost = 1,
cloakCostMoving = 2,
corpse = [[DEAD]],

customParams = {
description_bp = [[Aranha e de construÃƒÂ§?o, ConstrÃƒÂ³i a 6 m/s]],
description_es = [[Ara?a de construcciÃƒÂ³n, construye a 6 m/s]],
description_fi = [[Rakentaja/kaikuluotainkiipeilij?, rakentaa 6m/s nopeudella]],
description_fr = [[Araign?e de Construction, Construit ? 6 m/s]],
description_it = [[Ragno do costruzione occultante, costruisce a 6 m/s]],
description_pl = [[Paj?k konstruktor, buduje z pr?dko?ci? 6m/s]],
helptext = [[The Weaver is a constructor that can climb over any obstacle and build defenses on high ground.]],
helptext_bp = [[Weaver ÃƒÂ© o construtor escalador camuflÃƒÂ¡vel de NOVA. Pode subir qualquer obstÃƒÂ¡culo, mas constrÃƒÂ³i mais devagar que construtores normais.]],
helptext_es = [[El Weaver es el constructor que puede treparse sobre qualquier obstÃƒÂ¡culo y construir defensas en terreno alto]],
helptext_fi = [[Weaver pystyy liikkumaan vaikeakulkuisimmassakin maastossa ja rakentamaan vaivatta my?s useimmille muille rakentajille saavuttamattomiin paikkoihin.]],
helptext_fr = [[Le weaver est un robot de construction tout terrain qui peut batir des d?fenses en terrain ?lev?.]],
helptext_it = [[Il Weaver ÃƒÂ© un costruttore che puo arrampicarsi su qualunque ostacolo e costruire difese nel terreno alto]],
helptext_pl = [[Weaver jest konstruktorem mog?cym wspina? si? po ka?dej powierzchni oraz posiadaj?cym mo?liwo?? maskowania si?]],
},

defaultmissiontype = [[Standby]],
designation = [[ARM-MLSPD]],
energyMake = 0.15,
energyUse = 0,
explodeAs = [[BIG_UNITEX]],
footprintX = 3,
footprintZ = 3,
iconType = [[builder]],
mass = 115,
maxDamage = 750,
maxslope = 16,
maxSlope = 72,
maxVelocity = 1.7,
maxWaterDepth = 22,
metalMake = 0.15,
movementClass = [[TKBOT3]],
noAutoFire = false,
noChaseCategory = [[TERRAFORM SATELLITE FIXEDWING GUNSHIP HOVER SHIP SWIM SUB LAND FLOAT SINK]],
objectName = [[ARMMLSPD]],
radarDistanceJam = 256,
seismicSignature = 16,
selfDestructAs = [[BIG_UNITEX]],
showNanoSpray = false,
side = [[ARM]],
sightDistance = 295,
smoothAnim = true,
steeringmode = [[1]],
TEDClass = [[CNSTR]],
terraformSpeed = 450,
threed = [[1]],
turninplace = 0,
turnRate = 1020,
workerTime = 9,
zbuffer = [[1]],

featureDefs = {

DEAD = {
description = [[Wreckage - Weaver]],
blocking = true,
category = [[arm_corpses]],
damage = 850,
featureDead = [[DEAD2]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[40]],
hitdensity = [[100]],
metal = 92,
object = [[ARMMLSPD_dead]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

DEAD2 = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featureDead = [[HEAP]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 92,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

HEAP = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 46,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 46,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

},

}

return lowerkeys({ arm_spider = unitDef })
</pre>

Save this file as a lua file in <working directory>/<mod name>/units/

===modinfo.lua===

modinfo.lua is a lua file that defines a number of things that are used when loading a mod, most of the information is self explanitory but basically what you are doing is defining what is going to show up in whatever mod-selection interface you use as well as what other files need to be loaded into memory in order for your mod to work.

====Making a New Mod with your unit/units====
The following is an example of what will be in your modinfo.lua file if you are starting from scratch and making your own mod. This is also good when you are just testing one unit to see if it works.

<pre>
return {
-- The name is shown in the selection interface
game = "MyMod",
shortGame = "MM",
name = "My Mod",
shortName = "MM",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "My Mod That I Made",
url = "http://www.theplacepeoplecangetthelatestversionofyourmod.com",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
"Spring content v1",
"Spring Cursors",
"Spring Bitmaps",
-- Number of other content names this one replaces
},
}
</pre>

====Adding Your Unit to an Existing Mod====
The following is an example of what will be in your modinfo.lua file if you are adding new units to an existing mod (in this case XTA SE v066), this is good for adding units to the build tree of an existing mod or adding a whole new team.

<pre>
-- Description of the mod control file recognized by spring:
return {
-- The name is shown in the selection interface
game = "XTASE_MyUnits",
shortGame = "XTASEMU",
name = "XTASEv0.66 with+My Units",
shortName = "XTASEMU",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "xta_se_v066 with the cool tank I made",
url = "http://www.fileuniverse.com/exactlocationblahblahblah",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
"XTA se v066",
"Spring Cursors",
"Spring content v1",
-- Number of other archives this one replaces
},
}
</pre>

If you are not depending on OTA files, you will have to supply your own cursors.

There are some extra bits in these examples, but I work on the "better safe than sorry" principle... which is to wait for someone who knows what they are doing to fix my articles.

You will want to save this file as plain text in <working directory>/<mod name>/

===armorDefs.lua===

I'm not exactly sure how this works, but the file needs to exist, so either steal one from another mod and modify it... or just make a file that looks like this.

<pre>
local armorDefs = {
}
</pre>

You will want to save this file as a lua file in <working directory>/<mod name>/gamedata

===sidedata.lua===

Start by stealing the sidedata.lua file from your dependency mod if you have one, then edit it to include your units/side.

Basically this file is in the form:

<pre>
local sideData = {
[1] = {
name = 'Good Guys',
startunit = 'GG_comm',
},
}
</pre>

There are also additional "[X]" entries for each side/team/commander-choice available in the mod-selector you choose.

You will save this file as lua file in <working directory>/<mod name>/gamedata/

===moveDefs.lua===
This file determines the footprint of your units, the angle of slopes they can climb and in how deep water they can drive. It contains several entries, all in the following format:

<pre>
local moveDefs = {
KBOT1 = { -- This is the name. Unit files refer to this name.
footprintx = 1, -- This is how big the X dimension is of the footprint in Spring units probably?
footprintz = 1, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxwaterdepth = 15, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxslope = 36, -- The maximum angle of slopes this unit can climb.
crushstrength = 5, -- This determines if the unit/unit class can crush certain features
},
-- etc..
}
</pre>

===sounds.lua===
This file refers to all the sounds your units make, so Spring knows which sound file is linked to what action. It contains entries in the following format.

<pre>
local Sounds = {
SoundItems = {
IncomingChat = {
file = "sounds/nexuiz/talk.wav",
priority = 15,
preload = true,
},
MultiSelect = {
file = "sounds/ota/button9.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
MapPoint = {
file = "sounds/bzflag/teamgrab.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
FailedCommand = {
file = "sounds/openQuarz/pkup.wav",
gain = 0.75,
priority = 15,
preload = true,
in3d = false,
},
}
</pre>
}

==Step 7:Adding a Build Pic==

Add a 96x96 BMP to your <working directory>/<mod name>/unitpics/ folder named either "UnitName.bmp" or whatever you specified in the "BuildPic=" line of your fbi.

==Step 8:Adding a Side Pic==

Add a 16x16 BMP to your <working directory>/<mod name>/sidepics/ folder named "teamname.bmp" or whatever you specified in the "name=" line of your SIDEDATA.TDF for each side/team you have added.

==Step 9:Scriptor==

===Stealing a Script===
Open someone else's script in scriptor that works the way you want your script to work, look at the top where it's talking about "piece names"... then change those piece names to be the piece names of your unit and do a find/replace to make all the places where those pieces show up to be your pieces too. Compile it so its name is the same as the "UnitName=" value in your "UnitName.fbi".

XXreminder to someone to link to a proper scripting tutorial

Put the bos and cob files for your unit script in <working directory>/<mod name>/scripts

==Step 10:Compiling Your Mod==

You may want to check your mod directory and make sure it follows the structure defined [[Mod_Development:Archives|here]].

navigate to your <working directory>/<mod name> and select everything and choose "add to archive <mod name>.7z".

make a copy of this file called <mod name>v0.7z in your working directory so you don't screw anything up later, then make a copy of it called <mod name>.sd7 in the mods directory of spring.

An alternative, added in more recent versions is the ".SDD" folder, to use this, copy the entire <mod name> folder in the mods directory of spring and rename it as "<mod name>.SDD". The advantage to the ".SDD" method is that you can tweak settings and add files without recompressing your mod all the time. When it comes time to distribute your mod use ".sd7".

EXAMPLES:
If your mod is called JoesMod you will have a file called "JoesMod.sd7" or a folder called "JoesMod.SDD" in your spring mods directory.

==Step 11:Testing Your Mod==
Open Up your lobby client, pick your mod from the drop-down list of the games in host battle or singleplayer mode if your lobby supports it(if it doesn't show up you screwed up your modinfo.txt), choose your tiny map from the map list and press start. If it doesn't break and your unit shows up, you have created all the neccessary files... yay!

Gotchas:
*If it doesn't work, check you didn't zip the folder itself, but the contents, ie if you open mymod.sd7 with 7zip, you should see folders such as "unittextures" rather than a folder "mymod" containing unittextures.

[[Category:Mod development]]

Simple Game Tutorial

2010-08-23T11:48:27Z

Braindamage: use unitsync names, not filenames!

Until I Finish [[Mod Development]] is the place to go.

This Tutorial Aims to get a person from knowing nothing about Spring to the point where they can create and edit mods.

Right now I am working from memory so you may want to correct me when I'm wrong, I will try to cross link from my summaries to the appropriate articles available in other places.

I will not go too deep into making 3do's because they are old and dumb... but I'll try to make note of the differences here.

I don't know anything about scripting right now, so that section is likely to be sparse when I write it, I hope that someone will expand on it.

=Book 1: The First Unit=

==Step 1:Planning==
Who cares about planning, you know what you're doing... just come up with an idea for a mod... I made a chess set... if you don't have a real idea and just want to make a model show up in the game... then yeah... this is the place to start... I'd do that if I were you.

Another good thing to do at this point is to creat a "working directory", and inside it create a directory with the name that your mod will have... after many headaches I decided it's best to put this in the root directory of your system so it's really easy to find when you are switching around back and forth between folders and keep having to find your files over and over again.

==Step 2:Getting The Tools==
You will need a bunch of stuff... here's the list (I assume you are using windows)

''Want:''
*[http://taspring.clan-sy.com/download.php Spring] - The main program, you will likely need this to test if you've screwed up
*A Tiny Map (2x2) - to test your mod fast (suggest [http://www.fileuniverse.com/?p=showitem&ID=2534 Simple Chess Map])

''Need:''
*'''Program listings can be found here:''' '''[http://taspring.clan-sy.com/wiki/Map%2C_Mod%2C_And_Unit_Development_Programs Map, Mod, And Unit Development Programs]'''
*3D Modeling Program - '''See above link'''
*Notepad - to edit all the miriad of text files
*A Graphical Editing Program - needs to handle RGBA TGAs (aka tga's with alpha channels), I suggest Photoshop if you have it, or The GIMP... needed for all of the texture making for UVmapping stuff... '''See above link'''
*Upspring 1.3 - To convert your models to the approprite s3o format (if you want to fight with 3do builder, then go ahead... a good trick is to get your model into upspring first and adjust all the hierachy, then save it as an 3do... but why bother?). '''See above link'''
*Scriptor - to make and compile your units "animation script"... or steal someone else's and make it work for your unit. '''See above link'''
*Compression Utility - (I suggest [http://www.7-zip.org/ 7zip] - even if you are using zip compression and not 7zip, it's still good to have)

==Step 3:Making a 3D Model==

Go into your 3D modelling program and make a 3D model, [http://taspring.clan-sy.com/w/images/b/b4/WingsCombine.PNG combine] all the objects and UV map the model, then separate it out into any parts that need to move independently of each other. Then Export the UV map as an Image File and Export the whole thing as a 3ds file. Put the original wings file, the UVMap image and the 3ds file into your working directory so you can find them later.

Wings 3D UV Mapping tutorial has been started here - [[Units:CreateModel]]

==Step 4:Fixing Your Images==

[[Basic s3o unit making guide|This Article includes a UVMapping Guide]]

Open up your UVMap in Photoshop (or whatever) go to the layer/chooser thingy and go to the Channels Tab, add a new layer (it should default to alpha) and fill it with 99% black so you can see your texture in upspring. If you want to can paint the UVmap and put white (1% black) on the alpha channel where you want your team colours to show up (you can use something between 1% and 99% to get a blend of your team colour along with the texture... for example 50% will give you your texture with 50% of the team colour mixed in...)

I don't know how to do glow maps... XXreminder for someone to create a Glowmapping tutorial... you don't acctually need one for the model to show up.

Save these images both in the working directory.

Save a copy of these images in tga format into <working directory>/<mod name>/unittextures

==Step 5:Upspring==

===Importing Your 3ds===
Open Upspring 1.3, go to file>load model and navigate to and open your 3DS model you exported, you should see the model in upspring as a 3d mesh. Go to the model tab and set the radius and height values to something other then zero... this defines where the health bar will show up, and more importantly, how big the collision sphere will be.

You will also need to use all of the other tools on those tabs to resize and rotate and move your model to the right place... wings makes models that are 90 degrees off and about 30 times smaller than most spring models... make sure you click the "apply transform" button after any changes that you actually want to show up in the game.

Also, you will want to make the hierachy work using the cut, paste, and add empty buttons. You will need an object called "base" that all the other objects are connected to... the "origin object"... sometimes you get lucky and wings exports it properly... usually not.

===Importing Your UV and Glowmaps===

Go to the textures tab and make your UV/texture/team-colour map as "texture1" and your UV/glow/reflectivity map as "texture2"... it should show up correctly in the preview pane.

===Exporting Your s3o===
Choose File>Save Model As then in the drop down select "s3o" and type an appropriate name. This model should be saved to your working directory, and a copy of it made to <working directory>/<mod name>/objects3d/

==Step 6: Lua files==

===UnitName.lua===


<pre>
unitDef = {
unitname = [[arm_spider]],
name = [[Weaver]],
description = [[Cloaking Construction Spider, Builds at 9 m/s]],
acceleration = 0.15,
bmcode = [[1]],
brakeRate = 0.15,
buildCostEnergy = 230,
buildCostMetal = 230,
buildDistance = 80,
builder = true,

buildoptions = {
},

buildPic = [[arm_spider.png]],
buildTime = 230,
canAttack = false,
canGuard = true,
canMove = true,
canPatrol = true,
canreclamate = [[1]],
canstop = [[1]],
category = [[LAND UNARMED]],
cloakCost = 1,
cloakCostMoving = 2,
corpse = [[DEAD]],

customParams = {
description_bp = [[Aranha e de construÃƒÂ§?o, ConstrÃƒÂ³i a 6 m/s]],
description_es = [[Ara?a de construcciÃƒÂ³n, construye a 6 m/s]],
description_fi = [[Rakentaja/kaikuluotainkiipeilij?, rakentaa 6m/s nopeudella]],
description_fr = [[Araign?e de Construction, Construit ? 6 m/s]],
description_it = [[Ragno do costruzione occultante, costruisce a 6 m/s]],
description_pl = [[Paj?k konstruktor, buduje z pr?dko?ci? 6m/s]],
helptext = [[The Weaver is a constructor that can climb over any obstacle and build defenses on high ground.]],
helptext_bp = [[Weaver ÃƒÂ© o construtor escalador camuflÃƒÂ¡vel de NOVA. Pode subir qualquer obstÃƒÂ¡culo, mas constrÃƒÂ³i mais devagar que construtores normais.]],
helptext_es = [[El Weaver es el constructor que puede treparse sobre qualquier obstÃƒÂ¡culo y construir defensas en terreno alto]],
helptext_fi = [[Weaver pystyy liikkumaan vaikeakulkuisimmassakin maastossa ja rakentamaan vaivatta my?s useimmille muille rakentajille saavuttamattomiin paikkoihin.]],
helptext_fr = [[Le weaver est un robot de construction tout terrain qui peut batir des d?fenses en terrain ?lev?.]],
helptext_it = [[Il Weaver ÃƒÂ© un costruttore che puo arrampicarsi su qualunque ostacolo e costruire difese nel terreno alto]],
helptext_pl = [[Weaver jest konstruktorem mog?cym wspina? si? po ka?dej powierzchni oraz posiadaj?cym mo?liwo?? maskowania si?]],
},

defaultmissiontype = [[Standby]],
designation = [[ARM-MLSPD]],
energyMake = 0.15,
energyUse = 0,
explodeAs = [[BIG_UNITEX]],
footprintX = 3,
footprintZ = 3,
iconType = [[builder]],
mass = 115,
maxDamage = 750,
maxslope = 16,
maxSlope = 72,
maxVelocity = 1.7,
maxWaterDepth = 22,
metalMake = 0.15,
movementClass = [[TKBOT3]],
noAutoFire = false,
noChaseCategory = [[TERRAFORM SATELLITE FIXEDWING GUNSHIP HOVER SHIP SWIM SUB LAND FLOAT SINK]],
objectName = [[ARMMLSPD]],
radarDistanceJam = 256,
seismicSignature = 16,
selfDestructAs = [[BIG_UNITEX]],
showNanoSpray = false,
side = [[ARM]],
sightDistance = 295,
smoothAnim = true,
steeringmode = [[1]],
TEDClass = [[CNSTR]],
terraformSpeed = 450,
threed = [[1]],
turninplace = 0,
turnRate = 1020,
workerTime = 9,
zbuffer = [[1]],

featureDefs = {

DEAD = {
description = [[Wreckage - Weaver]],
blocking = true,
category = [[arm_corpses]],
damage = 850,
featureDead = [[DEAD2]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[40]],
hitdensity = [[100]],
metal = 92,
object = [[ARMMLSPD_dead]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

DEAD2 = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featureDead = [[HEAP]],
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 92,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 92,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

HEAP = {
description = [[Debris - Weaver]],
blocking = false,
category = [[heaps]],
damage = 850,
featurereclamate = [[smudge01]],
footprintX = 3,
footprintZ = 3,
height = [[4]],
hitdensity = [[100]],
metal = 46,
object = [[debris3x3b.s3o]],
reclaimable = true,
reclaimTime = 46,
seqnamereclamate = [[tree1reclamate]],
world = [[All Worlds]],
},

},

}

return lowerkeys({ arm_spider = unitDef })
</pre>

Save this file as a lua file in <working directory>/<mod name>/units/

===modinfo.lua===

modinfo.lua is a lua file that defines a number of things that are used when loading a mod, most of the information is self explanitory but basically what you are doing is defining what is going to show up in whatever mod-selection interface you use as well as what other files need to be loaded into memory in order for your mod to work.

====Making a New Mod with your unit/units====
The following is an example of what will be in your modinfo.lua file if you are starting from scratch and making your own mod. This is also good when you are just testing one unit to see if it works.

<pre>
return {
-- The name is shown in the selection interface
game = "MyMod",
shortGame = "MM",
name = "My Mod",
shortName = "MM",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "My Mod That I Made",
url = "http://www.theplacepeoplecangetthelatestversionofyourmod.com",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
"Spring content v1",
"Spring Cursors",
"Spring Bitmaps",
-- Number of other content names this one replaces
},
}
</pre>

====Adding Your Unit to an Existing Mod====
The following is an example of what will be in your modinfo.lua file if you are adding new units to an existing mod (in this case xta_se_v066.sdz), this is good for adding units to the build tree of an existing mod or adding a whole new team.

<pre>
-- Description of the mod control file recognized by spring:
return {
-- The name is shown in the selection interface
game = "XTASE_MyUnits",
shortGame = "XTASEMU",
name = "XTASEv0.66 with+My Units",
shortName = "XTASEMU",
version = "4.0",
mutator = "Heroes",
-- These can be shown by the selection interface
description = "xta_se_v066 with the cool tank I made",
url = "http://www.fileuniverse.com/exactlocationblahblahblah",
-- What kind of mod this is
-- 0 - Hidden (support mod that can't be selected, such as OTA_textures)
-- 1 - Normal, only one can be selected at a time
-- 2 - Addon, any number of these can be selected. Could be used
-- for single units for example.
-- others - perhaps mutators and addon races that can be
-- enabled in addition to xta for example?
modtype = "1",
-- Number of other archives this one depends on
depend= {
taenheter.sdz,
springcontent.sdz,
otacontent.sdz,
tatextures.sdz,
xta_se_v066.sdz,
-- Number of other archives this one replaces
},
}
</pre>

If you are not depending on OTA files, you will have to supply your own cursors.

There are some extra bits in these examples, but I work on the "better safe than sorry" principle... which is to wait for someone who knows what they are doing to fix my articles.

You will want to save this file as plain text in <working directory>/<mod name>/

===armorDefs.lua===

I'm not exactly sure how this works, but the file needs to exist, so either steal one from another mod and modify it... or just make a file that looks like this.

<pre>
local armorDefs = {
}
</pre>

You will want to save this file as a lua file in <working directory>/<mod name>/gamedata

===sidedata.lua===

Start by stealing the sidedata.lua file from your dependency mod if you have one, then edit it to include your units/side.

Basically this file is in the form:

<pre>
local sideData = {
[1] = {
name = 'Good Guys',
startunit = 'GG_comm',
},
}
</pre>

There are also additional "[X]" entries for each side/team/commander-choice available in the mod-selector you choose.

You will save this file as lua file in <working directory>/<mod name>/gamedata/

===moveDefs.lua===
This file determines the footprint of your units, the angle of slopes they can climb and in how deep water they can drive. It contains several entries, all in the following format:

<pre>
local moveDefs = {
KBOT1 = { -- This is the name. Unit files refer to this name.
footprintx = 1, -- This is how big the X dimension is of the footprint in Spring units probably?
footprintz = 1, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxwaterdepth = 15, -- This is how big the Y dimension is of the footprint in Spring units probably?
maxslope = 36, -- The maximum angle of slopes this unit can climb.
crushstrength = 5, -- This determines if the unit/unit class can crush certain features
},
-- etc..
}
</pre>

===sounds.lua===
This file refers to all the sounds your units make, so Spring knows which sound file is linked to what action. It contains entries in the following format.

<pre>
local Sounds = {
SoundItems = {
IncomingChat = {
file = "sounds/nexuiz/talk.wav",
priority = 15,
preload = true,
},
MultiSelect = {
file = "sounds/ota/button9.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
MapPoint = {
file = "sounds/bzflag/teamgrab.wav",
priority = 15,
preload = true,
rolloff = 0.1,
},
FailedCommand = {
file = "sounds/openQuarz/pkup.wav",
gain = 0.75,
priority = 15,
preload = true,
in3d = false,
},
}
</pre>
}

==Step 7:Adding a Build Pic==

Add a 96x96 BMP to your <working directory>/<mod name>/unitpics/ folder named either "UnitName.bmp" or whatever you specified in the "BuildPic=" line of your fbi.

==Step 8:Adding a Side Pic==

Add a 16x16 BMP to your <working directory>/<mod name>/sidepics/ folder named "teamname.bmp" or whatever you specified in the "name=" line of your SIDEDATA.TDF for each side/team you have added.

==Step 9:Scriptor==

===Stealing a Script===
Open someone else's script in scriptor that works the way you want your script to work, look at the top where it's talking about "piece names"... then change those piece names to be the piece names of your unit and do a find/replace to make all the places where those pieces show up to be your pieces too. Compile it so its name is the same as the "UnitName=" value in your "UnitName.fbi".

XXreminder to someone to link to a proper scripting tutorial

Put the bos and cob files for your unit script in <working directory>/<mod name>/scripts

==Step 10:Compiling Your Mod==

You may want to check your mod directory and make sure it follows the structure defined [[Mod_Development:Archives|here]].

navigate to your <working directory>/<mod name> and select everything and choose "add to archive <mod name>.7z".

make a copy of this file called <mod name>v0.7z in your working directory so you don't screw anything up later, then make a copy of it called <mod name>.sd7 in the mods directory of spring.

An alternative, added in more recent versions is the ".SDD" folder, to use this, copy the entire <mod name> folder in the mods directory of spring and rename it as "<mod name>.SDD". The advantage to the ".SDD" method is that you can tweak settings and add files without recompressing your mod all the time. When it comes time to distribute your mod use ".sd7".

EXAMPLES:
If your mod is called JoesMod you will have a file called "JoesMod.sd7" or a folder called "JoesMod.SDD" in your spring mods directory.

==Step 11:Testing Your Mod==
Open Up your lobby client, pick your mod from the drop-down list of the games in host battle or singleplayer mode if your lobby supports it(if it doesn't show up you screwed up your modinfo.txt), choose your tiny map from the map list and press start. If it doesn't break and your unit shows up, you have created all the neccessary files... yay!

Gotchas:
*If it doesn't work, check you didn't zip the folder itself, but the contents, ie if you open mymod.sd7 with 7zip, you should see folders such as "unittextures" rather than a folder "mymod" containing unittextures.

[[Category:Mod development]]