Units and buildings | Steel Tide Modding Guide

A def is a unit, a building or an upgrade level, and every field it can carry is a field of the game's own unit definition. Here is a mod with its own art, a defended building, and a fourth level for the power plant line:

{
  "format": "steel-tide-mod",
  "v": 4,
  "id": "ironworks",
  "name": [
    "Ironworks",
    "铁工厂"
  ],
  "version": "1.0.0",
  "author": "you",
  "description": [
    "A hover tank, a bunker and a fusion plant.",
    "一辆悬浮坦克、一座碉堡和一座聚变电站。"
  ],
  "license": "CC-BY-4.0",
  "defs": [
    {
      "id": "ironworks-hover",
      "name": [
        "Skimmer Hover Tank",
        "掠行悬浮坦克"
      ],
      "desc": [
        "Fast, thin-skinned, rockets.",
        "快、皮薄、打火箭。"
      ],
      "kind": "unit",
      "domain": "ground",
      "tier": 2,
      "cost": 260,
      "hp": 320,
      "armor": "light",
      "speed": 110,
      "turnRate": 5,
      "radius": 9,
      "body": {
        "r": 10,
        "len": 10
      },
      "trail": "tire",
      "weapons": [
        {
          "id": "pods",
          "cls": "rocket",
          "dmg": 16,
          "reload": 2.2,
          "range": 4.5,
          "burst": 4,
          "burstDelay": 0.1,
          "splash": 10,
          "spread": 14
        }
      ],
      "producedBy": [
        "factory2",
        "factory3"
      ],
      "aiWeight": 1
    },
    {
      "id": "ironworks-bunker",
      "name": [
        "Bunker",
        "碉堡"
      ],
      "desc": [
        "A gun pit that takes a beating.",
        "扛打的火力点。"
      ],
      "kind": "building",
      "cost": 380,
      "hp": 1600,
      "fw": 2,
      "fh": 2,
      "power": -3,
      "vision": 8,
      "weapons": [
        {
          "id": "gun",
          "cls": "autocannon",
          "dmg": 22,
          "reload": 0.5,
          "range": 5,
          "turret": false,
          "targets": [
            "ground",
            "ship"
          ]
        }
      ]
    },
    {
      "id": "ironworks-fusion",
      "name": [
        "Fusion Plant",
        "聚变电站"
      ],
      "desc": [
        "The plant line's fourth level.",
        "发电厂线的第四级。"
      ],
      "extends": "power3",
      "upgradeOf": "power3",
      "cost": 2200,
      "hp": 2600,
      "power": 500,
      "upgradeCost": 1100,
      "upgradeTime": 60,
      "requires": [
        "radar",
        "reactor"
      ]
    }
  ],
  "sprites": [
    {
      "key": "u.ironworks-hover",
      "file": "sprites/u.ironworks-hover.png",
      "frames": 1,
      "rotated": true,
      "fw": 24,
      "fh": 26
    },
    {
      "key": "u.ironworks-bunker",
      "file": "sprites/u.ironworks-bunker.png",
      "frames": 1
    }
  ],
  "screenshots": [
    "screenshots/skimmers.png"
  ]
}

Units of measure

A tile is 32 world pixels. speed and projectile speed are world px/s; range, minRange, vision, sonar, stealth, detect, repairRange and interceptRange are tiles; radius, splash, spread and muzzleOffset are world px; every time is seconds. For scale, the Bison Battle Tank is cost 280, hp 620, speed 60, radius 10, with a cannon of dmg 60 every 1.8 s at range 4.6; the Recon Buggy is cost 60, hp 150, speed 120; a War Factory is 3×3 tiles, hp 1500, power −8.

Where things are built

