.ANIMATED

The .animated object format

Check this tutorial out:

Animated Object Building Tutorial By willischong

■ 1. Overview

---

The ANIMATED object format is a container format allowing you to reference other objects (B3D/CSV/X) and to apply animation to them. It also allows to just group other objects (including other ANIMATED objects) without animating them.

Animated objects can be used in CSV/RW routes (unless explicitly disallowed by some commands), as train exterior objects via the extensions.cfg, and as 3D cabs via the panel.animated file.

● Basics

Animation is performed via the following primitives:

●

State changes - basically allowing to switch between different objects at any time

●

Translation - moving objects in three independent directions

●

Rotation - rotating objects around three independent axes

●

Texture shifts - allowing to shift the texture coordinates of objects in two independent directions

● A little formality

The file is a plain text file encoded in any arbitrary encoding, however, UTF-8 with a byte order mark is the preferred choice. The parsing model for numbers is Strict. The file name is arbitrary, but must have the extension .animated. The file is interpreted on a per-line basis, from top to bottom.

■ 2. Sections

---

● The [Include] section

You can use the [Include] section to just include other objects, but without animating them. This allows you to use the ANIMATED object file as a container to group other objects. There can be any number of [Include] sections within the file.

[Include]

This starts the section.

FileName0 FileName1 FileName2 ...

Defines a series of B3D/CSV/X/ANIMATED objects that should be included as-is.

Position = X, Y, Z

This defines the position of the objects, basically allowing you to offset them with respect to the rest of the ANIMATED object file.

---

● The [Object] section

You can use the [Object] section to create a single animation. This requires to set up at least one state via the States parameter, and to use any combination of functions you want, which provide control over the animation. There can be any number of [Object] sections within the file.

[Object]

This starts the section.

Position = X, Y, Z

Defines the position of the object. This basically corresponds to a final TranslateAll command in the respective CSV/B3D file, but is performed after any of the functions are performed. For example, if you want to use rotation, then keep in mind that rotation is done around the origin (0,0,0). The Position command allows you to reposition the object after the rotation is performed.

States = File0, File1, ..., Filen-1

Loads n objects of CSV/B3D/X extension. Please note that the first file indicated has state index 0. Use multiple files only if you want to use state changes.

StateFunction = Formula

This defines the function for state changes. The result of the Formula is rounded toward the nearest integer. If that integer is between 0 and n-1, where n is the number of states as defined via States, the respective state is shown, otherwise, no object is shown. You can make use of the latter if you want an object to toggle on/off with only one state.

TranslateXDirection = X, Y, Z TranslateYDirection = X, Y, Z TranslateZDirection = X, Y, Z

These define the directions for the TranslateXFunction, TranslateYFunction and TranslateZFunction, respectively. The default directions are:

TranslateXDirection = 1, 0, 0
TranslateYDirection = 0, 1, 0
TranslateZDirection = 0, 0, 1

This means that TranslateXFunction will move right by default, TranslateYFunction up and TranslateZFunction forward, which is also why TranslateXFunction and so on bear their names. If you define other directions, then simply think of the three functions and associated directions as three independent ways to move the object in that direction.

TranslateXFunction = Formula TranslateYFunction = Formula TranslateZFunction = Formula

These define the functions to move the object into the respective direction. The Formula needs to return the amount of meters to move from the initial position. The X, Y and Z parameters in the respective direction are multiplied by the result of Formula, so you could for example either multiple the formula by 2 or the direction by 2 if you want to double the speed of movement.

RotateXDirection = X, Y, Z RotateYDirection = X, Y, Z RotateZDirection = X, Y, Z

These define the directions for the RotateXFunction, RotateYFunction and RotateZFunction, respectively. The default directions are:

RotateXDirection = 1, 0, 0
RotateYDirection = 0, 1, 0
RotateZDirection = 0, 0, 1

