Building animations

Features & systems·Units, buildings & economy·Buildings & economy

A structure moves on screen through two mechanisms that share almost nothing. Its own artwork carries frames, and a small state machine steps through them. Separately, a structure runs up to thirteen attached animations — independent animation objects, each named in [Animations], pinned to a point on the structure’s artwork, cycling on their own timing, and created and destroyed as the structure changes state. The second is most of this page.

Each attached animation lives in a slot. A BuildingType declares one set of settings per slot, a structure holds at most one animation in each at a time, and each slot is filled and emptied by its own events. A slot no event ever reaches still stores every setting written for it and creates nothing from them.

The thirteen slots

The table lists every slot with the assignment that names its animation and the moment something puts one there. Take the last column as a pointer: the mechanism below governs how any slot’s animation is built, while the timing belongs to the setting that names it.

Slot	Named by	Filled when
Upgrade one, two, three	PowerUp1Anim=, PowerUp2Anim=, PowerUp3Anim=, each with a PowerUp<n>DamagedAnim=, PowerUp<n>LocXX=, PowerUp<n>LocYY=, PowerUp<n>LocZZ= and PowerUp<n>YSort= beside it	The first, second and third Upgrades= plug is installed. Removing a plug empties its slot
Active one to four	ActiveAnim=, ActiveAnimTwo=, ActiveAnimThree=, ActiveAnimFour=	The structure comes online, either as construction finishes or as the scenario places it
Pre-production	PreProductionAnim=	Work is being set up on the structure
Production	ProductionAnim=	The structure’s work is in progress
Turret	TurretAnim=	The structure comes online, or its charge-up begins
Special one to three	SpecialAnim=, SpecialAnimTwo=, SpecialAnimThree=	An event on a UnitRepair=yes, SiloDamage=yes or FirestormWall=yes structure

Two of the active slots carry behavior the other two do not. On a SensorArray=yes structure, slot one starts two seconds — 30 frames — after construction finishes; every other path that starts slot one, and every path that starts the other three, applies no delay. Slot one is also the slot a UnitRepair=yes bay stops while it services a vehicle, and slot two the one a TurretAnimIsExclusive=yes turret displaces while it charges.

The turret slot is the one slot whose animation does not run on its own timing: its frame is set every pass from the structure’s facing, or from a charge counter stepped at TurretChargeAnimRate on a ChargeAnim=yes structure. TeslaCharge sounds as that wind-up begins; TeslaZap sounds nowhere.

Building and emptying a slot

Whatever the occasion, one routine fills a slot. It takes the slot’s healthy or damaged name and stops there if that name is empty; otherwise it looks the name up in [Animations] and creates an animation at the structure’s drawing position, offset by the slot’s …X and …Y and carrying its two draw-order biases. A name no [Animations] entry registers gets as far as the lookup and no further: nothing is created and the slot stays as it was, though the damage-state flag below has already moved by then. Filling a slot that already holds an animation replaces it and hands the new one the stage the old had reached, so the swap does not show as a jump.

One path bypasses the slot’s names. The lettered turret variants a wall tower cycles through are built from the structure’s Image ID with _B, _C or _D appended, and take the turret slot’s offset and biases but not its name.

A slot empties in three ways: its animation plays to its end, something stops it deliberately, or the structure is taken off the map, which stops all thirteen at once. The first is why a looping animation holds its slot for the rest of the structure’s life while a finite one leaves it free.

A running animation belongs to the structure rather than to the cell. Placing the structure down re-applies every slot’s offset from the new position, and the structure’s redraw pass brings its animations to the brightness and translucency it is drawn at, so one fading into a cloaking field takes them with it. Fog reaches them the same way: a structure passing under fog marks each of its animations fogged, an animation created on an already fogged structure is marked as it is created, and one whose AnimType leaves ShouldFogRemove at its default is not drawn while that mark is set. Uncovering the structure clears it.

The damaged form

Each slot carries a second name for its damaged form, and which of the two is used is fixed as the animation is created, from whether the structure has fallen to ConditionYellow or below. A slot that names no damaged form is given its healthy name as the art file is read, so one name serves both states; a slot that names only a damaged form runs nothing while the structure is healthy.

A structure keeps one flag recording which form it is currently showing, and that flag is per structure rather than per slot. Creating any animation in a form different from the flag flips it and restarts every animation the structure is running in the new form. Crossing ConditionYellow in either direction does the same directly, so a structure that takes a hit past the threshold swaps its whole set at once.

