Lua UnitDefs: Difference between revisions

From Spring
Jump to navigationJump to search
← Older edit
No edit summary
Raaar (talk | contribs)
0 edits
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
 
(34 intermediate revisions by 10 users not shown)
Line 1: Line 1:
<font style="font-size:125%" color="#55ee99">The UnitDefs[] table holds all information about the units used in the mod.
[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}
Note: Its entries are metatables, so you can't use the pairs() iterator on them, use this instead:</font>
 
<font style="font-size:110%" color="lightblue">
'''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 id,unitDef in pairs(UnitDefs) do
     for name,param in unitDef:pairs() do
     for name,param in unitDef:pairs() do
Line 7: Line 27:
     end
     end
   end
   end
</font>
</pre>
<font style="font-size:125%" color="#55ee99">Very usefull is UnitDefs[i]["customParams"], since you can access any custom fbi param with it and use it in your lua scripts.</font>
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


<font style="font-size:125%" color="#55ee99">So because the UnitDefs tables are very large, I simple print here an example of it (BA5.8 core commander):</font>
<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.


  '''UnitDefs['''216''']["customParams"]''' = {
    } <font color="#55ee99">Variable names written must be lowercase and variables can only be strings.</font>
  '''UnitDefs['''216''']["TEDClass"]''' = "COMMANDER",
  '''UnitDefs['''216''']["activateWhenBuilt"]''' = true,
  '''UnitDefs['''216''']["aihint"]''' = 216,
  '''UnitDefs['''216''']["cobID"]''' = -1,
  '''UnitDefs['''216''']["airLosRadius"]''' = 21.09375,
  '''UnitDefs['''216''']["airStrafe"]''' = true,
  '''UnitDefs['''216''']["armorType"]''' = 8,
  '''UnitDefs['''216''']["armoredMultiple"]''' = 1,
  '''UnitDefs['''216''']["autoHeal"]''' = 2.6666667461395,
  '''UnitDefs['''216''']["bankingAllowed"]''' = false,
  '''UnitDefs['''216''']["buildDistance"]''' = 128,
  '''UnitDefs['''216''']["buildOptions"]''' = {
      '''[1]''' = unitDefID1,
      '''[2]''' = unitDefID2,
      ...
    }
  '''UnitDefs['''216''']["buildRange3D"] = true,
  '''UnitDefs['''216''']["buildSpeed"]''' = 300,
  '''UnitDefs['''216''']["buildTime"]''' = 75000,
  '''UnitDefs['''216''']["buildangle"]''' = 0,
  '''UnitDefs['''216''']["builder"]''' = true,
  '''UnitDefs['''216''']["buildingDecalDecaySpeed"]''' = 0.10000000149012,
  '''UnitDefs['''216''']["buildingDecalSizeX"]''' = 4,
  '''UnitDefs['''216''']["buildingDecalSizeY"]''' = 4,
  '''UnitDefs['''216''']["buildingDecalType"]''' = 0,
  '''UnitDefs['''216''']["buildpicname"]''' = "CORCOM.DDS",
  '''UnitDefs['''216''']["canAssist"]''' = true,
  '''UnitDefs['''216''']["canAttack"]''' = true,
  '''UnitDefs['''216''']["canBeAssisted"]''' = true,
  '''UnitDefs['''216''']["canBuild"]''' = true,
  '''UnitDefs['''216''']["canCapture"]''' = true,
  '''UnitDefs['''216''']["canCloak"]''' = true,
  '''UnitDefs['''216''']["canCrash"]''' = true,
  '''UnitDefs['''216''']["canDGun"]''' = true,
  '''UnitDefs['''216''']["canDropFlare"]''' = false,
  '''UnitDefs['''216''']["canFight"]''' = true,
  '''UnitDefs['''216''']["canFireControl"]''' = true,
  '''UnitDefs['''216''']["canFly"]''' = false,
  '''UnitDefs['''216''']["canGuard"]''' = true,
  '''UnitDefs['''216''']["canHover"]''' = false,
  '''UnitDefs['''216''']["canKamikaze"]''' = false,
  '''UnitDefs['''216''']["canLoopbackAttack"]''' = false,
  '''UnitDefs['''216''']["canMove"]''' = true,
  '''UnitDefs['''216''']["canPatrol"]''' = true,
  '''UnitDefs['''216''']["canReclaim"]''' = true,
  '''UnitDefs['''216''']["canRepair"]''' = true,
  '''UnitDefs['''216''']["canRepeat"]''' = true,
  '''UnitDefs['''216''']["canRestore"]''' = true,
  '''UnitDefs['''216''']["canResurrect"]''' = false,
  '''UnitDefs['''216''']["canSelfRepair"]''' = false,
  '''UnitDefs['''216''']["canSubmerge"]''' = false,
  '''UnitDefs['''216''']["capturable"]''' = false,
  '''UnitDefs['''216''']["captureSpeed"]''' = 300,
  '''UnitDefs['''216''']["cloakCost"]''' = 100,
  '''UnitDefs['''216''']["cloakCostMoving"]''' = 1000,
  '''UnitDefs['''216''']["collide"]''' = true,
  '''UnitDefs['''216''']["controlRadius"]''' = 32,
  '''UnitDefs['''216''']["crashDrag"]''' = 32,
  '''UnitDefs['''216''']["deathExplosion"]''' = "COMMANDER_BLAST",
  '''UnitDefs['''216''']["decloakDistance"]''' = 50,
  '''UnitDefs['''216''']["decloakOnFire"]''' = true,
  '''UnitDefs['''216''']["decloakSpherical"]''' = true,
  '''UnitDefs['''216''']["decoyDef"]''' = nil,
  '''UnitDefs['''216''']["dlHoverFactor"]''' = -1,
  '''UnitDefs['''216''']["drag"]''' = 0.13046109676361,
  '''UnitDefs['''216''']["energyCost"]''' = 2500,
  '''UnitDefs['''216''']["energyMake"]''' = 25,
  '''UnitDefs['''216''']["energyStorage"]''' = 0,
  '''UnitDefs['''216''']["energyUpkeep"]''' = 0,
  '''UnitDefs['''216''']["extractRange"]''' = 0,
  '''UnitDefs['''216''']["extractsMetal"]''' = 0,
  '''UnitDefs['''216''']["extractSquare"]''' = false,
  '''UnitDefs['''216''']["factoryHeadingTakeoff"] = false,
  '''UnitDefs['''216''']["fallSpeed"]''' = 1,
  '''UnitDefs['''216''']["filename"]''' = "units/corcom.fbi",
  '''UnitDefs['''216''']["fireState"]''' = 1,


  '''UnitDefs['''216''']["flankingBonusMode"]''' = 0,
  '''UnitDefs['''216''']["flankingBonusMax"]''' = 0,
  '''UnitDefs['''216''']["flankingBonusMin"]''' = 0,
  '''UnitDefs['''216''']["flankingBonusDirX"]''' = 0,
  '''UnitDefs['''216''']["flankingBonusDirY"]''' = 0,
  '''UnitDefs['''216''']["flankingBonusDirZ"]''' = 0,
  '''UnitDefs['''216''']["flankingBonusMobilityAdd"]''' = 0,


  '''UnitDefs['''216''']["flareDelay"]''' = 0.30000001192093,
[[category: Lua]]
  '''UnitDefs['''216''']["flareDropVectorX"]''' = 0,
  '''UnitDefs['''216''']["flareDropVectorY"]''' = 0,
  '''UnitDefs['''216''']["flareDropVectorZ"]''' = 0,
  '''UnitDefs['''216''']["flareEfficiency"]''' = 0.5,
  '''UnitDefs['''216''']["flareReloadTime"]''' = 5,
  '''UnitDefs['''216''']["flareSalvoDelay"]''' = 0,
  '''UnitDefs['''216''']["flareSalvoSize"]''' = 4,
  '''UnitDefs['''216''']["flareTime"]''' = 90,


  '''UnitDefs['''216''']["floater"]''' = false,
----
  '''UnitDefs['''216''']["frontToSpeed"]''' = 0.10000000149012,
<references/>
  '''UnitDefs['''216''']["fullHealthFactory"]''' = false,
  '''UnitDefs['''216''']["gaia"]''' = "",
  '''UnitDefs['''216''']["health"]''' = 3000,
  '''UnitDefs['''216''']["height"]''' = 42.333557128906,
  '''UnitDefs['''216''']["hideDamage"]''' = true,
  '''UnitDefs['''216''']["highTrajectoryType"]''' = 0,
  '''UnitDefs['''216''']["holdSteady"]''' = true,
  '''UnitDefs['''216''']["hoverAttack"]''' = false,
  '''UnitDefs['''216''']["humanName"]''' = "Commander",
  '''UnitDefs['''216''']["iconType"]''' = "corcommander",
  '''UnitDefs['''216''']["id"]''' = 216,
  '''UnitDefs['''216''']["idleAutoHeal"]''' = 2.6666667461395,
  '''UnitDefs['''216''']["idleTime"]''' = 1800,
  '''UnitDefs['''216''']["isAirBase"]''' = false,
  '''UnitDefs['''216''']["isBomber"]''' = false,
  '''UnitDefs['''216''']["isBuilder"]''' = true,
  '''UnitDefs['''216''']["isBuilding"]''' = false,
  '''UnitDefs['''216''']["isCommander"]''' = true,
  '''UnitDefs['''216''']["isFactory"]''' = false,
  '''UnitDefs['''216''']["isFeature"]''' = false,
  '''UnitDefs['''216''']["isFighter"]''' = false,
  '''UnitDefs['''216''']["isFirePlatform"]''' = false,
  '''UnitDefs['''216''']["isGroundUnit"]''' = false,
  '''UnitDefs['''216''']["isMetalExtractor"]''' = false,
  '''UnitDefs['''216''']["isMetalMaker"]''' = false,
  '''UnitDefs['''216''']["isTransport"]''' = false,
  '''UnitDefs['''216''']["jammerRadius"]''' = 0,
  '''UnitDefs['''216''']["kamikazeDist"]''' = 0,
  '''UnitDefs['''216''']["leaveTracks"]''' = false,
  '''UnitDefs['''216''']["levelGround"]''' = true,
  '''UnitDefs['''216''']["loadingRadius"]''' = 220,
  '''UnitDefs['''216''']["losHeight"]''' = 20,
  '''UnitDefs['''216''']["losRadius"]''' = 28.125,
  '''UnitDefs['''216''']["makesMetal"]''' = 0,
  '''UnitDefs['''216''']["mass"]''' = 5000,
  '''UnitDefs['''216''']["maxAcc"]''' = 0.18000000715256,
  '''UnitDefs['''216''']["maxAileron"]''' = 0.014999999664724,
  '''UnitDefs['''216''']["maxBank"]''' = 0.80000001192093,
  '''UnitDefs['''216''']["maxCoverage"]''' = 1000.0,
  '''UnitDefs['''216''']["maxDec"]''' = 0.037500001490116,
  '''UnitDefs['''216''']["maxElevator"]''' = 0.0099999997764826,
  '''UnitDefs['''216''']["maxFuel"]''' = 0,
  '''UnitDefs['''216''']["maxHeightDif"]''' = 14.558809280396,
  '''UnitDefs['''216''']["maxPitch"]''' = 0.44999998807907,
  '''UnitDefs['''216''']["maxRepairSpeed"]''' = 300,
  '''UnitDefs['''216''']["maxRudder"]''' = 0.0040000001899898,
  '''UnitDefs['''216''']["maxSlope"]''' = 0.93969261646271,
  '''UnitDefs['''216''']["maxThisUnit"]''' = 5000,
  '''UnitDefs['''216''']["maxWaterDepth"]''' = 35,
  '''UnitDefs['''216''']["maxWeaponRange"]''' = 300,
  '''UnitDefs['''216''']["maxx"]''' = 17.456253051758,
  '''UnitDefs['''216''']["maxy"]''' = 42.333557128906,
  '''UnitDefs['''216''']["maxz"]''' = 22.837493896484,
  '''UnitDefs['''216''']["metalCost"]''' = 2500,
  '''UnitDefs['''216''']["metalMake"]''' = 1.5,
  '''UnitDefs['''216''']["metalStorage"]''' = 0,
  '''UnitDefs['''216''']["metalUpkeep"]''' = 0,
  '''UnitDefs['''216''']["midx"]''' = 0,
  '''UnitDefs['''216''']["midy"]''' = 19.558204650879,
  '''UnitDefs['''216''']["midz"]''' = 0,
  '''UnitDefs['''216''']["minAirBasePower"]''' = 0,
  '''UnitDefs['''216''']["minCollisionSpeed"]''' = 1,
  '''UnitDefs['''216''']["minWaterDepth"]''' = -10000000,
  '''UnitDefs['''216''']["minx"]''' = -17.456253051758,
  '''UnitDefs['''216''']["miny"]''' = -3.2171478271484,
  '''UnitDefs['''216''']["minz"]''' = -9.9750061035156,
  '''UnitDefs['''216''']["modCategories"]''' = {
      '''["notship"]''' = false,
      '''["notair"]''' = false,
      '''["core"]''' = false,
      '''["commander"]''' = false,
      '''["all"]''' = false,
      '''["level10"]''' = false,
      '''["ctrl_c"]''' = false,
      '''["notsub"]''' = false,
      '''["weapon"]''' = false,
    }
  '''UnitDefs['''216''']["model"]''' = {
      '''["textures"]''' = {
      }
      '''["type"]''' = "3do",
      '''["name"]''' = "CORCOM",
      '''["path"]''' = "objects3d/CORCOM",
    }
  '''UnitDefs['''216''']["moveData"]''' = {
      '''["name"]''' = "KBOT3",
      '''["type"]''' = "ground",
      '''["maxSlope"]''' = 0.41221475601196,
      '''["id"]''' = 2,
      '''["depthMod"]''' = 0.10000000149012,
      '''["crushStrength"]''' = 50,
      '''["family"]''' = "kbot",
      '''["depth"]''' = 5000,
      '''["slopeMod"]''' = 9.680196762085,
      '''["size"]''' = 4,
    }
  '''UnitDefs['''216''']["moveState"]''' = 1,
  '''UnitDefs['''216''']["moveType"]''' = 0,
  '''UnitDefs['''216''']["myGravity"]''' = 0.40000000596046,
  '''UnitDefs['''216''']["name"]''' = "corcom",
  '''UnitDefs['''216''']["nanoColorB"]''' = 0.20000000298023,
  '''UnitDefs['''216''']["nanoColorG"]''' = 0.69999998807907,
  '''UnitDefs['''216''']["nanoColorR"]''' = 0.20000000298023,
  '''UnitDefs['''216''']["needGeo"]''' = false,
  '''UnitDefs['''216''']["noChaseCategories"]''' = {
      '''["all"]''' = false,
    }
  '''UnitDefs['''216''']["onOffable"]''' = false,
  '''UnitDefs['''216''']["pieceTrailCEGTag"]''' = "",
  '''UnitDefs['''216''']["pieceTrailCEGRange"]''' = 0,
  '''UnitDefs['''216''']["power"]''' = 2541.6667480469,
  '''UnitDefs['''216''']["radarRadius"]''' = 700,
  '''UnitDefs['''216''']["radius"]''' = 24.740692138672,
  '''UnitDefs['''216''']["reclaimSpeed"]''' = 300,
  '''UnitDefs['''216''']["reclaimable"]''' = false,
  '''UnitDefs['''216''']["refuelTime"]''' = 5,
  '''UnitDefs['''216''']["releaseHeld"]''' = false,
  '''UnitDefs['''216''']["repairSpeed"]''' = 300,
  '''UnitDefs['''216''']["resurrectSpeed"]''' = 300,
  '''UnitDefs['''216''']["scriptName"]''' = "armcom.cob",
  '''UnitDefs['''216''']["scriptPath"]''' = "scripts/armcom.cob",
  '''UnitDefs['''216''']["seismicRadius"]''' = 0,
  '''UnitDefs['''216''']["seismicSignature"]''' = 0,
  '''UnitDefs['''216''']["selfDCountdown"]''' = 5,
  '''UnitDefs['''216''']["selfDExplosion"]''' = "COMMANDER_BLAST",
  '''UnitDefs['''216''']["shieldWeaponDef"]''' = nil,
  '''UnitDefs['''216''']["showNanoFrame"]''' = true,
  '''UnitDefs['''216''']["showNanoSpray"]''' = true,
  '''UnitDefs['''216''']["showPlayerName"]''' = true,
  '''UnitDefs['''216''']["slideTolerance"]''' = 0,
  '''UnitDefs['''216''']["smoothAnim"]''' = true,
  '''UnitDefs['''216''']["sonarJamRadius"]''' = 0,
  '''UnitDefs['''216''']["sonarRadius"]''' = 300,
  '''UnitDefs['''216''']["sonarStealth"]''' = false,
  '''UnitDefs['''216''']["sounds"]''' = {
      '''["repair"]''' = {
      }
      '''["arrived"]''' = {
      }
      '''["underattack"]''' = {
        '''[1]''' = {
          '''["id"]''' = 140,
          '''["name"]''' = "warning2",
          '''["volume"]''' = 5,
        }
      }
      '''["select"]''' = {
        '''[1]''' = {
          '''["id"]''' = 213,
          '''["name"]''' = "kccorsel",
          '''["volume"]''' = 5,
        }
      }
      '''["deactivate"]''' = {
      }
      '''["activate"]''' = {
      }
      '''["ok"]''' = {
        '''[1]''' = {
          '''["id"]''' = 212,
          '''["name"]''' = "kcormov",
          '''["volume"]''' = 5,
        }
      }
      '''["cant"]''' = {
        '''[1]''' = {
          '''["id"]''' = 92,
          '''["name"]''' = "cantdo4",
          '''["volume"]''' = 5,
        }
      }
      '''["working"]''' = {
      }
      '''["build"]''' = {
        '''[1]''' = {
          '''["id"]''' = 197,
          '''["name"]''' = "nanlath2",
          '''["volume"]''' = 5,
        }
      }
    }
  '''UnitDefs['''216''']["speed"]''' = 37.5,
  '''UnitDefs['''216''']["speedToFront"]''' = 0.070000000298023,
  '''UnitDefs['''216''']["springCategories"]''' = {
      '''["commander"]''' = false,
      '''["notship"]''' = false,
      '''["notair"]''' = false,
      '''["all"]''' = false,
      '''["notsub"]''' = false,
      '''["weapon"]''' = false,
    }
  '''UnitDefs['''216''']["startCloaked"]''' = false,
  '''UnitDefs['''216''']["stealth"]''' = false,
  '''UnitDefs['''216''']["stockpileWeaponDef"]''' = nil,
  '''UnitDefs['''216''']["strafeToAttack"]''' = false,
  '''UnitDefs['''216''']["targfac"]''' = false,
  '''UnitDefs['''216''']["techLevel"]''' = 0,
  '''UnitDefs['''216''']["terraformSpeed"]''' = 300,
  '''UnitDefs['''216''']["tidalGenerator"]''' = 0,
  '''UnitDefs['''216''']["tooltip"]''' = "Commander",
  '''UnitDefs['''216''']["totalEnergyOut"]''' = 25,
  '''UnitDefs['''216''']["trackOffset"]''' = 0,
  '''UnitDefs['''216''']["trackStrength"]''' = 0,
  '''UnitDefs['''216''']["trackStretch"]''' = 1,
  '''UnitDefs['''216''']["trackType"]''' = 0,
  '''UnitDefs['''216''']["trackWidth"]''' = 32,
  '''UnitDefs['''216''']["transportByEnemy"]''' = true,
  '''UnitDefs['''216''']["transportCapacity"]''' = 0,
  '''UnitDefs['''216''']["transportMass"]''' = 100000,
  '''UnitDefs['''216''']["transportSize"]''' = 0,
  '''UnitDefs['''216''']["transportUnloadMethod"]''' = 0,
  '''UnitDefs['''216''']["turnRadius"]''' = 500,
  '''UnitDefs['''216''']["turnRate"]''' = 1133,
  '''UnitDefs['''216''']["type"]''' = "Builder",
  '''UnitDefs['''216''']["unitFallSpeed"]''' = 1.0,
  '''UnitDefs['''216''']["upright"]''' = true,
  '''UnitDefs['''216''']["useBuildingGroundDecal"]''' = false,
  '''UnitDefs['''216''']["wantedHeight"]''' = 0,
  '''UnitDefs['''216''']["waterline"]''' = 0,
  '''UnitDefs['''216''']["weapons"]''' = {
      '''[1]''' = {
        '''["onlyTargets"]''' = {
          '''["antiflame"]''' = false,
          '''["vtol"]''' = false,
          '''["notland"]''' = false,
          '''["fort"]''' = false,
          '''["special"]''' = false,
          '''["notair"]''' = false,
          '''["kbot"]''' = false,
          '''["antiemg"]''' = false,
          '''["commander"]''' = false,
          '''["jam"]''' = false,
          '''["tport"]''' = false,
          '''["constr"]''' = false,
          '''["strategic"]''' = false,
          '''["kamikaze"]''' = false,
          '''["minelayer"]''' = false,
          '''["hover"]''' = false,
          '''["noweapon"]''' = false,
          '''["plant"]''' = false,
          '''["ship"]''' = false,
          '''["antilaser"]''' = false,
          '''["phib"]''' = false,
          '''["mine"]''' = false,
          '''["notstructure"]''' = false,
          '''["tank"]''' = false,
          '''["mobile"]''' = false,
          '''["underwater"]''' = false,
          '''["antigator"]''' = false,
          '''["notship"]''' = false,
          '''["all"]''' = false,
          '''["notsub"]''' = false,
          '''["weapon"]''' = false,
        }
        '''["weaponDef"]''' = 39,
        '''["slavedTo"]''' = 0,
        '''["badTargets"]''' = {
          '''["antilaser"]''' = false,
        }
        '''["fuelUsage"]''' = 0,
        '''["mainDirX"]'''  = 0,
        '''["mainDirY"]'''  = 0,
        '''["mainDirZ"]'''  = 1,
        '''["maxAngleDif"]''' = -1,
      }
      '''[2]''' = {
        '''["onlyTargets"]''' = {
        }
        '''["weaponDef"]''' = 195,
        '''["slavedTo"]''' = 0,
        '''["badTargets"]''' = {
        }
        '''["fuelUsage"]''' = 0,
        '''["maxAngleDif"]''' = -1,
      }
      '''[3]''' = {
        '''["onlyTargets"]''' = {
          '''["antiflame"]''' = false,
          '''["vtol"]''' = false,
          '''["notland"]''' = false,
          '''["fort"]''' = false,
          '''["special"]''' = false,
          '''["notair"]''' = false,
          '''["kbot"]''' = false,
          '''["antiemg"]''' = false,
          '''["commander"]''' = false,
          '''["jam"]''' = false,
          '''["tport"]''' = false,
          '''["constr"]''' = false,
          '''["strategic"]''' = false,
          '''["kamikaze"]''' = false,
          '''["minelayer"]''' = false,
          '''["hover"]''' = false,
          '''["noweapon"]''' = false,
          '''["plant"]''' = false,
          '''["ship"]''' = false,
          '''["antilaser"]''' = false,
          '''["phib"]''' = false,
          '''["mine"]''' = false,
          '''["notstructure"]''' = false,
          '''["tank"]''' = false,
          '''["mobile"]''' = false,
          '''["underwater"]''' = false,
          '''["antigator"]''' = false,
          '''["notship"]''' = false,
          '''["all"]''' = false,
          '''["notsub"]''' = false,
          '''["weapon"]''' = false,
        }
        '''["weaponDef"]''' = 13,
        '''["slavedTo"]''' = 0,
        '''["badTargets"]''' = {
        }
        '''["fuelUsage"]''' = 0,
        '''["maxAngleDif"]''' = -1,
      }
    }
  '''UnitDefs['''216''']["windGenerator"]''' = 0,
  '''UnitDefs['''216''']["wingAngle"]''' = 0.079999998211861,
  '''UnitDefs['''216''']["wingDrag"]''' = 0.070000000298023,
  '''UnitDefs['''216''']["wreckName"]''' = "CORCOM_DEAD",
  '''UnitDefs['''216''']["verticalSpeed"]''' = 4,
  '''UnitDefs['''216''']["xsize"]''' = 4,
  '''UnitDefs['''216''']["ysize"]''' = 4,

Latest revision as of 17:38, 29 December 2023

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: [1]

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

  1. ↑ Spring 95, commit message,4e58b8b0
Retrieved from "https://springrts-wiki.p2004a.com/mediawiki/index.php?title=Lua_UnitDefs&oldid=12152"