Building animations

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

Changed in 0.2.0

A structure animates in two independent ways. Its artwork steps through a few frame sequences, covered in the last section. It can also run up to thirteen attached animations. Each is a separate animation from the [Animations] list, pinned to a point on the structure’s artwork and playing at its own rate. The structure creates and removes these animations as its state changes. Most of this page covers attached animations.

Each attached animation occupies an animation slot. A BuildingType has one set of settings per slot, and a structure runs at most one animation in each slot at a time. Events on the structure fill and empty the slots. A slot that no event fills never runs anything, whatever settings are written for it.

The thirteen slots

The table lists each slot, the key that names its animation, and when the slot is filled. The key pages give the full timing for each kind of structure.

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 or third Upgrades= plug is installed. Removing that plug empties the slot
Active one to four	ActiveAnim=, ActiveAnimTwo=, ActiveAnimThree=, ActiveAnimFour=	The structure comes online, either when construction finishes or when the scenario places it. A repair step, or a plug installed on a damaged structure, refills any active slot that is empty. A repair step skips active slot two while a TurretAnimIsExclusive=yes turret is charging or charged
Pre-production	PreProductionAnim=	A construction yard begins a structure, or a harvester begins unloading into the structure
Production	ProductionAnim=	A construction yard finishes a structure, a factory releases what it built, a refinery finishes unloading a harvester, or a service depot begins a repair
Turret	TurretAnim=	A turret-equipped or ChargeAnim=yes structure comes online, or the structure begins charging its weapon. With TurretAnimIsExclusive=yes, only charging fills it. A TurretAnimIsVoxel=yes structure skips the fill when it comes online
Special one to three	SpecialAnim=, SpecialAnimTwo=, SpecialAnimThree=	An event on a UnitRepair=yes, SiloDamage=yes or FirestormWall=yes structure

Three active-slot rules apply only to particular structures:

• On a SensorArray=yes structure, active slot one starts 30 game frames (two seconds) after construction finishes. No other start of an active slot is delayed.
• A UnitRepair=yes service depot stops active slot one while it repairs a vehicle. A service depot covers when it starts again.
• A TurretAnimIsExclusive=yes structure stops active slot two while its turret charges, and starts it again once the charge is spent.

The turret slot’s animation does not play at its own rate. The structure sets its frame on every update, from the direction the turret faces. On a ChargeAnim=yes structure the frame comes from a charge counter instead, which advances at TurretChargeAnimRate. TeslaCharge plays when charging begins. TeslaZap is never played.

This example gives a structure one active animation, written in its Image ID art entry:

art.ini

[MYSTRUCT]                ; the Image ID entry this structure is drawn from
ActiveAnim=TURBINE_A      ; both names are AnimTypes from [Animations]
ActiveAnimDamaged=TURBINE_AD
ActiveAnimX=20
ActiveAnimY=-30
ActiveAnimYSort=14
ActiveAnimZAdjust=-5

TURBINE_A runs 20 pixels right of and 30 pixels above the structure’s drawing point, and TURBINE_AD replaces it once the structure is damaged. The negative ActiveAnimZAdjust brings it slightly toward the viewer.

Building and emptying a slot

Every slot is filled the same way. The structure picks the slot’s healthy or damaged name, as described under The damaged form. If that name is empty, nothing happens. Otherwise the structure creates that animation at its drawing point, moved by the slot’s …X and …Y offset and given the slot’s two draw-order biases. Only the first 15 characters of an animation name are kept.

A name that no [Animations] entry registers creates nothing, and the slot keeps whatever it held. The form still changes: if the name belonged to the form the structure is not showing, every running animation switches to that form.

Filling a slot that already holds an animation replaces it. The new animation continues from the frame the old one had reached, so the swap does not show as a jump.

Two cases do not use the slot’s names:

• The structure that WallTower names cycles through lettered turret variants, named after its Image ID with _B, _C or _D appended. They use the turret slot’s offset and biases.
• A FirestormWall=yes section fills its first two special slots with fixed animations. A firestorm wall section covers them.

A slot empties when its animation plays to its end or when an event stops it. A looping animation therefore holds its slot until something stops it, while a finite one frees the slot when it ends. All thirteen slots empty when the structure begins to be sold or undeployed, and when it is removed from the game.

Attached animations follow the structure. When the structure is placed on a new cell, each animation moves to its slot’s offset from the new position.

Cloaking fades the attached animations along with the structure. Animations that keep the default ShouldUseCellDrawer=yes are also drawn in the owner’s colors at the structure’s brightness.

