Lua UnitDefs
More actions
Development < Lua Scripting < Lua UnitDefs
Were you looking for the unitDefs page for Game Developers? (Gamedev:UnitDefs)
What is this
The UnitDefs[] table holds information about the unittypes 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,
UnitDefs[unitDefID].name
Note:
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:
local unitDef = UnitDefNames["supertank"]
Print all unitDefs
This example code prints all unitdefs, with all keys and their values (but not their subtables).
for id,unitDef in pairs(UnitDefs) do
for name,param in unitDef:pairs() do
Spring.Echo(name,param)
end
end
Note that unitDef is a metatable, and requires the special iterator unitDef:pairs()
Useful keys/snippets
UnitDefs[unitDefID].id - gives back the unitDefID
UnitDefs[unitDefID].name - the internal unit name
UnitDefs[unitDefID].humanName - the displayed unit name
UnitDefs[unitDefID].weapons - See Lua_WeaponDefs, UnitDefs[unitDefID].weapons[1].weaponDef returns the weaponDefID of the units first weapon, which apppears in the WeaponsDef table as WeaponDefs[weaponDefID].
To read custom parameters use:
local myCustomParameters = UnitDefs[unitDefID].customParams
if (myCustomParameters) then
blub = myCustomParameters.blubfactor
end
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,4e58b8b0</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.
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,
...
},
},
...
},
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
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")
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.
<references/>