Lua UnitDefs: Difference between revisions

From Spring
Jump to navigationJump to search
← Older edit
Aegis (talk | contribs)
0 edits
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
 
(30 intermediate revisions by 8 users not shown)
Line 1: Line 1:
[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}
[[Engine_Development|Development]] < [[Lua_Scripting|Lua Scripting]] < {{FULLPAGENAME}}


<font style="font-size:125%" color="#55ee99">The UnitDefs[] table holds all information about the units used in the mod.
'''Were you looking for the unitDefs page for Game Developers?''' ([[Gamedev:UnitDefs]])
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">
==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 9: 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
 
<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.


<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>
===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,        //(unit info value) * 16 / 30
  '''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''']["zsize"]''' = 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"