Skip to content

Commit af9db0c

Browse files
ngokevindmarcos
ngokevin
authored and
dmarcos
committed
animation component, removes a-animation (fixes #1927) (#3678)
1 parent 2c8defe commit af9db0c

File tree

48 files changed

+2034
-2832
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+2034
-2832
lines changed

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.DS_Store
22
.cache
3-
*.swp
3+
*.sw*
44
build
55
firefox/
66
tests/coverage/

‎docs/components/animation.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: Animation
3+
type: components
4+
layout: docs
5+
parent_section: components
6+
source_code: src/components/animation.js
7+
examples:
8+
- title: Generated Animations
9+
src: https://glitch.com/~aframe-shooting-stars
10+
---
11+
12+
[animationtimeline]: https://www.npmjs.com/package/aframe-animation-timeline-component
13+
14+
The animation component lets us animate and tween values including:
15+
16+
- Component values (e.g., `position`, `visible`)
17+
- Component property values (e.g., `light.intensity`)
18+
19+
We can also tween values directly for better performance versus going through
20+
`.setAttribute`, such as by animating values:
21+
22+
- On the `object3D` (e.g., `object3D.position.y`, `object3D.rotation.z`)
23+
- Directly within a component (e.g., `components.material.material.color`, `components.text.material.uniforms.opacity.value`),
24+
25+
For example, translating a box:
26+
27+
```html
28+
<a-box position="0 1.6 0" animation="property: position; to: 5 1.6 0; dur: 1500; easing: linear"></a-box>
29+
```
30+
31+
Or orbiting a sphere in a 5-meter radius:
32+
33+
```html
34+
<a-entity rotation="0 0 0" animation="property: rotation; to: 0 360 0; loop: true; dur: 10000">
35+
<a-entity position="5 0 0"></a-entity>
36+
</a-entity>
37+
```
38+
39+
Read more below for additional options and discovering how to properly animate
40+
different types of values.
41+
42+
<!--toc-->
43+
44+
## API
45+
46+
### Properties
47+
48+
| Property | Description | Default Value | Values |
49+
| -------- | ----------- | ------------- | ------ |
50+
| property | Property to animate. Can be a component name, a dot-delimited property of a component (e.g., `material.color`), or a plain attribute. | | |
51+
| 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 | |
52+
| 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 | |
53+
| to | Target value at end of animation. | null | |
54+
| type | Right now only supports `color` for tweening `isRawProperty` color XYZ/RGB vector values. | '' | |
55+
| delay | How long (milliseconds) to wait before starting. | 0 | |
56+
| dir | Which dir to go from `from` to `to`. | normal | alternate, reverse |
57+
| dur | How long (milliseconds) each cycle of the animation is. | 1000 | |
58+
| easing | Easing function of animation. To ease in, ease out, ease in and out. | easeInQuad | See [easings](#easings) |
59+
| elasticity | How much to bounce (higher is stronger). | 400 | |
60+
| loop | How many times the animation should repeat. If the value is `true`, the animation will repeat infinitely. | 0 | |
61+
| round | Whether to round values. | false | |
62+
| 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 | |
63+
| pauseEvents | Comma-separated list of events to listen to trigger pause. Can be resumed with `resumeEvents`. | null | |
64+
| resumeEvents | Comma-separated list of events to listen to trigger resume after pausing. | null | |
65+
| autoplay | Whether or not the animation should `autoplay`. Should be specified if the animation is defined for the [`animation-timeline` component][animationtimeline]. | null | |
66+
| enabled | If disabled, animation will stop and startEvents will not trigger animation start. | true |
67+
68+
### Multiple Animations
69+
70+
The component's base name is `animation`. We can attach multiple animations to
71+
one entity by name-spacing the component with double underscores (`__`):
72+
73+
```html
74+
<a-entity animation="property: rotation"
75+
animation__2="property: position"
76+
animation__color="property: material.color"></a-entity>
77+
```
78+
79+
### Easings
80+
81+
Easings define the accelerations and speed throughout the cycle of the
82+
animation.
83+
84+
| easeIn | easeOut | easeInOut | Others |
85+
|---------------|----------------|------------------|--------|
86+
| easeInQuad | easeOutQuad | easeInOutQuad | linear |
87+
| easeInCubic | easeOutCubic | easeInOutCubic | |
88+
| easeInQuart | easeOutQuart | easeInOutQuart | |
89+
| easeInQuint | easeOutQuint | easeInOutQuint | |
90+
| easeInSine | easeOutSine | easeInOutSine | |
91+
| easeInExpo | easeOutExpo | easeInOutExpo | |
92+
| easeInCirc | easeOutCirc | easeInOutCirc | |
93+
| easeInBack | easeOutBack | easeInOutBack | |
94+
| easeInElastic | easeOutElastic | easeInOutElastic | |
95+
96+
### Events
97+
98+
| Property | Description |
99+
| -------- | ----------- |
100+
| animationbegin | Animation began. Event detail contains `name` of animation. |
101+
| animationcomplete | Animation completed. Event detail contains `name` of animation. |
102+
103+
### Members
104+
105+
Accessed as `el.components.animation.<MEMBER>`.
106+
107+
| Member | Description |
108+
|-----------|----------------------------|
109+
| animation | anime.js object. |
110+
| config | Config passed to anime.js. |
111+
112+
## Animating Different Types of Values
113+
114+
We'll go over different cases of animating different types of values.
115+
116+
### Component Values
117+
118+
We can animate a single-property component value (e.g., `property: visible`,
119+
we'll go over booleans in a bit) or animate a property of a multi-property
120+
component using a dot `.` as a separator (e.g., `property: light.intensity`,
121+
`property: material.color`).
122+
123+
If the property is a `vec3`, that is also supported (e.g., `property:
124+
someComponent.vec3Value; to: 5 5 5`).
125+
126+
However, animating component values this way is not the most optimal way as it
127+
will invoke `.setAttribute` on each frame of the animation. For an animation
128+
here or there, it won't be a big deal, but we can save time and memory by
129+
animating values directly.
130+
131+
A special note to try not to animate values of the `geometry` component as that
132+
will recreate the geometry on each tick. Rather animate `scale` if we want to
133+
animate the size.
134+
135+
### Boolean Values
136+
137+
We can "animate" boolean values where the `to` value will be applied at the end
138+
of the animation. Like `property: visible; from: false; to: true; dur: 1`.
139+
140+
### Direct Values through `object3D` and `components`
141+
142+
The animation component supports animating values directly through `object3D`
143+
or `components`.
144+
145+
For example, we can animate values on `object3D` like `property:
146+
object3D.position.z; to: 5` which will tween the entity's `object3D.position.z`
147+
value directly without calling `.setAttribute`; it's the most direct way and
148+
lets us animate a single axis at a time. Note, for `object3D.rotation`, degrees
149+
are used.
150+
151+
Or we can animate values by reaching into `components`. For example, rather than
152+
animating `property: material.opacity` which would call `.setAttribute` on each
153+
frame, we can animate the opacity value directly with `property:
154+
components.material.material.opacity`. We use a dot-delimited path to walk the
155+
object tree to find the value we want to animate, and the animation process
156+
under the hood reduces down to changing a number.
157+
158+
#### Direct Color Values
159+
160+
We can animate three.js color values directly, but we'll need to specify `type:
161+
color`. So rather than animating `property: material.color`, we can do
162+
`property: components.material.material.color; type: color`.
163+
164+
A note on color values, we can specify color values using hex, color names,
165+
hsl, or rgb (e.g., `from: red; to: #FFCCAA` or `from: rgb(100, 100, 100); to:
166+
hsl(213, 100%, 70%)`)..
167+
168+
## Using anime.js Directly
169+
170+
anime is a popular and powerful animation engine. The component prefers to do
171+
just basic tweening and touches the surface of what anime can do (e.g.,
172+
timelines, motion paths, progress, seeking). If we need more animation
173+
features, create a separate component that invokes anime.js directly. anime is
174+
accessible via **`AFRAME.ANIME`**.
175+
176+
Read through and explore the [anime.js
177+
documentation](https://github.com/juliangarnier/anime) and
178+
[website](https://animejs.com).
179+
180+
## See Also
181+
182+
- [animation-timeline component][animationtimeline]

‎docs/components/cursor.md‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ AFRAME.registerComponent('cursor-listener', {
8787
| downEvents | Array of additional events on the entity to *listen* to for triggering `mousedown` (e.g., `triggerdown` for vive-controls). | [] |
8888
| fuse | Whether cursor is fuse-based. | false on desktop, true on mobile |
8989
| fuseTimeout | How long to wait (in milliseconds) before triggering a fuse-based click event. | 1500 |
90-
| rayOrigin | Where the intersection ray is cast from (i.e.,entity or mouse) | entity
90+
| rayOrigin | Where the intersection ray is cast from (i.e.,entity or mouse). `rayOrigin: mouse` is extremely useful for VR development on a mouse and keyboard. | entity
9191
| upEvents | Array of additional events on the entity to *listen* to for triggering `mouseup` (e.g., `trackpadup` for daydream-controls). | [] |
9292

9393
To further customize the cursor component, we configure the cursor's dependency
@@ -160,23 +160,21 @@ interactions is that it requires the user to turn their head a lot.
160160

161161
## Adding Visual Feedback
162162

163-
[animation]: ../core/animations.md
163+
[animation]: ./animation.md
164164

165165
To add visual feedback to the cursor to show when the cursor is clicking or
166-
fusing, we can use the [animation system][animation]. When the cursor
166+
fusing, we can use the [animation component][animation]. When the cursor
167167
intersects the entity, it will emit an event, and the animation system will
168168
pick up event with the `begin` attribute:
169169

170170
```html
171-
<a-entity cursor="fuse: true;"
172-
position="0 0 -3"
173-
geometry="primitive: ring"
174-
material="color: black; shader: flat">
175-
<a-animation begin="click" easing="ease-in" attribute="scale" dur="150"
176-
fill="forwards" from="0.1 0.1 0.1" to="1 1 1"></a-animation>
177-
<a-animation begin="fusing" easing="ease-in" attribute="scale" dur="1500"
178-
fill="backwards" from="1 1 1" to="0.1 0.1 0.1"></a-animation>
179-
</a-entity>
171+
<a-entity
172+
animation__click="property: scale; startEvents: click; easing: easeInCubic; dur: 150; from: 0.1 0.1 0.1; to: 1 1 1"
173+
animation__fusing="property: scale; startEvents: fusing; easing: easeInCubic; dur: 1500; from: 1 1 1; to: 0.1 0.1 0.1"
174+
cursor="fuse: true;"
175+
material="color: black; shader: flat"
176+
position="0 0 -3"
177+
geometry="primitive: ring"></a-entity>
180178
```
181179

182180
[cursor-codepen]: https://codepen.io/Absulit/pen/WEKjqm

‎docs/components/embedded.md‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ a-scene {
3232
</body>
3333
```
3434

35-
An example of an embedded scene:
35+
An inline example of an embedded scene:
3636

3737
<script src="https://aframe.io/releases/0.8.2/aframe.min.js"></script>
3838

@@ -44,14 +44,11 @@ An example of an embedded scene:
4444
</style>
4545

4646
<div id="myEmbeddedScene">
47-
<a-scene embedded>
48-
<a-entity position="0 0 3.8"><a-camera></a-camera></a-entity>
49-
<a-sphere position="0 1.25 -1" radius="1.25" color="#EF2D5E"></a-sphere>
50-
<a-box position="-1 0.5 1" rotation="0 45 0" width="1" height="1" depth="1" color="#4CC3D9">
51-
<a-animation attribute="rotation" dur="10000" fill="forwards" to="0 360 0" repeat="indefinite"></a-animation>
52-
</a-box>
53-
<a-cylinder position="1 0.75 1" radius="0.5" height="1.5" color="#FFC65D"></a-cylinder>
54-
<a-plane rotation="-90 0 0" width="4" height="4" color="#7BC8A4"></a-plane>
47+
<a-scene background="color: #ECECEC" embedded>
48+
<a-box position="-1 0.5 -3" rotation="0 45 0" color="#4CC3D9" shadow></a-box>
49+
<a-sphere position="0 1.25 -5" radius="1.25" color="#EF2D5E" shadow></a-sphere>
50+
<a-cylinder position="1 0.75 -3" radius="0.5" height="1.5" color="#FFC65D" shadow></a-cylinder>
51+
<a-plane position="0 0 -4" rotation="-90 0 0" width="4" height="4" color="#7BC8A4" shadow></a-plane>
5552
</a-scene>
5653
</div>
5754

‎docs/components/material.md‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -625,14 +625,12 @@ We then apply the component to the entity with the custom shader:
625625
626626
```html
627627
<a-scene>
628-
<a-sphere material="shader:displacement-offset"
629-
myoffset-updater
630-
scale="1 1 1"
631-
radius="0.2"
632-
position="0 1.5 -2"
633-
segments-height="128"
634-
segments-width="128">
635-
<a-animation attribute="scale" direction="alternate-reverse" dur="5000" from="1 1 1" to="4 4 4" repeat="indefinite"></a-animation>
628+
<a-sphere
629+
animation="property: scale; dir: alternate; dur: 5000; loop: true; to: 4 4 4"
630+
geometry="radius: 0.2"
631+
material="shader: displacement-offset"
632+
myoffset-updater
633+
position="0 1.5 -2">
636634
</a-sphere>
637635
<a-box color="#CCC" width="3" depth="3" height="0.1" position="0 0 -2"></a-box>
638636
</a-scene>

0 commit comments

Comments
 (0)