The consequence worth planning around runs the other way. Any slot started in the healthy form drags the rest of them back to healthy whether or not the structure is damaged, and they stay there until the next damage step or repair step re-tests the threshold. A repair bay’s animations and three of the four production moments each do this.

Placement and draw order

…X and …Y offset the animation from the point the structure is drawn at, in screen pixels: …X to the right, …Y down the screen. The offset pins the animation to a point on the artwork rather than to a cell.

…ZAdjust and …YSort both decide what the animation ends up drawn over, through two different mechanisms.

• …ZAdjust biases the depth value the animation’s pixels are tested against. A negative figure brings the animation toward the viewer, so it covers the structure and anything else at that depth; a positive figure pushes it away, so the structure covers it.
• …YSort is added to the animation’s sorting position, in leptons, of which a cell is 256. That position orders the ground layer, which is sorted once a frame. An AnimType left at the default Surface=no goes into the air layer instead, which is never sorted, so the bias reaches nothing there.

The slot overrides the animation’s own sort bias

An AnimType may carry its own YSortAdjust=, but a slot writes its figure over that as the animation is created, including the zero it holds when …YSort is omitted. An animation used both on its own and in a building slot keeps its bias in the first case and loses it in the second unless the slot repeats the value.

Both biases are held in a single byte

…ZAdjust and …YSort are each stored in one signed byte. A figure from -128 through 127 is kept as written; anything outside that range wraps into it, so …ZAdjust=200 is stored as -56 and pulls the animation in front of the structure it was meant to hide behind. The same ceiling caps …YSort at rather less than half a cell in either direction.

Power

The two power flags are two responses to the same shortfall. …Powered=yes freezes the animation on its current frame while the house cannot meet its drain and resumes it at full power; the animation stays on screen throughout. …PoweredLight=yes instead destroys the animation on the shortfall and creates it again at full power.

Only one of the two is consulted. The pass over a house’s structures tests …Powered first and reaches …PoweredLight only when that flag is no, so …PoweredLight=yes left beside the default …Powered=yes never does anything. That pass reaches all thirteen slots on every structure the house owns, which is the one route by which a structure carrying none of the three special-slot flags runs a special animation. Fields, fences and lights covers which structures a house-wide shortfall reaches and which it spares.

The power cursor, the Turn off building trigger action and an EMP pulse reach the freeze by a different route, stopping one structure’s …Powered=yes animations directly rather than through the house-wide pass. A …PoweredLight=yes animation keeps running through all three.

Where each setting is read from

Only the first 15 characters of an animation name are kept, and where a slot’s settings are read from is not uniform. The table gives the entry each half of a slot is taken from; the split shows only on a structure that borrows another’s artwork, where the two entries are different sections.

Slot	Names	Offset, biases and power flags
Active one to four	The Image ID art entry	The Image ID art entry
Special, production and pre-production	The Image ID art entry	The art entry named after the ObjectType ID
Turret	The rules entry named after the ObjectType ID	The rules entry named after the ObjectType ID

Everything but the turret slot reads its remaining settings only once the slot holds a name, healthy or damaged; on a structure that names neither, those settings are not read at all. The turret slot reads its four unconditionally.

The upgrade slots and the active slots share one array

The thirteen slots are one array with the three upgrade slots at its head, and two paths walk into it by number rather than by name.

The art file is read one declared upgrade at a time — PowerUp1Anim= and its companions into the first slot, PowerUp2Anim= and its companions into the second — and the walk is bounded by Upgrades= rather than by the number of upgrade slots. A type declaring four upgrades therefore has its fourth plug’s six art assignments read over the first active slot’s two names, its offset and both of its biases, each field only where that plug’s assignment is present. A fifth, sixth and seventh declared upgrade reach active slots two, three and four in turn.

Installing a plug rewrites the host type’s animation name

Placing a plug copies the plug type’s own Image ID into the host type’s slot for the upgrade level being installed, not into the structure that received it. Every structure of the host type shows that name in that slot from then on, including ones already standing and ones that never received a plug. The first three plugs write into upgrade slots, where that is the intended behavior; a fourth plug writes into the first active slot instead, and the host’s ActiveAnim= is lost for the rest of the session.

The copy is made without a length check. A plug whose Image ID runs to sixteen characters or more is written into the sixteen-byte slot with no terminator, so the stored name runs on into the damaged name stored immediately after it.