This means that RotateXFunction will rotate around the x-axis by default, RotateYFunction around the Y-axis, and RotateZFunction around the z-axis, which is also why RotateXFunction and so on bear their names. If you define other directions, then simply think of the three functions and associated directions as three independent ways to rotate the object.

RotateXFunction = Formula RotateYFunction = Formula RotateZFunction = Formula

These define the functions to rotate along the respective direction in counter-clockwise order. The Formula needs to return the angle by which to rotate in radians. The order in which the rotations are performed is: RotateXFunction (first), RotateYFunction (then) and RotateZFunction (last). If you use more than one rotation function at a time, bear this order in mind. If necessary, overwrite the default directions for the rotations if you need a different order.

RotateXDamping = NaturalFrequency, DampingRatio RotateYDamping = NaturalFrequency, DampingRatio RotateZDamping = NaturalFrequency, DampingRatio

These define damping for the corresponding functions. If not used, damping will not be performed. NaturalFrequency is a non-negative value corresponding to the angular frequency of an assumed undamped oscillator in radians per second. DampingRatio is a non-negative value indicating the type of damping. Values between 0 and 1 represent under-damping, 1 represents critical damping, and values above 1 represent over-damping.

TextureShiftXDirection = X, Y TextureShiftYDirection = X, Y

These define the directions for the TextureShiftXFunction and TextureShiftYFunction, respectively. The default directions are:

TextureShiftXDirection = 1, 0
TextureShiftYDirection = 0, 1

This means that TextureShiftXFunction will shift the texture right by default, and TextureShiftYFunction down, which is also why TextureShiftXFunction and so on bear their names. If you define other directions, then simply think of the two functions and associated directions as two independent ways to shift textures on the objects.

TextureShiftXFunction = Formula TextureShiftYFunction = Formula

These define the functions to shift the texture in the respective direction. The texture is shifted by the return value of Formula in texture coordinates. The integer part of the result is ignored, and a fractional part of 0.5 represents moving the texture half way. The SetTextureCoordinate commands in the object file define the coordinates, which are then added the outcome of these formulas.

TextureOverride = Value

Value = Timetable: All faces will show the timetable bitmap as set up by CSV/RW routes.
Value = None: The original textures will be displayed on the faces (default behavior).

RefreshRate = Seconds

This defines the minimum amount of time that needs to pass before the functions are updated. A value of 0 forces the functions to be updated every frame. Please note that objects outside of the visual range might be updated less frequently regardless of this parameter. Use RefreshRate when you don't need a perfectly smooth animation (in order to optimize performance), or when you deliberately want the object to be only updated in fixed intervals.

---

⚠

openBVE 2 compatibility note: During the development of openBVE (v0.9) and during the development of the animated object format, there were certain commands in existance ending in RPN, such as TranslateXFunctionRPN. These commands never made it into any official release (v1.0) and were thus never meant to be used outside of development environments. While they are still available undocumentedly, they will be removed for openBVE 2. If you are using these commands, please get rid of them as soon as possible.

---

● About the formulas

First of all, infix notation, which is what you can enter for Formula, is converted into functional notation. Thus for every infix notation, there is a corresponding functional notation. Some functions do not have an infix operator and can thus only be entered in functional notation. For operators, precedence plays an important role. You can use parantheses to override the order of precedence just as in any usual mathematical formula. Names of functions are case-insensitive.

⚠

Please note that if the result of any mathematical operation or function would be infinity, indeterminate or non-real, 0 is returned. Numeric overflow is not prevented, so you need to take that into account yourself.

■ 3. List of infix notation operators

---

● Basic arithmetics

Infix	Functional	Description
a + b	Plus[a,b, ...]	Represents addition
a - b	Subtract[a,b]	Represents subtraction
-a	Minus[a]	Negates the number
a * b	Times[a,b,...]	Represents multiplication
a / b	Divide[a,b]	Represents division

● Comparisons

All comparisons return 1 for true and 0 for false.

