Qrow: 1 revision imported

2026-02-24T05:52:24Z

1 revision imported

← Older revision	Revision as of 22:52, 23 February 2026
(No difference)

luainter>Raaar: moved min/mid/max properties of the model inside the model subtable and name, type and path being outside of it to match what's available on recent versions

2023-12-29T16:38:39Z

moved min/mid/max properties of the model inside the model subtable and name, type and path being outside of it to match what's available on recent versions

New page

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

'''Were you looking for the unitDefs page for Game Developers?''' ([[Gamedev:UnitDefs]])

==What is this==
The '''UnitDefs[]''' table holds information about the unit'''types''' used in the game. It is indexed by a number, and normally refered to as unitDefID. It is read-only. To access its tags you write, for example,
<pre>
UnitDefs[unitDefID].name
</pre>

'''Note:'''<br>
The name of the keys often vary from the ones in the [[Gamedev:UnitDefs]] files.
For example ''maxDamage'' is named ''health''.

==UnitDefs reverse lookup: UnitDefNames==
The '''UnitDefNames[]''' table holds the unitdefs and can be used to get the unitdef table for a known unitname:
<pre>
local unitDef = UnitDefNames["supertank"]
</pre>

==Print all unitDefs==
This example code prints all unitdefs, with all keys and their values (but not their subtables).
<pre>
for id,unitDef in pairs(UnitDefs) do
for name,param in unitDef:pairs() do
Spring.Echo(name,param)
end
end
</pre>
Note that unitDef is a metatable, and requires the special iterator unitDef:pairs()

==Useful keys/snippets==
<code> UnitDefs[unitDefID].id </code> - gives back the unitDefID

<code> UnitDefs[unitDefID].name </code> - the internal unit name

<code> UnitDefs[unitDefID].humanName </code> - the displayed unit name

<code>UnitDefs[unitDefID].weapons</code> - See [[Lua_WeaponDefs]], <code>UnitDefs[unitDefID].weapons[1].weaponDef</code> returns the weaponDefID of the units first weapon, which apppears in the WeaponsDef table as <code>WeaponDefs[weaponDefID]</code>.

