# Sceneform animation

Sceneform lets you import models with animation. You can use Sceneform APIs to
play back and control the animation, and attach nodes to a model's skeleton.

For instance, the Sceneform [**Animation**](https://github.com/google-ar/sceneform-android-sdk/tree/v1.15.0/samples/animation)
sample includes files used to build models of Andy the android and a baseball
hat. The Andy model contains animation data, while the baseball hat is a
non-animated model. When you run the sample, Andy breakdances and waves his arms
while the hat remains fixed to his head using a node.

## Sceneform model animation vs Android property animation

It's important to differentiate between *model animation* in Sceneform versus
*property animation* in Android.

- Model animations are created ahead of time by artists using modeling and
  animation software. They contain [skeletal animation data](https://developers.google.com/sceneform/develop/animation#model-concepts).
  These animations must be exported as
  `*.fbx` files, then imported into a `*.sfb` file to be used in Sceneform.

- [Property animation](https://developer.android.com/guide/topics/graphics/prop-animation)
  is a fundamental Android concept and is not specific to Sceneform. This kind
  of animation can change any mutable value on a Java object that has a getter
  and a setter. The animated values can be set dynamically, but cannot be
  packaged into an `*.sfb` file.

  Both property and model animation support
  [Android's Animator API](https://developer.android.com/reference/android/animation/Animator)
  . They both support
  [listeners](https://developer.android.com/guide/topics/graphics/prop-animation#listeners),
  playback control (start/stop/end/pause/cancel), duration, and start delay.

  Only limited support for
  [`TimeInterpolators`](https://developer.android.com/reference/android/animation/TimeInterpolator)
  playback is provided in the model animations. Reverse playback is not
  supported in model animations.
- To see Sceneform animation modeling in action, review the
  [**Animation**](https://github.com/google-ar/sceneform-android-sdk/tree/v1.15.0/samples/animation)
  sample.

- To see property animation using Sceneform in action, review the
  [**Solar System**](https://github.com/google-ar/sceneform-android-sdk/tree/v1.15.0/samples/solarsystem)
  sample.

## Model animation concepts

Before you start working with animated models, it's a good idea to understand specific
concepts relating to [*skeletal animation*](https://en.wikipedia.org/wiki/Skeletal_animation),
as well as related restrictions and features that apply to Sceneform.

- **Bones.** An animated model contains *bones* that are connected together,
  forming parent-child relationships in a hierarchy. Animation alters the
  position and orientation of bones during playback.

  In the same way that moving a parent `Node` in Sceneform causes all child
  `Node`s to also move, moving a parent bone in Sceneform moves the children.
  Bones are movable by animation or accessed as a node via the [`SkeletonNode`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/SkeletonNode)
  class. When bones are accessed as a `Node`, the new positions are
  overwritten every frame by animation if one is playing.
- **Skeleton.** The *skeleton* comprises all of the bones together, forming a
  hierarchy of parent-child relationships.

  For example, a model of a human arm might contain bones such as
  "left shoulder", "left upper arm", "left elbow", and "left forearm" and so
  on. Starting from the "left shoulder" as the parent of this hierarchy,
  "left upper arm" would be assigned as a child. The children of "left upper
  arm" might be the "left elbow" and lower bones. When the shoulder bone is
  rotated, the upper arm, forearm, elbow and any bones below would move in
  tandem.

  Sceneform doesn't have an API for changing the parent-child relationships
  between bones in the skeleton. This must be done ahead of time in an
  external modeling and animation package.

  Even models depicting inorganic objects can utilize skeletons to facilitate
  realism. For example, a model of a couch could have bones and a skeleton.
- **Skin.** The *skin* is a weight applied to the drawn surface mesh of the
  model. The position and shape of the skin mesh is calculated from the nearby
  bones. This bone to skin connection maps to how the model deforms, providing
  for more realistic movement.

  The skin must be prepared ahead of time using a modeling and animation
  package. Sceneform can alter the material of the skin mesh to change a
  model's appearance.