Infix	Functional	Description
a == b	Equal[a,b]	True (1) if a equals b
a != b	Unequal[a,b]	True (1) if a does not equal b
a < b	Less[a,b]	True (1) if a is less than b
a > b	Greater[a,b]	True (1) if a is greater than b
a <= b	LessEqual[a,b]	True (1) if a is less than or equal to b
a >= b	GreaterEqual[a,b]	True (1) if a is greater than or equal to b

● Logical operations

All operations treat 0 as false and any other value as true, and return 1 for true and 0 for false.

Infix	Functional	Description
!a	Not[a]	True (1) if a is false
a & b	And[a,b]	True (1) if both a and b are true
a | b	Or[a,b]	True (1) if any of a or b are true
a ^ b	Xor[a,b]	True (1) if either a or b is true

● Operator precedence

From highest precedence to lowest. Operators of same precedence are evaluated left to right in the order in they occur in the formula.

- (Minus)

/

*

+, - (Subtract)

==, !=, <, >, <=, >=

!

&

^

|

⚠

Please note that some combinations of prefix and infix operators are not recognized. For example a*-b is not accepted. Use a*(-b) or -a*b instead.

■ 4. List of functions

---

● Basic arithmetics

Function	Description
Reciprocal[x]	Returns the reciprocal, equal to 1/x
Power[a,b,...]	Returns a raised to the bth power. b must be a non-negative number. For consistency, Power[0,b] always returns 1, even in the degenerate case Power[0,0], and a being negative always returns 0.

● Numeric functions

Function	Description
Quotient[a,b]	Divides a by b and rounds the result down, equal to Floor[a/b].
Mod[a,b]	Returns the remainder of dividing a by b, equal to a-b*Floor[a/b].
Min[a,b,...]	Returns the smallest of the terms.
Max[a,b,...]	Returns the largest of the terms.
Abs[x]	Returns the absolute value.
Sign[x]	Returns the sign of x, which is either -1, 0 or 1.
Floor[x]	Rounds down to the nearest integer.
Ceiling[x]	Rounds up to the nearest integer.
Round[x]	Rounds to the nearest integer. Numbers ending in .5 are rounded to the nearest even integer.

● Elementary functions

Function	Description
Exp[x]	The exponential function, or e to the xth power.
Log[x]	The natural logarithm, to base e.
Sqrt[x]	The square root.
Sin[x]	The sine (input in radians).
Cos[x]	The cosine (input in radians).
Tan[x]	The tangent (input in radians).
ArcTan[x]	The inverse tangent (output in radians).

● Conditionals

Function	Description
If[cond,truevalue,falsevalue]	If cond is != 0, returns truevalue, otherwise falsevalue

■ 5. List of variables

---

● Primitives

Variable	Description
value	The value returned by the function in the last evaluation. At the beginning of the simulation, this is 0.
delta	The time difference since the last evaluation of the function in seconds. Please note that there is no guaranteed time that elapses between successive function calls.

● Time and camera

Variable	Description
time	The current in-game time measured in seconds since midnight of the first day.
cameraDistance	The non-negative cartesian distance measured from the object to the camera in meters.

● Trains

Generally, objects attached to a particular train and car return values for that train and car, unless stated otherwise. For scenery objects, the reference is the driver's car of the nearest train (not necessarily the player's train).

In some of the following variables, carIndex has the following meaning: 0 is the 1^st car from the front, 1 is the 2^nd car from the front, etc., while -1 is the 1^st car from the rear, -2 is the 2^nd car from the rear, etc. In general, car indices from -cars to cars-1 represent existing cars, where cars is the number of cars the train has, while values outside of this range represent non-existing cars. As all trains have at least 1 car, indices -1 and 0 are guaranteed to exist for any train.

● Trains (general)