Under fog of war, the player sees the structure’s remembered image, with each attached animation frozen at the frame it had reached when fog covered it. The live animations are marked as fogged, and so is any animation created while the structure stays fogged. Uncovering the structure clears the mark. A marked animation is not drawn unless its AnimType sets ShouldFogRemove=no.

The damaged form

Each slot has a healthy name and a damaged name. Most fills use the damaged name when the structure’s health is at or below ConditionYellow at that moment. Some fills always use the healthy name; they are listed at the end of this section.

A slot that names only a healthy form uses that name in both states. The upgrade slots are the exception: an upgrade slot without PowerUp<n>DamagedAnim= keeps running its healthy animation while the structure is damaged.

A slot that names only a damaged form starts only when it is filled in the damaged form. It does not start while the structure is healthy, and it never starts from the fills listed below that always use the healthy name. If it starts while the structure is damaged, repairing the structure leaves that animation running.

Apart from those cases, a structure shows all its attached animations in one form at a time. Whenever a slot is filled in the other form, every animation the structure is running restarts in that form. Each damage or repair step checks the structure’s health again, and if the result differs from the form on show, the whole set switches at once.

Some fills always use the healthy form, whatever the structure’s health. On a damaged structure, each of them switches every running animation back to healthy. The set stays healthy until a damage or repair step, or until another slot is filled in the damaged form. The fills that do this are:

• the production slot’s start on every structure except a construction yard (ProductionAnim lists them);
• the pre-production slot’s start when a harvester begins unloading;
• every animation of a service depot’s repair sequence;
• the fill indicator of a SiloDamage=yes structure.

Placement and draw order

…X and …Y move the animation from the structure’s drawing point, in screen pixels. A positive …X moves it right and a positive …Y moves it down. The … stands for the slot’s key prefix, so active slot one uses ActiveAnimX= and active slot two uses ActiveAnimTwoX=. The offset pins the animation to a point on the artwork, not to a cell.

…ZAdjust and …YSort both decide what the animation is drawn over, in different ways:

• …ZAdjust shifts the depth the animation’s pixels are tested at. A negative value brings the animation toward the viewer, so it covers the structure and anything else at that depth. A positive value pushes it back, so the structure covers it.
• …YSort is added to the animation’s sorting position, in leptons; a cell is 256 leptons. Sorting orders the ground layer once a frame. An AnimType left at the default Surface=no is drawn in the air layer, which is never sorted, so …YSort has no effect on it.

The slot replaces the animation’s sort bias

An AnimType can set a sort bias with YSortAdjust=. A building slot replaces that bias with the slot’s …YSort, which is 0 when omitted. To keep the AnimType’s bias in a building slot, repeat the value in the slot’s …YSort.

Keep both biases between -128 and 127

…ZAdjust and …YSort are each stored in one signed byte. A value outside -128 to 127 wraps around: …ZAdjust=200 is stored as -56, which draws the animation in front of the structure it was meant to hide behind. The same limit keeps …YSort within about half a cell in either direction.

Power

Two flags decide what a slot’s animation does when its house is short of power. Only the active and special slots have them; on active slot one they are ActiveAnimPowered= and ActiveAnimPoweredLight=.

• …Powered=yes freezes the animation on its current frame. It stays on screen and resumes at full power.
• …PoweredLight=yes removes the animation, and creates it again at full power.

Only one of the two flags is used. The structure tests …Powered first and reads …PoweredLight only when …Powered is no. Because …Powered defaults to yes, a slot that should use …PoweredLight=yes must also set …Powered=no.

The upgrade, pre-production, production and turret slots have no power flags and always behave as …Powered=yes. A frozen turret animation still follows the turret’s facing, because the structure sets its frame directly.

The house applies these flags to every structure it owns each time it rechecks its power. At full power it resumes frozen animations and creates any missing …PoweredLight=yes animation on every structure. Below full power, only some structures freeze or remove their animations; Fields, fences and lights says which.

The full-power pass is the only way a structure that is not UnitRepair=yes, SiloDamage=yes or FirestormWall=yes runs a special animation.

Switching one structure off with the power cursor or the Turn off building trigger action freezes its …Powered=yes animations. Switching off also makes the house recheck its power. If the house has full power after the switch, that recheck resumes the animations at once. If the house is short of power, they stay frozen until the house next rechecks its power at full power.

An EMP pulse freezes the same animations. They resume when the structure recovers from the pulse, or earlier if the house rechecks its power at full power in the meantime.

Neither switching off nor an EMP pulse removes a …PoweredLight=yes animation unless the house is also short of power.

Where each setting is read from