To read [[Gamedev:UnitDefs#customParams|custom parameters]] use:
<pre>
local myCustomParameters = UnitDefs[unitDefID].customParams
if (myCustomParameters) then
blub = myCustomParameters.blubfactor
end
</pre>
Key-names of the customParams table written must be lowercase and their values can only be strings.

===Types of Units===
Sometimes one wants to check type of unit. Like is it a factory, is it a transport and so on.
Complete list: <ref>''Spring 95, commit message'',{{Sourcelinkhash|4e58b8b0f7af04065878d34e5e17523246739b0c}}</ref>

*isTransport
*isImmobile
*isBuilding
*isBuilder
*isMobileBuilder
*isStaticBuilder
*isFactory
*isExtractor
*isGroundUnit
*isAirUnit
*isStrafingAirUnit
*isHoveringAirUnit
*isFighterAirUnit
*isBomberAirUnit

==Example UnitDef table==
In the form of key = value, where UnitDefs[unitDefID].key = value, with subtables at the bottom.

<pre>
activateWhenBuilt = true,
airLosRadius = 5.2734375,
airStrafe = true,
armorType = 3,
armoredMultiple = 1,
autoHeal = 2.5,
bankingAllowed = true,
buildDistance = 112,
buildRange3D = false,
buildSpeed = 300,
buildTime = 75000,
builder = false,
buildingDecalDecaySpeed = 0.10000000149012,
buildingDecalSizeX = 4,
buildingDecalSizeY = 4,
buildingDecalType = -1,
buildpicname = "CORCOM.DDS",
canAssist = true,
canAttack = true,
canAttackWater = true,
canBeAssisted = true,
canCapture = true,
canCloak = true,
canCrash = false,
canDGun = false,
canDropFlare = false,
canFight = true,
canFireControl = true,
canFly = false,
canGuard = true,
canKamikaze = false,
canLoopbackAttack = false,
canManualFire = true,
canMove = true,
canParalyze = false,
canPatrol = true,
canReclaim = true,
canRepair = true,
canRepeat = true,
canRestore = true,
canResurrect = false,
canSelfD = true,
canSelfRepair = false,
canStockpile = false,
canSubmerge = false,
cantBeTransported = false,
capturable = true,
captureSpeed = 900,
cloakCost = 100,
cloakCostMoving = 1000,
cloakTimeout = 128,
cobID = -1,
collide = true,
cost = 3111.4499511719,
crashDrag = 0.0049999998882413,
deathExplosion = "commander_blast",
decloakDistance = 50,
decloakOnFire = true,
decloakSpherical = true,
dlHoverFactor = -1,
energyCost = 26667,
energyMake = 25,
energyStorage = 0,
energyUpkeep = 0,
extractRange = 0,
extractsMetal = 0,
factoryHeadingTakeoff = true,
fallSpeed = 0.20000000298023,
fireState = -1,
flankingBonusDirX = 0,
flankingBonusDirY = 0,
flankingBonusDirZ = 1,
flankingBonusMax = 1.8999999761581,
flankingBonusMin = 0.89999997615814,
flankingBonusMobilityAdd = 0.0099999997764826,
flankingBonusMode = 1,
flareDelay = 0.30000001192093,
flareDropVectorX = 0,
flareDropVectorY = 0,
flareDropVectorZ = 0,
flareEfficiency = 0.5,
flareReloadTime = 5,
flareSalvoDelay = 0,
flareSalvoSize = 4,
flareTime = 90,
floatOnWater = false,
floater = false,
frontToSpeed = 0.10000000149012,
fullHealthFactory = false,
hasShield = false,
health = 3000,
height = 50,
hideDamage = true,
highTrajectoryType = 0,
holdSteady = false,
hoverAttack = false,
humanName = "Commander",
iconType = "corcom.user",
id = 261,
idleAutoHeal = 2.5,
idleTime = 1800,
isAirBase = false,
isAirUnit = false,
isBomberAirUnit = false,
isBuilder = true,
isBuilding = false,
isCommander = false,
isExtractor = false,
isFactory = false,
isFeature = false,
isFighterAirUnit = false,
isFirePlatform = false,
isGroundUnit = true,
isHoveringAirUnit = false,
isImmobile = false,
isMobileBuilder = true,
isStaticBuilder = false,
isStrafingAirUnit = false,
isTransport = false,
jammerRadius = 0,
kamikazeDist = 0,
kamikazeUseLOS = false,
leaveTracks = false,
levelGround = true,
loadingRadius = 220,
losHeight = 40,
losRadius = 14.0625,
makesMetal = 0,
mass = 5000,
maxAcc = 0.18000000715256,
maxAileron = 0.014999999664724,
maxBank = 0.80000001192093,
maxCoverage = 0,
maxDec = 1.125,
maxElevator = 0.0099999997764826,
maxFuel = 0,
maxHeightDif = 14.558809280396,
maxPitch = 0.44999998807907,
maxRepairSpeed = 300,
maxRudder = 0.0040000001899898,
maxSlope = -1,
maxThisUnit = 32000,
maxWaterDepth = 35,
maxWeaponRange = 300,
metalCost = 2667,
metalMake = 1.5,
metalStorage = 0,
metalUpkeep = 0,
minAirBasePower = 0,
minCollisionSpeed = 1,
minWaterDepth = -10000000,
modelname = "CORCOM.s3o",
modelpath = "objects3d/CORCOM.s3o",
modeltype = "s3o",
moveState = -1,
myGravity = 0.40000000596046,
name = "corcom",
nanoColorB = 0.20000000298023,
nanoColorG = 0.69999998807907,
nanoColorR = 0.20000000298023,
needGeo = false,
onOffable = false,
power = 3111.4499511719,
primaryWeapon = 2,
rSpeed = 0,
radarRadius = 700,
radius = 22,
reclaimSpeed = 300,
reclaimable = false,
refuelTime = 5,
releaseHeld = false,
reloadTime = 1,
repairSpeed = 300,
repairable = true,
resurrectSpeed = 300,
scriptName = "corcom.cob",
scriptPath = "corcom.cob",
seismicRadius = 0,
seismicSignature = 0,
selfDCountdown = 5,
selfDExplosion = "commander_blast",
shieldPower = -1,
showNanoFrame = true,
showNanoSpray = true,
showPlayerName = true,
slideTolerance = 0,
sonarJamRadius = 0,
sonarRadius = 300,
sonarStealth = false,
speed = 37.5,
speedToFront = 0.070000000298023,
startCloaked = false,
stealth = false,
strafeToAttack = false,
targfac = false,
techLevel = 0,
terraformSpeed = 1500,
tidalGenerator = 0,
tooltip = "Commander",
totalEnergyOut = 25,
trackOffset = 0,
trackStrength = 0,
trackStretch = 1,
trackType = -1,
trackWidth = 32,
transportByEnemy = false,
transportCapacity = 0,
transportMass = 100000,
transportSize = 0,
transportUnloadMethod = 0,
turnInPlace = true,
turnInPlaceSpeedLimit = 0.82499998807907,
turnRadius = 500,
turnRate = 1133,
type = "",
unitFallSpeed = 0,
upright = true,
useBuildingGroundDecal = false,
useSmoothMesh = true,
verticalSpeed = 3,
wantedHeight = 0,
waterline = 0,
windGenerator = 0,
wingAngle = 0.079999998211861,
wingDrag = 0.070000000298023,
wreckName = "corcom_dead",
xsize = 4,
zsize = 4,

buildOptions = {
[1] = unitDefID1,
[2] = unitDefID2,
...
},
collisionVolume = {
boundingRadius = 1.0893974967364e-026,
defaultToFootPrint = false,
defaultToPieceTree = false,
defaultToSphere = false,
offsetX = 0,
offsetY = 1,
offsetZ = 1.089395031546e-026,
scaleX = 6.4911419586111e-027,
scaleY = 1.9340968033141e-038,
scaleZ = 1.0894122878784e-026,
type = "ellipsoid",
},
customParams = {
...
},
modCategories = {
all = true,
commander = true,
notair = true,
...
},
model = {
minx = -16.537784576416,
miny = 0.058725833892822,
minz = -9.709508895874,
midx = 0.66120779514313,
midy = 19,
midz = 1.7122877836227,
maxx = 17.423709869385,
maxy = 48.386325836182,
maxz = 14.10532283783,
textures = {
tex1 = "Core_color.dds",
tex2 = "Core_other.dds",
},
},
moveDef = {
crushStrength = 50,
depth = 5000,
depthMod = 0,
family = "kbot",
heatMapping = false,
heatMod = 0.0041666668839753,
heatProduced = 60,
id = 6,
maxSlope = 0.41221469640732,
name = "akbot2",
slopeMod = 9.6801977157593,
type = "ground",
xsize = 3,
zsize = 3,
},
noChaseCategories = {
all = true,
...
},
sounds = {
activate = {},
arrived = {},
build = {
[1] = {
id = 208,
name = "nanlath2",
volume = 1,
},
...
},
...
},
weapons = {
[1] = {
fuelUsage = 0,
mainDirX = 0,
mainDirY = 0,
mainDirZ = 0.99999564886093,
maxAngleDif = -1,
slavedTo = 0,
weaponDef = 221,
badTargets = {
vtol = true,
},
onlyTargets = {
all = true,
antiemg = true,
...
},
},
...
},
</pre>

==Unit/Weapon damages and armor classes==

For details on how to extract which units/weapons target/damage which units, see https://springrts.com/phpbb/viewtopic.php?f=44&t=34382&p=575738#p575738 (TODO: migrate info to wiki).

==How to save unitDef tables to file==
To save all unitDefs to a file, including all tables, you can use
<pre>
local unitDef = UnitDefs[unitDefID]
local t = {}
for k,v in unitDef:pairs() do
t[k] = v
end
table.save(t, "lua_unitDef_" .. unitDef.name .. ".lua", "-- generated by table.save")
</pre>
The special iterator is needed because metatables. See https://springrts.com/phpbb/viewtopic.php?f=67&t=33778 for a widget to regenerate the example defs.

[[category: Lua]]

----
<references/>

Lua UnitDefs - Revision history

Qrow: 1 revision imported

luainter>Raaar: moved min/mid/max properties of the model inside the model subtable and name, type and path being outside of it to match what's available on recent versions