A unit joins the production list of the buildings in producedBy. Left out, it joins its domain's line from its tier up: a tier-2 ground unit appears at the level-2 and level-3 war factory, a tier-1 ship at every naval yard. With extends, it is built wherever the base is.
A building is placed by the units in builtBy, the engineer unless you say otherwise. A building with a produces list is a factory; a unit that names a plain building in producedBy turns it into one.
A unit with a produces list trains those units itself: a carrier, a mothership. Each one is launched beside it, wherever it has got to, and left standing there. Another unit of the mod may name it in producedBy; a unit of the game's own may not be made one.
An upgrade level is a building with upgradeOf: the named building gains an Upgrade button that turns it into this def, at upgradeCost over upgradeTime, and this def is never placed directly. A building has one next level, so upgradeOf may name a vanilla building at the end of its line (power3, factory3, extractor3, gatling, cannonturret2, samsite, interceptor2, radar, repairtower, reactor, nukesilo) or another def of your mod.
requires lists buildings that must stand before something can be built, the way Tier 3 needs the Radar Station.

The AI

AI opponents build a modded unit at its aiWeight, on the scale the vanilla roster is weighed on (a Bison is 3, a scout car 1), once its requires are met. Leave it out and they never build it. Buildings and upgrade levels are yours alone.

Reference

A def (`defs[]`)

field	type	required	default	meaning
extensions	{ capability: configuration }			Configuration keyed by a required engine capability (format 3)
isHQ	boolean	buildings only		a headquarters: holds territory and production slots, follows the ordinary HQ loss and sale rules; format 2
id	id	yes		unique across every mod and the vanilla roster; prefix a generic word with your mod's id
name	text	yes		as the HUD shows it
desc	text		""	the tooltip line
extends	id			a vanilla def id (or an earlier def of this mod) to copy, then override field by field; inherits its art and where it is built
kind	unit \| building	yes		a unit or a building (required unless `extends` says)
domain	ground \| ship \| air \| amphibious	units only	ground	where it moves; a submarine is a `ship` with `underwater`, and an `amphibious` hull drives and swims (a ship target afloat, a ground one ashore)
tier	integer 1–3		1	the factory level it appears at, and the badge
cost	number 0–99999	yes		metal
buildTime	number 0–3600		cost ÷ 14	seconds at full power
pop	integer 0–50		1 for a unit, 0 for a building	population it counts for
hp	number 1–100000000	yes		hit points; standard capacity is limited to 1000000, large to 100000000
armor	light \| medium \| heavy \| ship \| sub \| air \| structure		by domain	the armour class weapons are multiplied against
impactMaterial	armor \| earth \| concrete		concrete for structure armor, armor otherwise	projectile-impact sound material; does not change damage. Both ordinary and heavy impacts use the matching recorded family
directionalArmor	{ front, side, rear }	units only		ground hull direct-hit multipliers `{front, side, rear}`, each 0–10; 90° front/rear arcs and 90° on each side. Arc fire, collateral blasts, mines and fire ignore facing. Enables slow reversing for short moves behind the hull
speed	number 0–1000	units only	60	world px/s (a tile is 32)
turnRate	number 0–50	units only	3.5	rad/s
vision	number 0–64		8	sight, in tiles; rounded to the nearest whole tile when activated
radius	number 1–200		9, or the footprint	collision radius, world px, and the combat yardstick: range, splash and hits are measured to it
body	{ r, len }	units only	the circle of `radius`	the room the hull takes up when units push each other apart, world px: `r` its half-width, `len` its length less the two round ends. A long hull is what a circle cannot say. A ship whose beam (`r` twice) is over a tile (32) needs that many tiles of water abeam, rounded up: it never enters a channel narrower than itself
weapons	weapon[]		[]	the weapons (see below); an empty list is unarmed
fw	integer 1–8	buildings only	2	footprint width, tiles
fh	integer 1–8	buildings only	2	footprint height, tiles
producedBy	id[]	units only	the line for its domain, from its tier up	the buildings whose production list it joins (vanilla or this mod's), or units of this mod that train it (a carrier)
produces	id[]			a factory: the units it builds. On a unit, a carrier or a mothership that trains them itself: each is launched beside it, wherever it has got to
builtBy	id[]	buildings only	["engineer"]	the builder units that may place it
builds	id[]	units only		a builder unit: the buildings it can construct
buildRate	number 0–10000	units only		a builder unit: hp of work per second
reach	number 0–256	units only		a builder unit: how far past a target's radius it works from, world px (the engineer's 46 when unset; the engineer boat's 64)
power	number -10000–10000		−pop for a unit, 0 for a building	positive produces, negative draws; every unit draws its population
metalRate	number 0–1000			metal per second: an extractor, or a unit that earns (a supply ship)
needsDeposit	boolean	buildings only		must stand on a deposit
offshore	boolean	buildings only		stands in open water on its own legs: every footprint tile sea, no shore needed; with needsDeposit, an ore field at sea, which only a builder on the water (the engineer boat) can reach
wall	boolean	buildings only		a wall: one tile that joins its neighbours of the same def (its sheet is sixteen frames, one per set of neighbours: north 1, east 2, south 4, west 8), the last thing a gun shoots at, untouched by a pulse, and it falls without a charge
repairRange	number 0–64			a repair aura, tiles; a unit repairs ground and naval units, a building also repairs aircraft and buildings
repairAirRange	number 0–64		repairRange	repair reach for aircraft, tiles; does not change which targets the source can repair
repairNavalRange	number 0–64		repairRange	repair reach for ships, submarines and swimming amphibians, tiles
repairRate	number 0–10000			hp per second per target
repairTargets	integer 1–50			targets served at once
upgradeOf	id	buildings only		the building this is the next level of; that one gains the upgrade button
upgradeCost	number 0–99999	buildings only	cost − the source's cost	with `upgradeOf`: the upgrade's price
upgradeTime	number 0–3600	buildings only	buildTime	with `upgradeOf`: seconds
requires	id[]			building ids that must stand before it can be built, or tech node ids that must be researched (`suicideDrones`, `activeProtection`…)
nukeCapacity	integer 0–10			a launcher: warheads it holds
nukeCost	number 0–99999			a launcher: metal per warhead
nukeTime	number 0–3600			a launcher: seconds per warhead
armsAtBase	number 0–64	units only		a launcher: fabricates its warheads only within this many tiles of one of its own bases of its kind (a naval yard for a hull, an airbase for an aircraft; and, an `underwater` one, only on the surface), and holds the work otherwise (the Kraken's and the Wraith's 4)
rearmTime	number 0.1–600		15	seconds to fill every gun that carries `ammo` from empty, at a base of its kind
hatch	number 0–30			a launcher: seconds its doors take to open before the warhead leaves, and to close after; none fires on the spot
antiWarhead	boolean			its anti-air may fire on a nuclear warhead without a veteran's rank
interceptRange	number 0–64			point defence: reach in tiles
interceptMag	integer 1–200			point defence: rounds ready
interceptReload	number 0.05–600			point defence: seconds per round replaced
interceptMuzzleOffset	number 0–200			point defence: launcher length, world px
transportCap	integer 1–50	units only		a transport: hold, in cargo weight
transportMaxWeight	number 0–50	units only	transportCap	a transport: maximum cargo weight of one passenger
cargoReach	number 0.5–4	units only	1	a transport: how far its load and unload distances stretch, as a multiple of the default (the landing craft's 1.1, the Moray's 1.5); on a ship it widens the ground its ramp reaches too
landsForCargo	boolean	units only		a cargo plane that touches down to load
cargoWeight	number 0–50	units only	pop	how much of a hold it takes
underwater	boolean	units only		a submarine: seen only by sonar
sonar	number 0–64	units only		sonar range, tiles
stealth	number 0–64	units only		seen only within this many tiles of an enemy
detect	number 0–64			reveals stealth within this many tiles
radar	boolean			sees by radio: the sight circle ignores weather and the hour, and drops to 7 tiles when short of power
remoteVision	boolean	units only		remote camera feed: hostile jamming blocks its sight within the field
jamRange	number 0–64	buildings only		electronic-warfare radius in tiles; requires full power, reveals its location, blocks hostile radar and remote vision, never visual sight or sonar
hovers	boolean	units only		an aircraft that hovers instead of orbiting
kamikaze	boolean	units only		the unit is its own round: it never picks a target, and its one weapon flies it into what it is ordered at (the Hornet)
lowFlying	boolean	units only		an aircraft at treetop height: machine guns and autocannons that fire on the ground reach it too (the helicopters and the Hornet)
limit	integer 1–200	units only		at most this many a faction at once, alive and queued together (the Hornet's 10)
altitude	number 0–64	units only	12	an aircraft's drawn height, px
fireOnMove	boolean	units only		keeps shooting on a plain move
burnMult	number 0–4	units only	1	what fire on the ground does to it, as a multiplier (the Drake's 0.5)
trail	tread \| tire \| wake \| none	units only	by domain	the mark it leaves, and the sound of it: treads and tyres are heard rolling; `none` for a unit on foot or a hovercraft, which neither cuts a rut nor is heard as an engine
shadow	boolean		true	the shadow the game casts for it: a unit's hull and turret silhouettes, a step to the south-east on the ground, further off in the air; a building's gun's, on its roof; `false` when the art brings its own, or none is wanted (a submarine casts none)
sprite	string		this mod's u.<id> sheet, else the base's art	the body's atlas key: one of this mod's sheets, or a vanilla key to borrow its art
turretSprite	string		this mod's tur.<id> sheet, else the base's (when its art is kept)	the rotating part's key, if any
turretMounts	mount[]		one, where the body sheet's `mount` puts it (else the pivot); the base's, when its art is kept	the rings its turret stands on and fires from, up to 8: a hull with several guns names one each (a battleship's A, B and X), every one drawn with the one `turretSprite` and trained on the one target, as far round as its own arc goes (see below)
decals	decal[]		the base's, when its art is kept	pictures laid on the hull and the turret besides their own sheets (see below), up to 12
ability	sprint \| afterburner \| smoke \| incendiary \| barrage \| countermeasures \| damageControl \| emergencyRepair	units only	the base's	its one active ability, a vanilla one by id (`sprint`, `smoke`, `countermeasures`…): the same click, clock and unlock as on the game's own units
aliases	string[]			other names the console's `give` accepts
aiWeight	number 0–10	units only	0	how readily the AI builds it: a Bison is 3, a scout car 1; 0 never
rules	rule[]			its behaviour: rules that turn it into another form, spawn, heal, pay, buff or blow up, on an event, a condition, a clock or a button (see Behaviour), up to 24; never inherited through `extends`
shield	{ hp, regen, delay }			an energy shield, `{ hp, regen, delay }`: it takes harm before the hull does, and recharges `regen` a second once unhurt for `delay` seconds
regen	number 0–10000			hit points a second it mends itself by
untargetable	boolean			nothing on the other side may pick it as a target or be ordered to attack it; a blast still reaches it (a disguise, a decoy)
wing	{ unit, count, rebuild, sortie, rearm, range }	units only		a carrier: planes of this mod it keeps aboard, `{ unit, count, rebuild, sortie, rearm, range }`, sent out at what it fights, taken back to rearm and made again when lost; never the player's to order (see Behaviour); never inherited through `extends`

Defaults with no extends: a unit is domain: "ground", tier: 1, pop: 1, speed: 60, turnRate: 3.5, vision: 8, radius: 9, armour by domain (ground medium, ship ship, air air), a tread trail on land (trail: "none" for a unit on foot, which is then not heard rolling either) and a wake at sea; a building is fw: 2, fh: 2, armor: "structure", power: 0, pop: 0. buildTime is cost ÷ 14 seconds.

Units of measure

Where things are built

The AI

Reference

A def (defs[])

A def (`defs[]`)