The structure’s own frames

The structure’s own artwork has no slots in it. A structure is in one of five frame sequences at a time, four of them declared as a first frame, a frame count and a per-frame delay: AnimIdle whenever nothing else has taken it over, AnimActive while it is working, and AnimAux1 and AnimAux2 for the two further states a missile silo uses. The fifth is the construction sequence, which is not declared at all: its frame count is half the frame count of the Buildup= file — or GateStages plus one on a gate — and its rate is that count divided into BuildupTime. A Theater=yes structure is timed again as each theater is set up, over every frame in the file at a fixed five seconds, so neither the halving nor BuildupTime reaches it.

Damaged artwork is a second block of frames after the first, and where that block begins depends on which sequence the structure is in. A damaged structure in the idle sequence draws the very next frame after the one it would otherwise draw; in any of the other three it is offset by the largest end any of the four sequences reaches. ExtraDamageStage promises a third condition and reaches nothing.

Four further shapes are drawn around the structure rather than as part of it, and none is an attached animation: BibShape under it, DeployingAnim in place of it while it unloads, and DoorAnim with UnderDoorAnim around its factory door. Each is a shape file loaded with the rules and drawn from a frame the structure works out, so none cycles on its own. Despite the name, Bib=yes has nothing to do with the apron artwork: it opens the eastern edge of the footprint to vehicles and draws nothing.

Related settings

Filter keys

99 of 99

