Lua UnitDefs

Development < Lua Scripting < Lua 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:

• 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,
    maxx = 17.423709869385,
    maxy = 48.386325836182,
    maxz = 14.10532283783,
    metalCost = 2667,
    metalMake = 1.5,
    metalStorage = 0,
    metalUpkeep = 0,
    midx = 0.66120779514313,
    midy = 19,
    midz = 1.7122877836227,
    minAirBasePower = 0,
    minCollisionSpeed = 1,
    minWaterDepth = -10000000,
    minx = -16.537784576416,
    miny = 0.058725833892822,
    minz = -9.709508895874,
    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 = {
        name = "CORCOM.s3o",
        path = "objects3d/CORCOM.s3o",
        type = "s3o",
        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.

---