Variable	Description
cars	The number of cars the train has.
speed	The signed actual speed of the current car in m/s. Is positive when the train travels forward, and negative when the train travels backward.
speed[carIndex]	The signed actual speed of the car carIndex in m/s. Is positive when the train travels forward, and negative when the train travels backward.
speedometer	The signed perceived speed of the current car in m/s as it would appear to a speedometer on wheel slip and wheel lock.
speedometer[carIndex]	The signed perceived speed of the car carIndex in m/s as it would appear to a speedometer on wheel slip and wheel lock.
acceleration	The actual acceleration of the current car in m/s².
acceleration[carIndex]	The actual acceleration of the car carIndex in m/s².
accelerationMotor	The acceleration which the motor of the first motor car currently generates in m/s².
accelerationMotor[carIndex]	The acceleration which the motor of the car carIndex currently generates in m/s².
distance	The non-negative cartesian distance measured from the object to the closest car in meters. Only meaningful for scenery objects.
distance[carIndex]	The non-negative cartesian distance measured from the object to the car carIndex in meters, or 0 if the car does not exist. Only meaningful for scenery objects.
trackDistance	The signed track distance measured from the object to the closest end of the train in meters. Is positive when the train is in front of the object, negative when behind, and zero when the object lies between the ends of the train. Only meaningful for scenery objects. Deprecated. The behavior of this variable may change in future versions of openBVE.
trackDistance[carIndex]	The signed track distance measured from the object to the car carIndex in meters. Is positive when the center of the car is in front of the object, and negative if behind. Returns 0 if the car does not exist. Only meaningful for scenery objects. Deprecated. The behavior of this variable may change in future versions of openBVE.

● Trains (brake)

Variable	Description
mainReservoir	The current pressure in the main reservoir in this car, measured in Pa.
mainReservoir[carIndex]	The current pressure in the main reservoir in car carIndex, measured in Pa.
emergencyReservoir	The current pressure in the emergency reservoir in this car, measured in Pa.
emergencyReservoir[carIndex]	The current pressure in the emergency reservoir in car carIndex, measured in Pa.
brakePipe	The current pressure in the brake pipe in this car, measured in Pa.
brakePipe[carIndex]	The current pressure in the brake pipe in car carIndex, measured in Pa.
brakeCylinder	The current pressure in the brake cylinder in this car, measured in Pa.
brakeCylinder[carIndex]	The current pressure in the brake cylinder in car carIndex, measured in Pa.
straightAirPipe	The current pressure in the straight air pipe in this car, measured in Pa.
straightAirPipe[carIndex]	The current pressure in the straight air pipe in car carIndex, measured in Pa.

● Trains (doors)

Variable	Description
doors	The state of the doors. Returns 0 if fully closed, 1 if fully opened, or any intermediate value, biasing doors that are in a more open state.
doors[carIndex]	The state of the doors of car carIndex. Returns 0 if fully closed, 1 if fully opened, or any intermediate value, biasing doors that are in a more open state.
leftDoors	The state of the left doors. Returns 0 if fully closed, 1 if fully opened, or any intermediate value, biasing doors that are in a more open state.
leftDoors[carIndex]	The state of the left doors of car carIndex. Returns a value between 0 and 1, biasing doors that are in a more open state, or -1 if the car does not exist.
rightDoors	The state of the right doors. Returns 0 if fully closed, 1 if fully opened, or any intermediate value, biasing doors that are in a more open state.
rightDoors[carIndex]	The state of the right doors of car carIndex. Returns a value between 0 and 1, biasing doors that are in a more open state, or -1 if the car does not exist.
leftDoorsTarget	The anticipated target state of the left doors. Returns either 0 (closed) or 1 (opened).
leftDoorsTarget[carIndex]	The anticipated target state of the left doors of car carIndex. Returns either 0 (closed) or 1 (opened).
rightDoorsTarget	The anticipated target state of the right doors. Returns either 0 (closed) or 1 (opened).
rightDoorsTarget[carIndex]	The anticipated target state of the right doors of car carIndex. Returns either 0 (closed) or 1 (opened).

● Trains (miscellaneous)

