Lua SyncedCtrl
More actions
Development < Lua Scripting < Lua SyncedCtrl
Game End
Spring.KillTeam
( number teamID )
return: nil
- New in version 83.0
Will declare a team to be dead ( no further orders can be assigned to such teams's units ), Gaia team cannot be killed.
Spring.GameOver
( number allyTeamID1,
number allyTeamID2,
... )
return: nil
- New in version 83.0
Will declare game over, a list of winning allyteams can be passed, if undecided ( like when dropped from the host ) it should be empty ( no winner ), in the case of a draw with multiple winners, all should be listed.
RulesParams
String values are new since 95.0. Attention: Numeric paramValues in quotes will be converted to number.
Spring.SetUnitRulesParam
( number unitID,
string paramName,
number|string paramValue [,
table losAccess ] )
return: nil
- Possible keys for the losAccess table are:
`private` : only readable by the ally (default) `allied` : readable by ally + ingame allied `inlos` : readable if the unit is in LOS `inradar` : readable if the unit is in AirLOS `public` : readable by all note: if one condition is fulfilled all beneath it are too (e.g. if an unit is in LOS it
can read params with `inradar=true` even if the param has `inlos=false`) note2: all GameRulesParam are public, TeamRulesParams can just be `private`,`allied`
and/or `public` note3: You can read RulesParams from any Lua enviroments! With those losAccess
policies you can limit their access.
Spring.SetFeatureRulesParam
( number featureID,
string paramName,
number|string paramValue [,
table losAccess ] )
return: nil
- New since 102.0.
See above for further documentation of losAccess.
Spring.SetTeamRulesParam
( number teamID,
string paramName,
number|string paramValue [,
table losAccess ] )
return: nil
- See above for further documentation of losAccess.
Spring.SetGameRulesParam
( string paramName,
number|string paramValue [,
table losAccess ] )
return: nil
- See above for further documentation of losAccess.
Resources
Spring.AddTeamResource
( number teamID,
string "metal" | "energy",
number amount )
return: nil
- Adds metal or energy resources to the specified team.
Spring.UseTeamResource
( number teamID,
string "metal" | "energy",
number amount | { metal = number amount, energy = number amount } )
return: nil | bool hadEnough
- Consumes metal and/or energy resources of the specified team.
Spring.SetTeamResource
( number teamID,
string res,
number amount )
return: 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 )
return: nil
- Changes the resource amount for a team beyond which resources aren't stored but transferred to other allied teams if possible.
Spring.ShareTeamResource
( number teamID_src,
number teamID_recv,
string "metal" | "energy",
number amount )
return: nil
- Transfers resources between two teams.
Teams
Spring.SetAlly
( number firstAllyTeamID,
number secondAllyTeamID,
bool ally )
return: nil
- New in version 98.0
Changes the value of the (one-sided) alliance between: firstAllyTeamID -> secondAllyTeamID.
Spring.AssignPlayerToTeam
( number playerID,
number teamID )
return: nil
- New in version 98.0
Assigns a player to a team.
Spring.SetGlobalLos
( number allyTeamID,
bool globallos )
return: nil
- New in version 101.0
Changes access to global line of sight for a team and its allies.
Unit Handling
Spring.CreateUnit
( string "defName" | number unitDefID,
number x,
number y,
number z,
string "facing" | number facing,
number teamID [,
bool build = false [,
bool flattenGround = true [,
number builderID ]]] )
return: number unitID | nil (meaning unit was not created)
- Offmap positions are clamped! Use MoveCtrl to move to such positions.
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 in version 92.0, the former allowing to spawn a unit with a specific ID.
Spring.DestroyUnit
( number unitID [,
bool selfd = false [,
bool reclaimed = false [,
number attackerID ]]] )
return: nil
- selfd := Makes the unit act like it self-destructed.
reclaimed := Don't show any DeathSequences, don't leave a wreckage. This does not give back the resources to the team!
Spring.TransferUnit
( number unitID,
number newTeamID [,
bool given = true ] )
return: nil
- If given=false, the unit is captured.
Unit Control
Spring.SetUnitCosts
( number unitID,
{ [ buildTime = number amount ],
[ metalCost = number amount ],
[ energyCost = number amount ] } )
return: nil
Spring.SetUnitTooltip
( number unitID,
string "tooltip" )
return: nil
Spring.SetUnitHealth
( number unitID,
number health | { [ health = number health ],
[ capture = number capture ],
[ paralyze = number paralyze ],
[ build = number build ] } )
return: nil
Spring.SetUnitMaxHealth
( number unitID,
number maxHealth )
return: 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 ]]]]]] )
return: nil
- The number in the paralyze parameter equals to the paralyzetime in the WeaponDef.
Spring.SetUnitStockpile
( number unitID [,
number stockpile [,
number buildPercent ]] )
return: nil
Spring.SetUnitExperience
( number unitID,
number experience,
number buildPercent )
return: nil
Spring.SetUnitFuel
( number unitID,
number fuel )
return: nil
- Removed from version 101.0
Spring.SetUnitCrashing
( number unitID,
bool crashing )
return: bool success
- New in version 83.0
Spring.SetUnitLineage
( number unitID,
number teamID [,
bool isRoot ] )
return: nil
- Removed from version 83.0
Spring.SetUnitNeutral
( number unitID,
bool neutral )
return: nil
- Removed from version 83.0
Spring.SetUnitTarget
( number unitID,
number x | nil,
number y,
number z [,
bool dgun = false [,
bool userTarget = false [,
number weaponNum = -1 ]]] )
return: bool success
or
Spring.SetUnitTarget
( number unitID,
number enemyUnitID | nil [,
bool dgun = false [,
bool userTarget = false [,
number weaponNum = -1 ]]] )
return: bool success
- Defines a unit's target. Nil as 2nd argument drops the unit's current target.
UserTarget & success new in version 95.0, setting nil target new in version 99.0, weaponNum new in version 102.0.
Spring.SetUnitMaxRange
( number unitID,
number maxRange )
return: nil
Spring.SetUnitMass
( number unitID,
number mass )
return: nil
- New in version 101.0
Spring.SetUnitBlocking
( number unitID,
bool isblocking,
bool isSolidObjectCollidable,
bool isProjectileCollidable,
bool isRaySegmentCollidable,
bool crushable,
bool blockEnemyPushing,
bool blockHeightChanges )
return: nil
- New in version 95.0
Changed parameters.
Spring.SetUnitMetalExtraction
( number unitID,
number depth [,
number range ] )
return: nil
- Parameter "depth" corresponds to metal extraction rate. Range value is similar to "extractsMetal" in unitDefs.
Spring.SetUnitBuildSpeed
( number builderID,
number buildSpeed [,
number repairSpeed [,
number reclaimSpeed[,
number resurrectSpeed [,
number captureSpeed [,
number terraformSpeed ]]]]] )
return: nil
Spring.SetUnitNanoPieces
( number builderID,
table pieces )
return: nil
- New in version 92.0
This saves a lot of engine calls, by replacing: function script.QueryNanoPiece() return currentpiece end
Use it!
Spring.UnitAttach
( number transporterID,
number passengerID,
number pieceNum )
return: nil
- New in version 101.0
Spring.UnitDetach
( number passengerID )
return: nil
- New in version 101.0
Spring.UnitDetachFromAir
( number passengerID )
return: nil
- New in version 101.0
Spring.SetUnitLoadingTransport
( number passengerID,
number transportID )
return: nil
- New in version 101.0
Disables collisions between the two units to allow colvol intersection during the approach.
Spring.SetUnitPieceParent
( number unitID,
number AlteredPiece,
number ParentPiece )
return: nil
- New in version 101.0
Changes the pieces hierarchy of a unit by attaching a piece to a new parent.
Spring.SetUnitPieceMatrix
( number unitID,
number pieceNum,
table matrix )
return: nil
- New in version 104.0
Sets the local (i.e. parent-relative) matrix of the given piece if any of the first three elements are non-zero, and also blocks all script animations from modifying it until {0, 0, 0} is passed (matrix should be an array of 16 floats, but is not otherwise sanity-checked).
Spring.SetUnitArmored
( number unitID,
bool armored [,
number armorMultiple ] )
return: nil
- armorMultiple new in version 0.83.x
Spring.SetUnitShieldState
( number unitID [,
number weaponID = -1 [,
bool enabled [,
number power ]]] )
return: nil
Spring.SetUnitFlanking
( number unitID,
string "mode",
number mode )
return: nil
or
Spring.SetUnitFlanking
( number unitID,
string "moveFactor",
number factor )
return: nil
or
Spring.SetUnitFlanking
( number unitID,
string "minDamage",
number minDamage )
return: nil
or
Spring.SetUnitFlanking
( number unitID,
string "maxDamage",
number maxDamage )
return: nil
or
Spring.SetUnitFlanking
( number unitID,
string "dir",
number x,
number y,
number z )
return: nil
Spring.SetUnitWeaponState
( number unitID,
number weaponNum,
table states )
return: nil
or
Spring.SetUnitWeaponState
( number unitID,
number weaponNum,
string key,
number value )
return: 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,]
["salvoLeft" = number value,]
["nextSalvo" = number value,]
["aimReady" = number value,] (<>0.0f := true)
}
(*) if you change the range of a weapon with dynamic damage
make sure you use SetUnitWeaponDamages to change dynDamageRange as well.
Spring.SetUnitWeaponDamages
( number unitID,
number weaponNum | string "selfDestruct" | string "explode",
table damages )
return: nil
or
Spring.SetUnitWeaponDamages
( number unitID,
number weaponNum | string "selfDestruct" | string "explode",
string key,
number value )
return: nil
- New in version 101.0
Format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}
Spring.SetUnitCollisionVolumeData
( number unitID,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number vType,
number tType,
number Axis )
return: 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,
bool enable,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ [,
number volumeType [,
number primaryAxis ]] )
return: nil
- As of 101.0 this is 1-based piece index argument (was 0-based).
Spring.SetUnitTravel
( number unitID,
number travel [,
number travelPeriod ] )
return: nil
Spring.SetUnitMoveGoal
( number unitID,
number goalX, number goalY, number goalZ [,
number goalRadius [,
number moveSpeed [,
bool moveRaw ]]] )
return: nil
- Used by default commands to get in build-, attackrange etc.
New in version 98.0 moveRaw: allow unit to dumbly move to a coordinate without calculating path.
Spring.SetUnitLandGoal
( number unitID,
number goalX, number goalY, number goalZ [,
number goalRadius ] )
return: nil
- New in version 101.0
Used in conjunction with Spring.UnitAttach et al. to re-implement old airbase & fuel system in Lua.
Spring.ClearUnitGoal
( number unitID )
return: nil
- New in version 102.0
Spring.SetUnitPhysics
( number unitID,
number posX, number posY, number posZ,
number velX, number velY, number velZ,
number rotX, number rotY, number rotZ,
number dragX, number dragY, number dragZ )
return: nil
- Drag new in version 95.0
Spring.SetUnitPosition
( number unitID,
number x,
number z [,
bool alwaysAboveSea ] )
return: nil
Spring.SetUnitDirection
( number unitID,
number x,
number y,
number z )
return: nil
- New in version 90.0
Spring.SetUnitVelocity
( number unitID,
number velX,
number velY,
number velZ )
return: nil
Spring.SetUnitRotation
( number unitID,
number yaw,
number pitch,
number roll )
return: nil
Spring.AddUnitImpulse
( number unitID,
number x,
number y,
number z [,
number decayRate ] )
return: nil
Spring.AddUnitSeismicPing
( number unitID,
number pingSize )
return: nil
Spring.SetGroundMoveTypeData
( number unitID,
table properties )
return: nil
- Use this function to control movement properties for ground units. Known properties : maxSpeed, maxWantedSpeed, turnRate, ... (TODO fix/update)
Spring.SetAirMoveTypeData
( number unitID,
table properties )
return: nil
- Use this function to control movement properties for non-gunship air units. Known properties : maxSpeed, maxWantedSpeed, ... (TODO fix/update)
Spring.SetGunshipMoveTypeData
( number unitID,
table properties )
return: nil
- Use this function to control movement properties for air gunships. Known properties : maxSpeed, maxWantedSpeed, turnRate, ... (TODO fix/update)
Spring.RemoveBuildingDecal
( number unitID )
return: nil
Spring.SetUnitMidAndAimPos
( number unitID,
number mpX, number mpY, number mpZ,
number apX, number apY, number apZ [,
bool relative ] )
return: bool success
- New in version 89.0
mpx, mpy, mpz: New middle position of unit
apx, apy, apz: New position that enemies aim at on this unit
relative: Are the new coordinates relative to world (false) or unit (true) coordinates? Also, note that apy is inverted!
Spring.SetUnitRadiusAndHeight
( number unitID,
number radius,
number height )
return: bool success
- New in version 89.0
Spring.UnitWeaponFire
( number unitID,
number weaponID )
return: nil
Spring.UnitWeaponHoldFire
( number unitID,
number weaponID )
return: nil
Unit LOS
Spring.SetUnitCloak
( number unitID,
bool cloaked | number scriptCloak [,
bool decloakAbs | number decloakDistance ] )
return: 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,
bool sonarStealth )
return: nil
Spring.SetUnitStealth
( number unitID,
bool stealth )
return: nil
Spring.SetUnitAlwaysVisible
( number unitID,
bool alwaysVisible )
return: nil
Spring.SetUnitLosMask
( number unitID,
number allyTeam,
number los | table losTypes )
return: nil
- The 3rd argument is either the bit-and combination of the following numbers:
LOS_INLOS = 1
LOS_INRADAR = 2
LOS_PREVLOS = 4
LOS_CONTRADAR = 8
or a table of the following form:
losTypes = {
[los = boolean,]
[radar = boolean,]
[prevLos = boolean,]
[contRadar = boolean]
}
Spring.SetUnitLosState
( number unitID,
number allyTeam,
number los | table losTypes )
return: nil
- See above for more info on the arguments.
Spring.SetUnitSensorRadius
( number unitID,
string type,
number radius )
return: nil | number newRadius
- Type can be:
"los", "airLos", "radar", "sonar", "seismic", "radarJammer", "sonarJammer"
Spring.SetRadarErrorParams
( number allyTeamID,
number allyteamErrorSize [,
number baseErrorSize [,
number baseErrorMult ]] )
return: nil
- New in version 95.0
Spring.SetUnitPosErrorParams
( number unitID,
number posErrorVector.x, number posErrorVector.y, number posErrorVector.z,,
number posErrorDelta.x, number number posErrorDelta.y, number posErrorDelta.z [,
number nextPosErrorUpdate ] )
return: nil
- New in version 95.0
Unit Resourcing
Spring.SetUnitResourcing
( number unitID,
string res,
number amount )
return: nil
or
Spring.SetUnitResourcing
( number unitID,
{ res = number amount, ... } )
return: 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 )
return: nil
Spring.UseUnitResource
( number unitID,
string "m" | "e",
number amount )
return: nil | bool okay
or
Spring.UseUnitResource
( number unitID,
{ [ "m" | "metal" | "e" | "energy" ] = amount, ... } )
return: nil | bool okay
Spring.SetUnitHarvestStorage
( number unitID,
number metal )
return: nil
- New in version 97.0
See also harvestStorage UnitDef tag.
Feature Handling
Spring.CreateFeature
( string "defName" | number featureDefID,
number x, number y, number z [,
number heading [,
number AllyTeamID [,
number featureID ]]] )
return: number featureID
Spring.DestroyFeature
( number featureDefID )
return: nil
Spring.TransferFeature
( number featureDefID,
number teamID )
return: nil
Feature Control
Spring.SetFeatureHealth
( number featureID,
number health )
return: nil
Spring.SetFeatureResources
( number featureID,
number metal,
number energy [,
number reclaimTime [,
number reclaimLeft ]{rbracket,
{{{arg6}}},
{{{arg7}}},
{{{arg8}}},
{{{arg9}}} )
|arg6 = |arg7 = |arg8 = |arg9 = |return = nil |info = New in version 104.0 }}
Spring.SetFeatureReclaim
( number featureID,
number reclaimLeft )
return: nil
Spring.SetFeatureResurrect
( number featureID,
number unitDefID | string unitDefName [,
number facing | string "facing" [,
number progress ]] )
return: nil
- New in version 104.0 Second param can now be a number id instead of a string name, this also allows cancelling ressurection by passing -1. The level of progress can now be set via the additional 4th param.
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 [,
bool snapToGround ] )
return: nil
Spring.SetFeatureDirection
( number featureID,
number dirX, number dirY, number dirZ )
return: nil
Spring.SetFeatureRotation
( number featureID,
number rotX, number rotY, number rotZ )
return: nil
- New in version 101.0
Spring.SetFeatureVelocity
( number featureID,
number velX, number velY, number velZ )
return: nil
- New in version 95.0
Spring.SetUnitPhysics
( number featureID,
number posX, number posY, number posZ,
number velX, number velY, number velZ,
number rotX, number rotY, number rotZ,
number dragX, number dragY, number dragZ )
return: nil
- New in version 95.0
Spring.SetFeatureMoveCtrl
( number featureID [,
bool enable [,
number* args ]] )
return: nil
- Use this callout to control feature movement. The number* arguments are parsed as follows and all optional:
If enable is true:
[, velVector(x,y,z) -- initial velocity for feature
[, accVector(x,y,z) -- acceleration added every frame]]
If enable is false:
[, velocityMask(x,y,z) -- dimensions in which velocity is allowed to build when not using MoveCtrl
[, impulseMask(x,y,z) -- dimensions in which impulse is allowed to apply when not using MoveCtrl
[, movementMask(x,y,z) -- dimensions in which feature is allowed to move when not using MoveCtrl]]]
As of spring 103.0 it is necessary to unlock feature movement on x,z axis before changing feature physics. For example use "Spring.SetFeatureMoveCtrl(featureID,false,1,1,1,1,1,1,1,1,1)" to unlock all movement prior to making SetFeatureVelocity calls.
Spring.SetFeatureNoSelect
( number featureID,
bool noSelect )
return: nil
Spring.SetFeatureAlwaysVisible
( number featureID,
bool enable )
return: nil
Spring.SetFeatureCollisionVolumeData
( number featureID,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number vType,
number tType,
number Axis )
return: nil
- Check Spring.SetUnitCollisionVolumeData for further explanation of the arguments.
Spring.SetFeaturePieceCollisionVolumeData
( number featureID,
number pieceIndex,
bool enable,
number scaleX, number scaleY, number scaleZ,
number offsetX, number offsetY, number offsetZ,
number Axis,
number volumeType [,
number primaryAxis ] )
return: nil
- New in version 101.0
Spring.SetFeatureMidAndAimPos
( number featureID,
number mpX, number mpY, number mpZ,
number apX, number apY, number apZ [,
bool relative )
return: bool success
- New in version 89.0
Check Spring.SetUnitMidAndAimPos for further explanation of the arguments.
Spring.SetFeatureRadiusAndHeight
( number featureID,
number radius,
number height )
return: bool success
- New in version 89.0
Spring.SetFeatureMass
( number featureID,
number mass )
return: nil
- New in version 101.0
Spring.SetFeatureBlocking
( number featureID,
boolean isBlocking,
boolean isSolidObjectCollidable,
boolean isProjectileCollidable,
boolean isRaySegmentCollidable,
boolean crushable,
boolean blockEnemyPushing,
boolean blockHeightChanges )
return: nil
- New in version 95.0
Changed parameters.
Lua to COB
Spring.CallCOBScript
( number unitID,
number funcID | string funcName,
number retArgs,
COBArg1,
COBArg2,
... )
return: nil | number returnValue, number retArg1, number retArg2, ...
Spring.GetCOBScriptID
( number unitID,
string funcName )
return: nil | number funcID
Spring.GetUnitCOBValue
( number unitID [,
bool splitData=false ],
number COBValue [,
number param1 [,
number param2 [,
number param3 [,
number param4 ]]]] )
return: number result | number result1, number result2
- Note: Don't use Spring.[Get|Set]UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead!
You can find the possible values for `COBValue` in Lua_ConstCOB. Also see Custom_Variables.
Spring.SetUnitCOBValue
( number unitID,
number COBValue,
number param1 [,
number param2 ] )
return: nil
- Note: Don't use Spring.[Get|Set]UnitCOBValue in LUS just because you are familar with it since bos/cob, use the LuaSpringAPI instead!
You can find the possible values for `COBValue` in Lua_ConstCOB. Also see 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"} )
return: nil
Spring.GiveOrderToUnitMap
( unitMap = { [unitID] = example, etc... },
number cmdID,
params = { number, etc...},
options = {"alt", "ctrl", "shift", "right"} )
return: nil
Spring.GiveOrderToUnitArray
( unitArray = { [1] = unitID, etc... },
number cmdID,
params = { number, etc...},
options = {"alt", "ctrl", "shift", "right"} )
return: nil
Spring.GiveOrderArrayToUnitMap
( unitMap = { [number unitID] = example, etc... },
orderArray = { { number cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } } )
return: nil
Spring.GiveOrderArrayToUnitArray
( unitArray = { [1] = number unitID, etc... },
orderArray = { { number cmdID, params = { number, etc...}, options = {"alt", "ctrl", "shift", "right"} } } )
return: nil
Ground
Grass
Spring.AddGrass
( number x,
number z )
return: nil
Spring.RemoveGrass
( number x,
number z )
return: 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 )
return: nil
Spring.AdjustHeightMap
( number x1,
number z1 [,
number x2,
number z2 ],
number height )
return: nil
- (heightmap[x][z] += height;)
Spring.RevertHeightMap
( number x1,
number z1 [,
number x2,
number z2 ],
number origFactor )
return: nil
Spring.SetHeightMapFunc
( lua_function [,
arg1 [,
arg2 [,
... ]]] )
return: nil | number absTotalHeightMapAmountChanged
Example code:
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)
Spring.AddHeightMap
( number x,
number z,
number height )
return: nil | number newHeight
- Can only be called in SetHeightMapFunc()
Spring.SetHeightMap
( number x,
number z,
number height [,
number terraform = 1 ] )
return: nil | number absHeightDiff
- Can only be called in SetHeightMapFunc(). The terraform argument is a scaling factor:
If =0 nothing will be changed (the terraform starts) and if =1 the terraform will be finished.
Spring.LevelSmoothMesh
( number x1,
number z1 [,
number x2,
number z2 ],
number height )
return: nil
Spring.AdjustSmoothMesh
( number x1,
number z1 [,
number x2,
number z2 ],
number height )
return: nil
Spring.RevertSmoothMesh
( number x1,
number z1 [,
number x2,
number z2 ],
number origFactor )
return: nil
Spring.SetSmoothMeshFunc
( lua_function [,
arg1 [,
arg2 [,
... ]]] )
return: nil | number absTotalHeightMapAmountChanged
Spring.AddSmoothMesh
( number x,
number z,
number height )
return: nil | number newHeight
- Can only be called in SetSmoothMeshFunc().
Spring.SetSmoothMesh
( number x,
number z,
number height [,
number terraform = 1 ] )
return: nil | number absHeightDiff
- Can only be called in SetSmoothMeshFunc().
TerrainTypes
Spring.SetMapSquareTerrainType
( number x,
number z,
number newType )
return: nil | number oldType
Spring.SetTerrainTypeData
( number typeIndex [,
number speedTanks = nil [,
number speedKBOts = nil [,
number speedHovers = nil [,
number speedShips = nil ]]]] )
return: nil | bool true
Spring.SetSquareBuildingMask
( number x,
number z,
number mask )
return: nil
- New in version 103.0
See also buildingMask unitdef tag.
MetalAmount
Spring.SetMetalAmount
( number x,
number z,
number metalAmount )
return: nil
- New in version 83.0
x & z coords are in worldspace/16. metalAmount must be between 0 and 255*maxMetal (with maxMetal from the .smd or mapinfo.lua).
Command Descriptions
Doesn't work in unsynced code!
Spring.EditUnitCmdDesc
( number unitID,
number cmdDescID,
table cmdArray )
return: nil
structure of cmdArray:
{
[ id = int ],
[ type = int ],
[ name = string ],
[ action = string ],
[ tooltip = string ],
[ texture = string ],
[ cursor = string ],
[ queueing = boolean ],
[ hidden = boolean ],
[ disabled = boolean ],
[ showUnique = boolean ],
[ onlyTexture = boolean ],
[ params = { string = string, ... } ]
}
queueing is New in version 101.0 and allows custom commands to be non-queueing (handy for state toggles).
Spring.InsertUnitCmdDesc
( number unitID [,
number cmdDescID ],
table cmdArray )
return: nil
Spring.RemoveUnitCmdDesc
( number unitID [,
number cmdDescID ] )
return: nil
Other
Spring.SetNoPause
( bool noPause )
return: nil
Spring.SetUnitToFeature
( bool tofeature )
return: 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) thread
Spring.SetExperienceGrade
( number expGrade [,
number ExpPowerScale [,
number ExpHealthScale [,
number ExpReloadScale ]]] )
return: nil
- expGrade defines how often UnitExperience() will be called.
Prior to 104.0 it is based on the following equation:
(int) [exp/(exp+1)] / expGrade
Post 104.0 it is the raw change.
Spring.SpawnExplosion
( number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
table explosionParams )
return: nil
- New in version 104.0
Possible keys of explosionParams are:
weaponDef = number,
owner = number,
hitUnit = number,
hitFeature = number,
craterAreaOfEffect = number,
damageAreaOfEffect = number,
edgeEffectiveness = number,
explosionSpeed = number,
gfxMod = number,
impactOnly = boolean,
ignoreOwner = boolean,
damageGround = boolean
Please note the explosion defaults to 1 damage regardless of what it's defined in the weaponDef.
The weapondefID is only used for visuals and for passing into callins like UnitDamaged.
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 )
return: nil | bool success, number cegID
- cegID new in 95.0.
Spring.SpawnSFX
( number unitID,
number sfxID,
number posX = 0, number posY = 0, number posZ = 0,
number dirX = 0, number dirY = 0, number dirZ = 0,
number radius = 0,
number damage = 0 [,
bool absolute ] )
return: nil | bool success
- New in version 104.0
Equal to the UnitScript versions of EmitSFX, but takes position and direction arguments (in either unit- or piece-space) instead of a piece index.
Projectiles
Spring.SpawnProjectile
( number weaponDefID,
table projectileParams )
return: 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.DeleteProjectile
( number projectileID )
return: nil
- New in version 101.0
Silently removes projectiles (no explosion).
Pre 95.0:
Spring.SetProjectileTarget
( number projectileID,
[ number targetID, string targetTypeStr ] | [ number posX = 0, number posY = 0, number posZ = 0 ] )
return: nil | bool validTarget
Post 95.0:
Spring.SetProjectileTarget
( number projectileID,
[ number targetID, number targetType ] | [ number posX = 0, number posY = 0, number posZ = 0 ] )
return: nil | bool validTarget
targetTypeStr can be one of:
'u' - unit
'f' - feature
'p' - projectile
while targetTypeInt is one of:
string.byte('g') := GROUND
string.byte('u') := UNIT
string.byte('f') := FEATURE
string.byte('p') := PROJECTILE
Spring.SetProjectileIgnoreTrackingError
( number projectileID,
bool ignore )
return: nil
- New in version 101.0
Spring.SetProjectileIsIntercepted
( number projectileID )
return: nil
- New in version 99.0
Spring.SetProjectileMoveControl
( number projectileID,
bool enable )
return: nil
- Disables engine movecontrol, so lua can fully control the physics.
Spring.SetProjectilePosition
( number projectileID [,
number posX = 0 [,
number posY = 0 [,
number posZ = 0 ]]] )
return: nil
Spring.SetProjectileVelocity
( number projectileID [,
number velX = 0 [,
number velY = 0 [,
number velZ = 0 ]]] )
return: nil
Spring.SetProjectileCollision
( number projectileID )
return: nil
Spring.SetProjectileGravity
( number projectileID [,
number grav = 0 ] )
return: nil
Spring.SetProjectileSpinAngle
( number projectileID [,
number spinAngle = 0 ] )
return: nil
- Removed from version 95.0
Spring.SetProjectileSpinSpeed
( number projectileID [,
number speed = 0 ] )
return: nil
- Removed from version 95.0
Spring.SetProjectileSpinVec
( number projectileID [,
number spinX = 0 [,
number spinY = 0 [,
number spinZ = 0 ]]] )
return: nil
- Removed from version 95.0
Spring.SetProjectileCEG
( number projectileID,
string ceg_name )
return: nil
Spring.SetPieceProjectileParams
( number projectileID [,
number explosionFlags [,
number spinAngle [,
number spinSpeed [,
number spinVector.x [,
number spinVector.y [,
number spinVector.z ]]]]]] )
return: nil
- New in version 95.0
Spring.SetProjectileAlwaysVisible
( number projectileID,
bool alwaysVisible )
return: nil
- New in version 95.0
Spring.SetProjectileDamages
( number unitID,
number weaponNum,
table damages )
return: nil
or
Spring.SetProjectileDamages
( number unitID,
number weaponNum,
string key,
number value )
return: nil
- New in version 101.0
Format of the damages table:
{
["paralyzeDamageTime" = number value,]
["impulseFactor" = number value,]
["impulseBoost" = number value,]
["craterMult" = number value,]
["craterBoost" = number value,]
["dynDamageExp" = number value,]
["dynDamageMin" = number value,]
["dynDamageRange" = number value,]
["dynDamageInverted" = number value,] (<>0.0f := true)
["craterAreaOfEffect" = number value,]
["damageAreaOfEffect" = number value,]
["edgeEffectiveness" = number value,]
["explosionSpeed" = number value,]
[number armorType = number value,] (changes the damage against this armor type)
}