Key	Description	Value	When omitted
ActiveAnimBuildingType	The animation the structure runs in its first active slot.	string	(empty)
ActiveAnimDamagedBuildingType	The animation the first active slot runs while the structure is damaged.	string	Inherited
ActiveAnimXBuildingType	How far right of the structure's drawing point the first active slot's animation sits, in screen pixels.	integer	0
ActiveAnimYBuildingType	How far below the structure's drawing point the first active slot's animation sits, in screen pixels.	integer	0
ActiveAnimZAdjustBuildingType	The depth bias applied to the first active slot's animation.	integer	0
ActiveAnimYSortBuildingType	The sorting bias applied to the first active slot's animation, in leptons.	integer	0
ActiveAnimPoweredBuildingType	Whether the first active slot's animation freezes while its house is short of power.	boolean	yes
ActiveAnimPoweredLightBuildingType	Whether the first active slot's animation is destroyed and recreated with its house's power.	boolean	no
ActiveAnimTwoBuildingType	The animation the structure runs in its second active slot.	string	(empty)
ActiveAnimTwoDamagedBuildingType	The animation the second active slot runs while the structure is damaged.	string	Inherited
ActiveAnimTwoXBuildingType	How far right of the structure's drawing point the second active slot's animation sits, in screen pixels.	integer	0
ActiveAnimTwoYBuildingType	How far below the structure's drawing point the second active slot's animation sits, in screen pixels.	integer	0
ActiveAnimTwoZAdjustBuildingType	The depth bias applied to the second active slot's animation.	integer	0
ActiveAnimTwoYSortBuildingType	The sorting bias applied to the second active slot's animation, in leptons.	integer	0
ActiveAnimTwoPoweredBuildingType	Whether the second active slot's animation freezes while its house is short of power.	boolean	yes
ActiveAnimTwoPoweredLightBuildingType	Whether the second active slot's animation is destroyed and recreated with its house's power.	boolean	no
ActiveAnimThreeBuildingType	The animation the structure runs in its third active slot.	string	(empty)
ActiveAnimThreeDamagedBuildingType	The animation the third active slot runs while the structure is damaged.	string	Inherited
ActiveAnimThreeXBuildingType	How far right of the structure's drawing point the third active slot's animation sits, in screen pixels.	integer	0
ActiveAnimThreeYBuildingType	How far below the structure's drawing point the third active slot's animation sits, in screen pixels.	integer	0
ActiveAnimThreeZAdjustBuildingType	The depth bias applied to the third active slot's animation.	integer	0
ActiveAnimThreeYSortBuildingType	The sorting bias applied to the third active slot's animation, in leptons.	integer	0
ActiveAnimThreePoweredBuildingType	Whether the third active slot's animation freezes while its house is short of power.	boolean	yes
ActiveAnimThreePoweredLightBuildingType	Whether the third active slot's animation is destroyed and recreated with its house's power.	boolean	no
ActiveAnimFourBuildingType	The animation the structure runs in its fourth active slot.	string	(empty)
ActiveAnimFourDamagedBuildingType	The animation the fourth active slot runs while the structure is damaged.	string	Inherited
ActiveAnimFourXBuildingType	How far right of the structure's drawing point the fourth active slot's animation sits, in screen pixels.	integer	0
ActiveAnimFourYBuildingType	How far below the structure's drawing point the fourth active slot's animation sits, in screen pixels.	integer	0
ActiveAnimFourZAdjustBuildingType	The depth bias applied to the fourth active slot's animation.	integer	0
ActiveAnimFourYSortBuildingType	The sorting bias applied to the fourth active slot's animation, in leptons.	integer	0
ActiveAnimFourPoweredBuildingType	Whether the fourth active slot's animation freezes while its house is short of power.	boolean	yes
ActiveAnimFourPoweredLightBuildingType	Whether the fourth active slot's animation is destroyed and recreated with its house's power.	boolean	no
SpecialAnimBuildingType	The animation the structure runs in its first special slot.	string	(empty)
SpecialAnimDamagedBuildingType	The animation the first special slot runs while the structure is damaged.	string	Inherited
SpecialAnimXBuildingType	How far right of the structure's drawing point the first special slot's animation sits, in screen pixels.	integer	0
SpecialAnimYBuildingType	How far below the structure's drawing point the first special slot's animation sits, in screen pixels.	integer	0
SpecialAnimZAdjustBuildingType	The depth bias applied to the first special slot's animation.	integer	0
SpecialAnimYSortBuildingType	The sorting bias applied to the first special slot's animation, in leptons.	integer	0
SpecialAnimPoweredBuildingType	Whether the first special slot's animation freezes while its house is short of power.	boolean	yes
SpecialAnimPoweredLightBuildingType	Whether the first special slot's animation is destroyed and recreated with its house's power.	boolean	no
SpecialAnimTwoBuildingType	The animation the structure runs in its second special slot.	string	(empty)
SpecialAnimTwoDamagedBuildingType	The animation the second special slot runs while the structure is damaged.	string	Inherited
SpecialAnimTwoXBuildingType	How far right of the structure's drawing point the second special slot's animation sits, in screen pixels.	integer	0
SpecialAnimTwoYBuildingType	How far below the structure's drawing point the second special slot's animation sits, in screen pixels.	integer	0
SpecialAnimTwoZAdjustBuildingType	The depth bias applied to the second special slot's animation.	integer	0
SpecialAnimTwoYSortBuildingType	The sorting bias applied to the second special slot's animation, in leptons.	integer	0
SpecialAnimTwoPoweredBuildingType	Whether the second special slot's animation freezes while its house is short of power.	boolean	yes
SpecialAnimTwoPoweredLightBuildingType	Whether the second special slot's animation is destroyed and recreated with its house's power.	boolean	no
SpecialAnimThreeBuildingType	The animation the structure runs in its third special slot.	string	(empty)
SpecialAnimThreeDamagedBuildingType	The animation the third special slot runs while the structure is damaged.	string	Inherited
SpecialAnimThreeXBuildingType	How far right of the structure's drawing point the third special slot's animation sits, in screen pixels.	integer	0
SpecialAnimThreeYBuildingType	How far below the structure's drawing point the third special slot's animation sits, in screen pixels.	integer	0
SpecialAnimThreeZAdjustBuildingType	The depth bias applied to the third special slot's animation.	integer	0
SpecialAnimThreeYSortBuildingType	The sorting bias applied to the third special slot's animation, in leptons.	integer	0
SpecialAnimThreePoweredBuildingType	Whether the third special slot's animation freezes while its house is short of power.	boolean	yes
SpecialAnimThreePoweredLightBuildingType	Whether the third special slot's animation is destroyed and recreated with its house's power.	boolean	no
ProductionAnimBuildingType	The animation a structure runs while its work is in progress.	string	(empty)
ProductionAnimDamagedBuildingType	The animation the production slot runs while the structure is damaged.	string	Inherited
ProductionAnimXBuildingType	How far right of the structure's drawing point the production animation sits, in screen pixels.	integer	0
ProductionAnimYBuildingType	How far below the structure's drawing point the production animation sits, in screen pixels.	integer	0
ProductionAnimZAdjustBuildingType	The depth bias applied to the production animation.	integer	0
ProductionAnimYSortBuildingType	The sorting bias applied to the production animation, in leptons.	integer	0
PreProductionAnimBuildingType	The animation a structure runs while work is being set up on it.	string	(empty)
PreProductionAnimDamagedBuildingType	The animation the pre-production slot runs while the structure is damaged.	string	Inherited
PreProductionAnimXBuildingType	How far right of the structure's drawing point the pre-production animation sits, in screen pixels.	integer	0
PreProductionAnimYBuildingType	How far below the structure's drawing point the pre-production animation sits, in screen pixels.	integer	0
PreProductionAnimZAdjustBuildingType	The depth bias applied to the pre-production animation.	integer	0
PreProductionAnimYSortBuildingType	The sorting bias applied to the pre-production animation, in leptons.	integer	0
TurretAnimBuildingType	The animation a building's turret is drawn from, or the voxel model that replaces it.	string	(empty)
TurretAnimDamagedBuildingType	The turret animation a building shows once it is damaged.	string	Computed
TurretAnimXBuildingType	The horizontal screen offset from a building's artwork to its turret.	integer	0
TurretAnimYBuildingType	The vertical screen offset from a building's artwork to its turret.	integer	0
TurretAnimZAdjustBuildingType	The depth bias a building's turret art is drawn with.	integer	0
TurretAnimYSortBuildingType	The bias added to where a building's turret animation falls in the draw order.	integer	0
TurretAnimIsVoxelBuildingType	Draws a building's turret from a voxel model rather than from an animation.	boolean	no
TurretAnimIsExclusiveBuildingType	Runs a building's turret animation only while its weapon is charging, in place of its second active animation.	boolean	no
TurretChargeAnimRateBuildingType	The delay between frames of a building's turret animation while its weapon charges.	integer	3
ChargeAnimBuildingType	Drives a turretless structure's turret animation from its charge counter.	boolean	no
TeslaChargeglobal rules	Sound a structure makes as its electric weapon begins charging.	sound	none
TeslaZapNo effectglobal rules	Parsed sound that no turret ever discharges.	sound	none
UpgradesBuildingType	How many upgrade plugs the structure accepts.	integer	0
AnimIdleBuildingType	The first frame, frame count and step delay of a structure's resting animation.	string	0,1,0
AnimActiveBuildingType	The first frame, frame count and step delay of a structure's working animation.	string	0,1,0
AnimAux1BuildingType	The first frame, frame count and step delay of a structure's first auxiliary animation.	string	0,1,0
AnimAux2BuildingType	The first frame, frame count and step delay of a structure's second auxiliary animation.	string	0,1,0
ExtraDamageStageNo effectBuildingType	Parsed flag that the engine never uses.	boolean	yes
DeployingAnimBuildingType	The shape file that replaces a structure's own artwork while it unloads.	string	(empty)
DoorAnimBuildingType	The shape file drawn over a structure as its factory door works.	string	(empty)
DoorStagesBuildingType	The number of frames the factory door animation steps through.	integer	0
DamagedDoorBuildingType	Draws the factory door animation from a second block of frames once the structure is damaged.	boolean	no
UnderDoorAnimBuildingType	The shape drawn beneath a structure's factory door while it unloads.	string	(empty)
BibBuildingType	Opens the eastern edge of the structure's footprint to vehicles.	boolean	no
BibShapeBuildingType	The apron shape drawn on the ground under a structure.	string	(empty)
SensorArrayBuildingType	Whether the structure marks the cells around it as sensed, revealing cloaked objects standing there.	boolean	no
UnitRepairBuildingType	Makes the building take in one vehicle or aircraft at a time and repair it for credits.	boolean	no
SiloDamageBuildingType	Draws a fill level on a building that stores Tiberium.	boolean	no
FirestormWallBuildingType	Whether the structure is a firestorm wall section, raised and lowered with its house's firestorm defense.	boolean	no
SurfaceAnimType	Places the animation in the ground layer, among the units and structures, rather than in the layer above them.	boolean	no
YSortAdjustAnimType	Biases where the animation falls in the ground layer's drawing order, in leptons.	integer	0

Related resources

• Power output and drainFeature or system
• Repair and healingFeature or system
• Production and factoriesFeature or system
• Laser fences and the firestorm wallFeature or system
• EMP pulseFeature or system
• Cloaking and detectionFeature or system
• SHP imagesFormat

Page feedback

Report an error or missing detail. The issue includes this page and revision.

Open issueSource revision 59fae722af8c