Variable	Description
reverserNotch	The state of the reverser, which is either -1 (backward), 0 (neutral), or forward (1).
powerNotch	The current power notch, i.e. 0 for N, 1 for P1, 2 for P2, 3 for P3, etc.
powerNotches	The amount of power notches the train has.
brakeNotch	The current brake notch. ● For trains without the automatic air brake: 0 for N, 1 for B1, 2 for B2, 3 for B3, etc. ● For trains with the automatic air brake: 0 for REL, 1 for LAP and 2 for SRV.
brakeNotches	The amount of brake notches the train has. For trains with the automatic air brake, this returns 2.
brakeNotchLinear	A combination of brake notch, hold brake and emergency brake. ● For trains without the automatic air brake and without hold brake: 0 for N, 1 for B1, 2 for B2, 3 for B3, etc., up to BrakeNotches+1 for EMG. ● For trains without the automatic air brake but with hold brake: 0 for N, 1 for HLD, 2 for B1, 3 for B2, 4 for B3, etc., up to BrakeNotches+2 for EMG. ● For trains with the automatic air brake: 0 for REL, 1 for LAP, 2 for SRV or 3 for EMG.
brakeNotchesLinear	The highest value returned by brakeNotchesLinear. ● For trains without the automatic air brake and without hold brake, this is BrakeNotches+1. ● For trains without the automatic air brake but with hold brake, this is BrakeNotches+2. ● For trains with the automatic air brake, this returns 3.
emergencyBrake	Whether the emergency brake is currently active (1) or not (0).
hasAirBrake	Whether the train has the automatic air brake (1) or not (0).
holdBrake	Whether the hold brake is currently active (1) or not (0).
hasHoldBrake	Whether the train has a hold brake (1) or not (0).
constSpeed	Whether the const speed system is currently active (1) or not (0).
hasConstSpeed	Whether the train has a const speed system (1) or not (0).
hasPlugin	Whether the train uses a plugin (1) or not (0).
pluginState[i]	The state of the ith plugin variable, returning an integer depending on the plugin. Is the same as atsi in the panel2.cfg.

If pluginState[i] is used with the built-in safety systems ATS and ATC, the following mappings for i apply:

i	English	日本語	Return values		pluginState[271]	Meaning
256	ATS	ATS	0 (unlit) or 1 (lit)		0	ATC not available
257	ATS RUN	ATS 作動	0 (unlit), 1 (lit) or 2 (flashing)		1	0 km/h
258	ATS RUN	ATS 作動	0 (unlit / non-flashing), 1 (lit / flashing)		2	15 km/h
259	P POWER	P 電源	0 (unlit) or 1 (lit)		3	25 km/h
260	PTN APPROACH	パターン接近	0 (unlit) or 1 (lit)		4	45 km/h
261	BRAKE RELEASE	ブレーキ開放	0 (unlit) or 1 (lit)		5	55 km/h
262	BRAKE APPLY	ブレーキ動作	0 (unlit) or 1 (lit)		6	65 km/h
263	ATS P	ATS-P	0 (unlit) or 1 (lit)		7	75 km/h
264	FAILURE	故障	0 (unlit) or 1 (lit)		8	90 km/h
265	ATC	ATC	0 (unlit) or 1 (lit)		9	100 km/h
266	ATC POWER	ATC 電源	0 (unlit) or 1 (lit)		10	110 km/h
267	ATC SRV	ATC 常用	0 (unlit) or 1 (lit)		11	120 km/h
268	ATC EMG	ATC 非常	0 (unlit) or 1 (lit)		12	ATS is active
269	CONST SPEED	定速	0 (unlit) or 1 (lit)
270	EB	EB	0 (unlit) or 1 (lit)
271	ATC speed indicator		0 - 12, see table on the right

● Sections (signalling)

The section context is defined when the object is placed using Track.SigF.

Variable	Description
section	The value of the section aspect currently shown. If this variable is used outside of a Track.SigF context, the behavior is currently undefined and subject to change.

■ 6. Performance

---

There are certain kinds of animation which are less expensive, and others which are more. Also, the underlying object plays a significant role. If you want to design your animated objects with as best performance as possible for future releases of openBVE, take a look at the following performance table:

Animation	Object	Performance
State changes	Has only opaque faces	Good
State changes	Has partially transparent faces	Moderate
Translation	Has only opaque faces	Good
Translation	Has partially transparent faces	Moderate
Rotation	Has only opaque faces	Good
Rotation	Has partially transparent faces	Bad
Texture shifts	Has only opaque faces	Bad
Texture shifts	Has partially transparent faces	Bad

Performance is generally better if the result of a function only infrequently changes. So, even if you set the RefreshRate parameter to zero, performance is generally better if the outcome of your formula is constant over longer periods of time. On the other hand, if it changes every frame, performance is generally worse.

Generally, you should avoid using animation with partially transparent faces and stick to opaque faces when possible. Also, try to avoid texture shifts, and consider using state changes or translation where possible.

■ 7. Tips

---

●

Generally speaking, try to keep the complexity of functions as low as possible. This is not the most critical aspect, though, as most of the performance impact will result from applying the results of a function, e.g. rotating the object, and not evaluating the function.

●

Use the RefreshRate parameter when possible to optimize performance. Usually, you can use this parameter when you don't need a smooth animation, or when you deliberately want the functions to only update in intervals.

●

Don't use functions which always evaluate to the same constant. For example, don't use RotateXFunction = 3.14159, but rotate the underlying CSV/B3D/X object directly.

●

State changes are very cheap as long as the state doesn't actually change in between two executions of the StateFunction. If a change occurs, this is a relatively expensive operation, though.

●

Try to optimize out if conditions. Especially try to avoid nested if functions. Often, there is an elegant mathematical solution.

●

Certain functions, e.g. Exp, Sin, Cos, etc., are relatively expensive. Use them only if absolutely necessary for an effect. Don't include unnecessary operations. For example, the result of StateFunction is automatically rounded toward the nearest integer, so don't apply an additional explicit Round.

●

When working with car objects, bear in mind that some variables have an optional car index. You should use this index if you want to query the state of a particular car (that is, not necessarily the one the object is attached to). If, however, you just want to query the value of the particular car the object is attached to, use the variable without the index. For scenery objects, you should not generally use car indices as you can't be sure how many cars the queried train has.

■ 8. Example functions

---

● Blinking light

	Template for a blinking light:
▶	States = OBJECT0, OBJECT1 StateFunction = value == 0 RefreshRate = SECONDS

● Rotating wheel

	Template for the code used in an exterior car object:
▶	States = OBJECT RotateXFunction = value + delta * speedometer / RADIUS_OF_THE_WHEEL

● Cycling through a list of objects

	Template for objects that are to be cycled through:
▶	States = OBJECT0, OBJECT1, OBJECT2, ... StateFunction = mod[value + 1, AMOUNT_OF_OBJECTS] RefreshRate = TIME_PER_OBJECT

● Signal (3-aspect) for Track.Section(0; 2; 4)

	'
▶	States = RED_OBJECT, YELLOW_OBJECT, GREEN_OBJECT StateFunction = section / 2

● Employing an approach-controlled delay in signals

If you want to create a signal that keeps being red until the train approaches it to some distance, then counts down a timer before it changes aspect to green, please refer to this post on the forum for a detailed explanation. Once you understand the concepts, you can use this code template:

	Template for an approach-controlled delay in a signal with two aspects:
▶	States = RED_OBJECT, GREEN_OBJECT StateFunction = if[trackDistance>DISTANCE | section==0, 0, min[value + 0.5*delta/DELAY, 1]]

	Template for an approach-controlled delay in a signal with any number of aspects:
▶	States = RED_OBJECT, ..., GREEN_OBJECT StateFunction = if[trackDistance>DISTANCE | section==0, 0, if[value<0.5, value + 0.5*value/DELAY, section]]