A slot’s settings do not all come from the same section. The difference matters only for a structure that borrows another structure’s artwork with Image=, so that its Image ID and ObjectType ID name different sections. The table gives the section each half of a slot is read from.

Slot	Names	The remaining settings
Upgrade one to three	The Image ID art entry	The Image ID art entry
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

The active, special, production and pre-production slots read their remaining settings only when the slot has a name, healthy or damaged. A slot with neither name ignores them. The upgrade slots read theirs for each declared upgrade. The turret slot reads its four offset and bias settings in every case, from the same rules entry as its names:

rules.ini

[MYTURRET]                ; the structure's BuildingType entry
TurretAnim=TURRET_A       ; an AnimType registered in [Animations]
TurretAnimDamaged=TURRET_AD
TurretAnimX=0
TurretAnimY=-20
TurretAnimZAdjust=-10
TurretAnimYSort=0

The upgrade slots and the active slots share one array

The three upgrade slots come first among the thirteen, directly before the four active slots. Two operations find an upgrade slot by its number, and both run past upgrade slot three into the active slots.

The first is reading the art file. It reads one set of PowerUp<n> settings per declared upgrade, up to the Upgrades= count: PowerUp1Anim= and its companions into upgrade slot one, PowerUp2Anim= into slot two, and so on. A type that declares four upgrades therefore reads PowerUp4Anim= and its five companions into active slot one. Each PowerUp4 assignment that is present replaces the matching active-slot setting: its two names, its offset or one of its biases. A fifth, sixth and seventh upgrade reach active slots two, three and four in turn.

The second is installing a plug. The plug’s Image ID becomes the host type’s animation name for the upgrade slot being filled, replacing what PowerUp<n>Anim= gave. The animation that appears is therefore the [Animations] entry named after the plug’s Image ID. The name is stored on the host’s type, not on the one structure, so it applies to every structure of that type from then on.

Keep Upgrades= at 3 or below

A fourth plug fills active slot one. Its Image ID replaces the host type’s ActiveAnim= name, so every structure of the host type runs the plug’s animation in active slot one from then on. Upgrades covers the crash a fourth plug can also cause.

Keep a plug’s Image ID to 15 characters or fewer

A slot’s name holds 16 characters. A plug’s Image ID of 16 characters or more is copied without an end marker, so the stored name runs on into the damaged name stored after it.

The structure’s own frames

A structure’s artwork plays one of five frame sequences at a time. Four are declared in the Image ID art entry, each as a first frame, a frame count and a delay per frame:

• AnimIdle runs whenever no other sequence has taken over.
• AnimActive runs while the structure is working.
• AnimAux1 and AnimAux2 are used only by a missile silo, while its doors are held open and while they close.

The fifth is the construction sequence, which is not declared. It plays the Buildup= file. Its frame count is half the frames in that file, or GateStages plus one on a gate, and the delay per frame spreads BuildupTime across that count. A Theater=yes structure instead plays every frame of its buildup file over five seconds, so neither the halving nor BuildupTime applies to it.

Damaged artwork is a second block of frames after the healthy ones, shown at or below ConditionYellow. Where the damaged frame lies depends on the sequence:

• In the idle sequence, it is the frame directly after the healthy one.
• In the active and auxiliary sequences, it is offset by the end of whichever of the four declared sequences ends last (its first frame plus its frame count).
• The construction sequence has no damaged frames. Gates, laser fence sections and firestorm wall sections choose their frames differently.

ExtraDamageStage is read but has no effect.

Four more shapes are drawn with the structure, but none of them is an attached animation. Each is a shape file named in the Image ID art entry, and the structure chooses its frame, so none plays on its own:

• BibShape is drawn under the structure.
• DeployingAnim replaces the structure’s artwork while it releases a unit.
• DoorAnim and UnderDoorAnim are drawn around its factory door while it releases a unit.

Despite its name, Bib=yes does not draw the apron. It draws nothing, and lets vehicles drive onto the eastern edge of the structure’s footprint.

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 the structure has no 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 plays as it delivers what it built, after a harvester unloads, or while it repairs a vehicle.	string	(empty)
ProductionAnimDamagedBuildingType	The damaged form of a structure's production animation.	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 voxel models named by TurretAnim.	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	How many game frames each step of a building's weapon charge takes.	integer	3
ChargeAnimBuildingType	Drives a 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 structure plays when a charged weapon fires.	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, sorted among the objects on the ground, instead of 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

History

1. Changed0.2.0In development

   Stop a damaging building animation crashing the game

Page feedback

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

Open issueSource revision 51b52aa38392