You use the expression language to access attributes and methods of layer properties. To access a value, use a chain of object references separated by the period (.) operator. To chain object references past the layer level (for example, to refer to effect properties, masks, or text animators), you can also use parentheses. For example, to link the Opacity property in Layer A to the Blurriness property of the Gaussian Blur effect in Layer B, enter the following expression in the expression field for the Opacity property for Layer A:

  thisComp.layer("Layer B").effect("Gaussian Blur")("Blurriness")

Reading this expression from left to right, you progress from the higher-level, containing object down to the specific property:

• The global object used refers to the current composition: thisComp.

• A specific layer object within that composition is referred to by its name: layer("Layer B").

• A specific effect object within that layer is referred to by its name: effect("Gaussian Blur").

• A specific effect property within that effect is referred to by its name: ("Blurriness").

For the nth component of a multidimensional property, like the y component of an effect control point, append [n] at the end, like this:

  thisComp.layer("Layer B").effect("Advanced Lightning")("Origin")[1]

The default object for an expression is the property on which the expression is written, followed by the layer containing the expression; therefore, you do not need to specify the property. For example, a wiggle expression written on the Position property of a layer can be either of the following:

  wiggle(5, 10) 
  position.wiggle(5, 10)

You do need to include the layer and property when retrieving them from outside the layer and property on which the expression is written. For example, an expression written on the Opacity property of Layer B, linking it to the Rotation property of Layer A would look like this expression:

  thisComp.layer("Layer A").rotation

To see more examples of how this works, use the pick whip to link one layer property to another, and look at the expressions it creates.

Jeff Almasol provides a script on his redefinery website with which you can determine how to refer to any property in expressions.

An Array is a type of object that stores an ordered set of numbers. An Array is represented as a list of numbers separated by commas and surrounded by brackets, as in this example:

  [10, 23]

You can assign an Array object to a variable, making it easy to refer to array values in other areas of the expression. For example:

  myArray = [10, 23]

The dimension of an Array object is the number of elements in the array. The dimension of myArray is 2. Different properties in After Effects have different dimensions depending on the number of value arguments they have. In the expression language, the values of properties are either single values (Number objects) or arrays (Array objects).

The following table provides examples of some properties and their dimensions:

You can access the individual elements of an Array object by using brackets and an index number to indicate which element you want. The elements in an Array object are indexed starting from 0. Using the previous example, myArray[0] is 10 and myArray[1] is 23.

The following two expressions are equivalent:

  [myArray[0], 5] 
  [10, 5]

The Position property arrays are indexed as follows:

• position[0] is the x coordinate of position.

• position[1] is the y coordinate of position.

• position[2] is the z coordinate of position.

Colors are represented as four-dimensional arrays [red, green, blue, alpha]. In projects with a color depth of 8 bpc or 16 bpc, each value in a color array ranges from 0 (black) to 1 (white). For example, red can range from 0 (no color) to 1 (red). So, [0,0,0,0] is black and transparent, and [1,1,1,1] is white and completely opaque. In projects with a color depth of 32 bpc, values under 0 and over 1 are allowed.

If you use an index that is greater than the index of the highest-dimension component in an Array object, After Effects returns an error. For example, myArray[2] causes an error, but position[2] returns the z coordinate of Position.

Many of the properties and methods in the After Effects expression language take Array objects as arguments or return them as values. For example, thisLayer.position is an Array object that is either two-dimensional or three-dimensional depending on whether the layer is 2D or 3D.

If you want to write an expression that keeps the y value of an animation of Position but fixes the x value at 9, you would use the following:

  y = position[1]; 
  [9,y]

The following is even more succinct:

  [9, position[1]]

This is an important point, so let’s look at one more example. If you want to combine the x position value from Layer A with the y position value from Layer B, you would use the following:

  x = thisComp.layer("Layer A").position[0];  
  y = thisComp.layer("Layer B").position[1];  
  [x,y]

You can create an expression that refers to just one value within the array of a 2D or 3D property. By default, the first value is used, unless you specify otherwise. For example, if you drag the pick whip from the Rotation property of Layer A to Scale property of Layer B, the following expression appears:

  thisComp.layer("Layer B").scale[0]

By default, this expression uses the first value of the Scale property, which is width. If you prefer to use the height value instead, drag the pick whip directly to the second value instead of the property name, or change the expression as follows:

  thisComp.layer("Layer B").scale[1]

Conversely, if you drag the pick whip from the Scale property of Layer B to the Rotation property of Layer A, After Effects automatically creates a variable, assigns the one-dimensional Rotation property value to it, and then uses that variable for both dimensions of the Scale property:

  temp = thisComp.layer(1).transform.rotation; 
  [temp, temp]

In After Effects, many properties and methods take or return vectors. After Effects refers to an array as a vector if it represents either a point or direction in space. For example, After Effects describes position as returning a vector.

However, though a function like audioLevels does return a two-dimensional value (the left and right channel levels), it is not called a vector because it does not represent a point or direction. Some functions in After Effects accept vector arguments, but they are generally only useful when the values passed represent a direction. For example, cross(vec1, vec2) computes a third vector that is at right angles to the input vectors. The cross product is useful when vec1 and vec2 are two vectors representing directions in space, but not if they just represent two arbitrary collections of numbers.

Indexing for Layer, Effect, and Mask elements in After Effects starts from 1. For example, the first layer in the Timeline panel is layer(1).

Generally, it is best to use the name of a layer, effect, or a mask instead of a number to avoid confusion and errors if the layer, effect, or mask is moved, or if the arguments are changed during product updates and upgrades. When you use a name, always enclose it in straight quotes. For example, the first of these expressions is easier to understand than the second expression, and the first expression will continue to work even if you change the order of effects:

  effect("Colorama").param("Get Phase From")  
  effect(1).param(2)

Time within an expression is always in composition time (not layer time) and is measured in seconds. The default time for any expression is the current composition time at which the expression is being evaluated. The following expressions both use the default composition time and return the same values:

  thisComp.layer(1).position 
  thisComp.layer(1).position.valueAtTime(time)

To use a relative time, add an incremental time value to the time argument. For example, to get the Position value 5 seconds before the current time, use the following expression:

  thisComp.layer(1).position.valueAtTime(time-5)

Default time references to properties in nested compositions use the original default composition time, not remapped time. However, if you use the source function to retrieve a property, the remapped time is used.

For example, if the source of a layer in the containing composition is a nested composition, and in the containing composition you have remapped time, when you get the position values of a layer in the nested composition with the following expression, the position values use the default time of the composition:

  comp("nested composition").layer(1).position

However, if you access layer 1 using the source function, the position values use the remapped time:

  thisComp.layer("nested composition").source.layer(1).position

Because expressions operate on time in units of seconds (not frames), you sometimes need to use time conversion methods to convert time values to perform operations on frames. (See Time conversion methods (expression reference).)