Art
Sprite sheets for bodies, turrets, buildings and decals: how to draw them, how team colour works, and which frames play when.
A def draws with the atlas key in sprite (its body) and turretSprite (a rotating part). Three ways to fill them:
- Nothing. A def with no sheet is drawn as a plain placeholder in the faction's colour, sized to the def, so a mod plays before its art exists.
- Borrowed.
"sprite": "u.mbt", "turretSprite": "tur.mbt"draws with the Bison's art;extendsinherits the base's. - Your own. A
spritesentry per sheet: a PNG (WebP and JPEG work too),framesanimation frames left to right in one strip, evenly spaced, no gaps. The key isu.<id>for a body andtur.<id>for a turret, and a mod may not take a vanilla key.
Units and turrets
Hulls, turrets and everything that turns are one image facing up with "rotated": true; the game bakes the 24 headings. fw/fh are the in-game size of that image in world px (a tank hull is about 24×24; draw it at 2–4× that and the loader resamples). pivotX/pivotY put the pivot on the turret ring.
Buildings
Buildings are a strip of frames, not rotated, drawn top-down with a slight southern tilt: the footprint is the bottom fw×32 by fh×32 px of the frame and anything above overhangs the terrain behind. Width, height and anchor are sized from the def's footprint for you.
Team colour
Team colour is magenta: paint faction-coloured parts in #FF66FF, #FF00FF and #990099 and nothing else in magenta; the game recolours them per player. Generated sheets are cleaned on load (backgrounds removed, frames registered, static pixels frozen), so a transparent background is best but not required.
Buildings with guns that turn
A turreted building is two sheets, like a tank: the body with an empty mounting ring and "mount": [fx, fy] on its sprites entry saying where the ring sits as fractions of the frame, and a tur.<id> sheet for the gun, one image facing up. Its weapons carry "turret": true and the gun tracks targets in-engine. The Ironworks bunker in the registry is one.
Several turrets
A hull with more than one gun, a battleship's turrets fore and aft or a tank with a turret at each corner, names a ring for each in turretMounts. The def's one turretSprite is drawn on every ring, and every ring is trained on the one target the unit is aiming at, as far round as its own arc of its rest bearing goes, so a gun the superstructure blocks waits at its stop while the others fire. A burst walks the rings that bear, one shot from each in turn, and muzzleOffset is measured from the ring a shot leaves, so a weapon of several guns wants a burst of that many. x/y are a point on the body's up-facing art, as a decal's are. Guns painted on the body never turn.
Decals
A decal is a picture a def lists in its decals, laid on it besides its body and its turret — a hatch, a crew figure, an outline, a lamp — fixed to the hull or the turret (on) and turned with it. Static detail belongs in the body's own sheet; a decal is for what the body cannot hold: a part that turns with the turret, a hatch the barrel sweeps over, a light that comes on at night, a barrel that spins while it fires.
Its sheet is like a turret's, keyed dec.<name>: one up-facing image (or a strip of frames at fps for something that moves), sized by fw/fh and drawn about its centre; or a body or turret key it borrows. x/y are a point on that part's up-facing art: right and down (toward the tail) of its pivot, in the px of the sheet at its fw×fh size; the game scales them with the unit.
A night decal is a lamp: laid over the dark rather than dimmed by it, so a headlight or a lit window reads as light, and a unit that carries one gets none of the game's own headlights. Paint a beam soft, a wide faint falloff rather than a hard-edged triangle, or it reads as glass.
Animation
A body sheet's anims say which frames play while it moves, stands or has just fired. A unit that changes form can use them to look like something else entirely while it stands still.
Reference
A sheet (sprites[])
| field | type | required | default | meaning |
|---|---|---|---|---|
| key | string | yes | `u.<id>` for a body, `tur.<id>` for a rotating part, `dec.<name>` for a decal, `prj.<name>` for a round and `fx.<name>` for an effect a weapon's look or a rule plays; `ter.<mod id>-<name>` for terrain materials; never a vanilla key | |
| file | string | yes | the image, relative to mod.json (PNG, WebP or JPEG) | |
| frames | integer 1–64 | 1 | animation frames, left to right in one strip | |
| fw | number 4–512 | the footprint (a building) or the image | in-game frame width, whole world px | |
| fh | number 4–512 | in-game frame height, whole world px | ||
| rotated | boolean | one up-facing image; the game bakes the 24 headings (hulls, turrets) | ||
| pivotX | number 0–1 | 0.5 | rotation pivot, as a fraction of the frame | |
| pivotY | number 0–1 | 0.5 | rotation pivot, as a fraction of the frame | |
| anchorY | number 0–512 | px from the top to the footprint centre (tall buildings) | ||
| mount | [x, y] | a body: where its turret sits (or, with a repair aura, where the beam leaves), as `[fx, fy]` | ||
| barrels | [left, top, right, bottom][] | exposed barrel rectangles, each `[left, top, right, bottom]` in 0–1 fractions of the up-facing source frame, in muzzle firing order; leave mantlets fixed. Pair with weapon `recoil` (art px) | ||
| fps | number 0–60 | animation speed | ||
| teams | boolean | true | recolour magenta per faction; `false` draws the sheet as painted for every faction, and for the wreck | |
| ss | integer 1–4 | supersample factor; omit to let the game choose | ||
| fitFootprint | boolean | scale the drawn content to fill the frame | ||
| animRegion | [x0, y0, x1, y1] | where the animation lives, `[x0, y0, x1, y1]` fractions; the rest is frozen | ||
| stabilize | boolean | true | re-align drifting frames | |
| freezeStatic | boolean | median-freeze pixels that barely change | ||
| stripBg | boolean | force background removal on or off | ||
| bgMinLuma | number 0–255 | lightest colour still taken as background | ||
| artifactCleanup | boolean | sweep specks left by background removal | ||
| anims | { moving, idle, firing } | a unit body's frames by what it is doing, `{ moving, idle, firing }`, each `[first, last]` or `[first, last, fps]`: a tank that is a tree when it stands, a walker whose legs move only when it does (see Animation states) |
Animation states (sprites[].anims)
| field | type | required | default | meaning |
|---|---|---|---|---|
| moving | [first, last] or [first, last, fps] | `[first, last]` frames played while it moves, or `[first, last, fps]` | ||
| idle | [first, last] or [first, last, fps] | frame 0 | the frames while it stands | |
| firing | [first, last] or [first, last, fps] | the frames within a reload of its last shot; before moving and idle |
A decal (defs[].decals[])
| field | type | required | default | meaning |
|---|---|---|---|---|
| sprite | string | yes | the sheet drawn: one of this mod's `dec.<name>` sheets, or any body or turret key | |
| on | hull | turret | hull | what it is fixed to and turns with; `turret` needs a `turretSprite` | |
| layer | under | hull | over | hull, or over when on a turret | where it goes in the stack: under the body, on the hull under the turret, or over everything | |
| x | number -256–256 | 0 | where it sits on the part's up-facing art: px right of the pivot, in the sheet's own px at its `fw`×`fh` size (the game scales it with the unit) | |
| y | number -256–256 | 0 | px down from the pivot, toward the tail | |
| angle | number -360–360 | 0 | turned this much further than what it is fixed to, degrees clockwise | |
| upright | boolean | never turned: laid screen-up wherever its anchor is | ||
| scale | number 0.05–8 | 1 | drawn at this multiple of its sheet's size | |
| alpha | number 0–1 | 1 | opacity | |
| when | always | moving | still | firing | damaged | night | ability | always | shown only while the unit moves or stands (`moving`, `still`), within a reload of its last shot (`firing`), under half health (`damaged`), while its ability runs or is armed (`ability`), or after dusk (`night`: laid over the dark like a lamp, and the game's own headlights stay off a unit that has one) |
A turret mount (defs[].turretMounts[])
| field | type | required | default | meaning |
|---|---|---|---|---|
| x | number -256–256 | 0 | where the ring is on the body's up-facing art: px right of its pivot, in the body sheet's own px at its `fw`×`fh` size (the game scales it with the unit) | |
| y | number -256–256 | 0 | px down from the pivot, toward the tail | |
| rest | number -360–360 | 0 | the bearing it trains about, degrees clockwise from the bow: 0 forward, 90 to the right, 180 aft | |
| arc | number 0–180 | 180 | how far either side of `rest` it turns, degrees; 180 is all round. A ring that cannot bear on the target waits at the end of its arc, and the rings that can take the shots |
Last edited