forked from aframevr/aframe
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
animation component, removes a-animation (fixes aframevr#1927)
- Loading branch information
Showing
42 changed files
with
1,967 additions
and
2,765 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| .DS_Store | ||
| .cache | ||
| *.swp | ||
| *.sw* | ||
| build | ||
| firefox/ | ||
| tests/coverage/ | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,180 @@ | ||
| --- | ||
| title: Animation | ||
| type: components | ||
| layout: docs | ||
| parent_section: components | ||
| source_code: src/components/animation.js | ||
| examples: | ||
| - title: Generated Animations | ||
| src: https://glitch.com/~aframe-shooting-stars | ||
| --- | ||
|
|
||
| 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: | ||
|
|
||
| ```html | ||
| <a-box position="0 1.6 0" animation="property: position; to: 5 1.6 0; dur: 1500; easing: linear"></a-box> | ||
| ``` | ||
|
|
||
| Or orbiting a sphere in a 5-meter radius: | ||
|
|
||
| ```html | ||
| <a-entity rotation="0 0 0" animation="property: rotation; to: 0 360 0; loop: true; dur: 10000"> | ||
| <a-entity position="5 0 0"></a-entity> | ||
| </a-entity> | ||
| ``` | ||
|
|
||
| Read more below for additional options and discovering how to properly animate | ||
| different types of values. | ||
|
|
||
| <!--toc--> | ||
|
|
||
| ## API | ||
|
|
||
| ### Properties | ||
|
|
||
| | Property | Description | Default Value | Values | | ||
| | -------- | ----------- | ------------- | ------ | | ||
| | property | Property to animate. Can be a component name, a dot-delimited property of a component (e.g., `material.color`), or a plain attribute. | | | | ||
| | isRawProperty | Flag to animate an arbitrary object property outside of A-Frame components for better performance. If set to true, for example, we can set `property` to like `components.material.material.opacity`. If `property` starts with `components` or `object3D`, this will be inferred to `true`. | false | | | ||
| | from | Initial value at start of animation. If not specified, the current property value of the entity will be used (will be sampled on each animation start). It is best to specify a `from` value when possible for stability. | null | | | ||
| | to | Target value at end of animation. | null | | | ||
| | type | Right now only supports `color` for tweening `isRawProperty` color XYZ/RGB vector values. | '' | | | ||
| | delay | How long (milliseconds) to wait before starting. | 0 | | | ||
| | dir | Which dir to go from `from` to `to`. | normal | alternate, reverse | | ||
| | dur | How long (milliseconds) each cycle of the animation is. | 1000 | | | ||
| | easing | Easing function of animation. To ease in, ease out, ease in and out. | easeInQuad | See [easings](#easings) | | ||
| | elasticity | How much to bounce (higher is stronger). | 400 | | | ||
| | loop | How many times the animation should repeat. If the value is `true`, the animation will repeat infinitely. | 0 | | | ||
| | round | Whether to round values. | false | | | ||
| | startEvents | Comma-separated list of events to listen to trigger a restart and play. Animation will not autoplay if specified. `startEvents` will **restart** the animation, use `pauseEvents` to resume it. If there are other animation components on the entity animating the same property, those animations will be automatically paused to not conflict. | null | | | ||
| | pauseEvents | Comma-separated list of events to listen to trigger pause. Can be resumed with `resumeEvents`. | null | | | ||
| | resumeEvents | Comma-separated list of events to listen to trigger resume after pausing. | null | | | ||
| | autoplay | Whether or not the animation should `autoplay`. Should be specified if the animation is defined for the [`animation-timeline` component][animationtimeline]. | null | | | ||
| | enabled | If disabled, animation will stop and startEvents will not trigger animation start. | true | | ||
|
|
||
| ### 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 (`__`): | ||
|
|
||
| ```html | ||
| <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. | ||
|
|
||
| | easeIn | easeOut | easeInOut | Others | | ||
| |---------------|----------------|------------------|--------| | ||
| | easeInQuad | easeOutQuad | easeInOutQuad | linear | | ||
| | easeInCubic | easeOutCubic | easeInOutCubic | | | ||
| | easeInQuart | easeOutQuart | easeInOutQuart | | | ||
| | easeInQuint | easeOutQuint | easeInOutQuint | | | ||
| | easeInSine | easeOutSine | easeInOutSine | | | ||
| | easeInExpo | easeOutExpo | easeInOutExpo | | | ||
| | easeInCirc | easeOutCirc | easeInOutCirc | | | ||
| | easeInBack | easeOutBack | easeInOutBack | | | ||
| | easeInElastic | easeOutElastic | easeInOutElastic | | | ||
|
|
||
| ### Events | ||
|
|
||
| | Property | Description | | ||
| | -------- | ----------- | | ||
| | animationbegin | Animation began. Event detail contains `name` of animation. | | ||
| | animationcomplete | Animation completed. Event detail contains `name` of animation. | | ||
|
|
||
| ### Members | ||
|
|
||
| Accessed as `el.components.animation.<MEMBER>`. | ||
|
|
||
| | Member | Description | | ||
| |-----------|----------------------------| | ||
| | animation | anime.js object. | | ||
| | config | Config passed to anime.js. | | ||
|
|
||
| ## 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](https://github.com/juliangarnier/anime) and | ||
| [website](https://animejs.com). | ||
|
|
||
| ## See Also | ||
|
|
||
| - [animation-timeline component](https://www.npmjs.com/package/aframe-animation-timeline-component) |
Oops, something went wrong.