animation

NOTE: This version of the documentation tracks unstable development happening on A-Frame’s master branch. If you wish to try it out, grab the unstable build. Otherwise, head to the documentation for the current 1.6.0 version

The animation component lets us animate and tween values including:

• Component values (e.g., position, visible)
• Component property values (e.g., light.intensity)

We can also tween values directly for better performance versus going through .setAttribute, such as by animating values:

• On the object3D (e.g., object3D.position.y, object3D.rotation.z)
• Directly within a component (e.g., components.material.material.color, components.text.material.uniforms.opacity.value),

For example, translating a box:

<a-box position="-1 1.6 -5" animation="property: position; to: 1 8 -10; dur: 2000; easing: linear; loop: true" color="tomato"></a-box>

Or orbiting a sphere in a 5-meter radius:

<a-entity rotation="0 0 0" animation="property: rotation; to: 0 360 0; loop: true; dur: 10000">
        <a-sphere position="5 0 0" color="mediumseagreen"></a-sphere>
</a-entity>

Read more below for additional options and discovering how to properly animate different types of values.

API

Properties

Multiple Animations

The component’s base name is animation. We can attach multiple animations to one entity by name-spacing the component with double underscores (__):

<a-entity animation="property: rotation"
          animation__2="property: position"
          animation__color="property: material.color"></a-entity>

Easings

Easings define the accelerations and speed throughout the cycle of the animation.

Events

Members

Accessed as el.components.animation.<MEMBER>.

Controlling Animations using setAttribute

Like any A-Frame component, the animation component can be configured from JavaScript by calling setAttribute() on an element.

By default, the animation will begin playing immediately (autoplay is true by default).

However, care should be taken when using the interface in this way. If a finite (i.e. non-looping) animation is requested twice in a row, with identical parameters, the second animation will not play, and neither will it generate an animationcomplete event.

This is because A-Frame sees the second request as a duplicate request for configuration already applied to the element, and so the second request never reaches the animation component.

A better approach is to control the start of an animation using events (see next section)

• On initialization, configure all the animations that may be required on the object, with a custom event configured to start the animation.
• When you want to start a specific animation, do so by using emit() rather than setAttribute().

This gives more robust control of the animation (avoiding problems where you request the same animation twice in a row), and also reduces the overheads involved in setting up animation config, since it only needs to be done once.

Animating on Events

We can use the startEvents property to animate upon events:

<a-entity id="mouseCursor" cursor="rayOrigin: mouse"></a-entity>

<a-entity
  geometry="primitive: box"
  material="color: red"
  animation__mouseenter="property: components.material.material.color; type: color; to: blue; startEvents: mouseenter; dur: 500";
  animation__mouseleave="property: components.material.material.color; type: color; to: red; startEvents: mouseleave; dur: 500";>
</a-entity>

Remix the Animating on Events Glitch.

To start an animation by explicitly emitting an event, you can do the following:

el.emit(`startanim001`, null, false);

The third parameter of emit set to “false” parameter ensures the event won’t bubble up to parents, so that you can target the animation at just one particular element.

This assumes that an animation has already been configured to respond to that custom start event, for example like this:

el.setAttribute('animation__001', {'property': 'position',
                                 'to': {x: 1, y: 1, z: 1},                                 
                                 'startEvents': 'startanim001'});

(configuring startEvents on the animation automatically disables autoplay).

Animating Different Types of Values

We’ll go over different cases of animating different types of values.

Component Values

We can animate a single-property component value (e.g., property: visible, we’ll go over booleans in a bit) or animate a property of a multi-property component using a dot . as a separator (e.g., property: light.intensity, property: material.color).

If the property is a vec3, that is also supported (e.g., property: someComponent.vec3Value; to: 5 5 5).

However, animating component values this way is not the most optimal way as it will invoke .setAttribute on each frame of the animation. For an animation here or there, it won’t be a big deal, but we can save time and memory by animating values directly.

A special note to try not to animate values of the geometry component as that will recreate the geometry on each tick. Rather animate scale if we want to animate the size.

Boolean Values

We can “animate” boolean values where the to value will be applied at the end of the animation. Like property: visible; from: false; to: true; dur: 1.

Direct Values through object3D and components

The animation component supports animating values directly through object3D or components.

For example, we can animate values on object3D like property: object3D.position.z; to: 5 which will tween the entity’s object3D.position.z value directly without calling .setAttribute; it’s the most direct way and lets us animate a single axis at a time. Note, for object3D.rotation, degrees are used.

Or we can animate values by reaching into components. For example, rather than animating property: material.opacity which would call .setAttribute on each frame, we can animate the opacity value directly with property: components.material.material.opacity. We use a dot-delimited path to walk the object tree to find the value we want to animate, and the animation process under the hood reduces down to changing a number.

Direct Color Values

We can animate three.js color values directly, but we’ll need to specify type: color. So rather than animating property: material.color, we can do property: components.material.material.color; type: color.

A note on color values, we can specify color values using hex, color names, hsl, or rgb (e.g., from: red; to: #FFCCAA or from: rgb(100, 100, 100); to: hsl(213, 100%, 70%))..

Using anime.js Directly

anime is a popular and powerful animation engine. The component prefers to do just basic tweening and touches the surface of what anime can do (e.g., timelines, motion paths, progress, seeking). If we need more animation features, create a separate component that invokes anime.js directly. anime is accessible via AFRAME.ANIME.

Read through and explore the anime.js documentation and website.

See Also

• animation-timeline component