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.

Animation is performed via the following primitives:

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.

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.

This starts the section.

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

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

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.

This starts the section.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

● Basic arithmetics

● Comparisons

All comparisons return 1 for true and 0 for false.

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

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

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.

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

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

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:

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.

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: