Animation basics

The die that teleports

Dice Duel, as you have built it so far, works perfectly. Tap the die, a number appears. Tap again, a different number appears.

It also feels like a spreadsheet.

Nothing about the game changes when you add the roll animation. The random number is the same random number. What changes is that a player believes the die was thrown — and that belief is worth more to a game than any feature you could add in the same forty lines.

This is the last lesson of Part 3, and it is the one that turns a screen into an app.

Animation is declarative too

Every animation system you may have seen elsewhere works like an instruction: move this thing from 0 to 360 over 640 milliseconds. You start it, you stop it, you keep track of whether it is running.

Compose does not work that way, for the same reason it does not work that way for anything else. You describe where the value should be, and it takes care of the journey:

1val angle by animateFloatAsState(
2    targetValue = if (rolling) 360f else 0f,
3    label = "angle"
4)

animateFloatAsState hands you a Float that is always slightly out of date. Change the target and the number does not jump — it starts sliding, arriving a few hundred milliseconds later. Read it in your layout and the screen follows it all the way.

Here is what is actually happening, and it is worth being precise about, because it explains several bugs at once:

1. rolling changes. Your composable recomposes, as normal.
2. animateFloatAsState sees a new targetValue and starts an animation.
3. On every frame — sixty times a second on most phones — it writes a new value into its state box.
4. Every write triggers a recomposition of whatever read that box.
5. When the value reaches the target, the writes stop and everything goes quiet.

So an animation is just state changing very fast, using the machinery from Lesson 3.5. There is no separate animation system bolted on the side.

1val angle by animateFloatAsState(...)   // a Float
2val angle = animateFloatAsState(...)    // a State

Choosing how it moves: the animation spec

The second parameter decides the character of the movement. There are two you will use constantly.

1animationSpec = tween(
2    durationMillis = 640,
3    easing = FastOutSlowInEasing
4)

tween is a duration: get there in exactly this many milliseconds. Predictable, and right for anything with a known length — a card sliding in, a bar filling up.

easing is the shape of the speed. Nothing in the physical world starts and stops instantly, so a straight-line animation reads as mechanical:

1animationSpec = spring(
2    dampingRatio = Spring.DampingRatioMediumBouncy,
3    stiffness = Spring.StiffnessLow
4)

spring has no duration at all. It is physics: a weight on a spring, pulled towards the target. stiffness is how hard it pulls; dampingRatio is how much it wobbles before settling — DampingRatioNoBouncy stops dead, DampingRatioHighBouncy overshoots several times.

Springs feel alive, and they have one genuine practical advantage: interrupt one halfway and it carries its current speed into the new animation, so a fast-tapping user never sees a jerk. A tween interrupted mid-flight restarts from wherever it happened to be.

Use spring for things the user is directly manipulating. Use tween when the timing matters.

There is a third, keyframes, for animations with named waypoints — "70% of the way by 200ms, then ease out". You will rarely need it.

Where to apply it: graphicsLayer

You could animate a number and feed it into Modifier.padding or Modifier.size. It works, and it is the expensive way to do it: changing a size forces Compose to measure and lay out the screen again, every frame, including everything around it.

Modifier.graphicsLayer changes only how the pixels are drawn — position, rotation, scale, transparency — without disturbing the layout at all. Its neighbours never find out. That is the difference between a smooth animation and a stuttering one on a cheap phone.

1Modifier.graphicsLayer {
2    rotationZ = spin
3    scaleX = lift
4    scaleY = lift
5}

The properties you will use: rotationZ (degrees, clockwise), scaleX / scaleY, translationX / translationY (pixels), and alpha (0 invisible, 1 solid).

Rule of thumb: if you can express the animation as moving, turning, scaling or fading, use graphicsLayer. Only animate a size or a padding when the layout genuinely has to change, and then reach for Modifier.animateContentSize(), which does it properly.

The real roll

This is Dice Duel's animation, exactly as it ships.

1var rollId by remember { mutableStateOf(0) }
2var tilt by remember { mutableStateOf(0f) }
3var rolling by remember { mutableStateOf(false) }
4
5val spin by animateFloatAsState(
6    targetValue = rollId * 360f + tilt,
7    animationSpec = tween(
8        durationMillis = 640,
9        easing = FastOutSlowInEasing
10    ),
11    label = "spin"
12)
13
14val lift by animateFloatAsState(
15    targetValue = if (rolling) 1.16f else 1f,
16    animationSpec = tween(durationMillis = 280),
17    label = "lift"
18)
19
20LaunchedEffect(rollId) {
21    if (rollId == 0) return@LaunchedEffect
22    repeat(9) {
23        die = Random.nextInt(1, 7)
24        delay(60)
25    }
26    die = Random.nextInt(1, 7)
27    rolling = false
28}
29
30fun roll() {
31    if (rolling) return
32    rolling = true
33    tilt = Random.nextInt(-8, 9).toFloat()
34    rollId++
35}
36
37DieFace(
38    value = die,
39    size = 172.dp,
40    modifier = Modifier.graphicsLayer {
41        rotationZ = spin
42        scaleX = lift
43        scaleY = lift
44    },
45    onRoll = { roll() }
46)

The last part of the trick is not an animation at all. That LaunchedEffect(rollId) runs a coroutine every time rollId changes: nine random faces, 60 milliseconds apart, then the real one. It is Lesson 1.19's delay doing the work.

Be clear about the division of labour, because it is easy to blur:

• The spin and the lift are animations — a continuous value moving smoothly to a target.
• The flickering faces are not. A die face is 1 to 6; there is nothing in between to animate. That is a coroutine changing state nine times.

Use an animation when a value has a meaningful in-between. Use a coroutine when it does not.

The rest of the toolbox

You now know the pattern, so the rest is naming.

Other values, same function. animateColorAsState for a colour fading from one to another, animateDpAsState for a size or offset in dp. Identical parameters, identical behaviour.

1val panel by animateColorAsState(
2    targetValue = if (active) {
3        colors.primary
4    } else {
5        colors.surfaceVariant
6    },
7    label = "panel"
8)

Appearing and disappearing. AnimatedVisibility animates a composable in and out instead of it popping:

1AnimatedVisibility(visible = winner != 0) {
2    WinBanner()
3}

By default it fades and expands on the way in, and shrinks and fades on the way out. Pass enter = slideInVertically() and exit = fadeOut() to choose.

Changing size smoothly. Modifier.animateContentSize() on a container makes it grow and shrink smoothly when its contents change — the standard way to build an expanding card.

Swapping one thing for another. Crossfade fades between two composables based on a value: Crossfade(targetState = screen) { s -> when (s) { ... } }.

Full control. Animatable is the low-level version, driven from a coroutine rather than from a target value. You need it when you want to await an animation finishing, or to interrupt one deliberately. animate*AsState is built on top of it, and covers the vast majority of real work.

Something that never stops. rememberInfiniteTransition() is for loading spinners and pulsing dots — an infinite transition that runs until the composable leaves the screen.