path: root/docs/animation.org

#+TITLE: Animation

Downstroke animates sprites by swapping an entity's =#:tile-id= on a
timed cycle. You declare a table of named animations on the entity
under =#:animations=, pick one by name with =#:anim-name=, and the
engine's last pipeline stage — =apply-animation= — advances the frame
counter every tick.

There is no interpolation, no blending, no tween layer: each frame is
a whole tile from the tileset, selected by index, held for a fixed
number of ticks. The model is small enough to describe in one line of
data and small enough to disable per-entity when you want to drive
=#:tile-id= by hand.

This file assumes you already know how entities are shaped (see
[[file:entities.org][entities.org]]) and how the update pipeline runs
(see [[file:physics.org][physics.org]]).

* The minimum you need

An animated entity needs three things:

1. A =#:tile-id= (so there is something to render before the first
   tick).
2. A non-empty =#:animations= list.
3. A =#:anim-name= that names one of those animations.

The simplest hand-built entity looks like this:

#+begin_src scheme
(list (cons #:type 'player)
      (cons #:x 80) (cons #:y 80)
      (cons #:width 16) (cons #:height 16)
      (cons #:tile-id 28)
      (cons #:anim-name 'walk)
      (cons #:anim-frame 0)
      (cons #:anim-tick 0)
      (cons #:animations
            (list (list (cons #:name 'walk)
                        (cons #:frames '(28 29))
                        (cons #:duration 10)))))
#+end_src

In practice you never write this by hand. You declare the animation
in a prefab data file and let =load-prefabs= + =instantiate-prefab=
build the alist for you:

#+begin_src scheme
;; demo/assets/animation-prefabs.scm
((mixins)
 (prefabs
  (hero animated
        #:type hero #:anim-name walk
        #:animations ((#:name walk #:frames (28 29) #:duration 10)))))
#+end_src

Two things are happening here that are not obvious:

- The =animated= mixin (from =engine-mixins=) supplies the
  =#:anim-frame 0=, =#:anim-tick 0=, and =#:tile-id 0= defaults so you
  don't have to.
- The prefab loader deep-converts the plist-shaped =#:animations=
  value into a list of alists (see
  [[file:entities.org][entities.org]] for why prefab data is written
  as plists but entities are alists). =#:animations= is one of the
  keys in =+nested-plist-list-keys+= that gets this treatment.

Once the prefab is in a scene, the engine does the rest — you don't
need to call anything per frame just to make the animation play.

* Core concepts

** Animation data shape

An animation is an alist with three keys:

| Key          | Required | Meaning                                           |
|--------------+----------+---------------------------------------------------|
| =#:name=     | yes      | Symbol used to select this animation.             |
| =#:frames=   | yes      | List of frames (see below).                       |
| =#:duration= | no       | Default ticks-per-frame. Used when a frame        |
|              |          | does not carry its own duration. Defaults to 10.  |

=#:frames= can take two forms, and you can mix them inside one
animation only if you're careful about what each element means.

*Simple form* — a list of bare tile ids. Each frame holds for the
animation's =#:duration= ticks (or 10 if no duration is given):

#+begin_src scheme
(#:name attack #:frames (28 29) #:duration 10)
#+end_src

*Timed form* — a list of =(tile-id duration-ticks)= pairs. Each frame
carries its own duration; the animation's top-level =#:duration= is
ignored for that frame:

#+begin_src scheme
(#:name walk #:frames ((28 10) (29 1000)))
#+end_src

In the timed form above, tile 28 shows for 10 ticks and tile 29 shows
for 1000 ticks — a deliberately uneven cycle useful for things like
blink-idle animations.

The =#:animations= entity key holds a *list* of these animation
records, one per named animation:

#+begin_src scheme
#:animations ((#:name idle #:frames (10))
              (#:name walk #:frames (28 29) #:duration 10)
              (#:name jump #:frames (30)))
#+end_src

For a real working example of both forms side by side, see the
=timed-frames= and =std-frames= prefabs in
=demo/assets/animation-prefabs.scm=.

** The apply-animation pipeline step

=apply-animation= is the *last* stage of =default-engine-update=,
after physics, ground detection, entity collisions, and group
sync. You can see the wiring in =engine.scm=:

#+begin_src scheme
(scene-map-entities _ (cut apply-animation <> <> dt))
#+end_src

It is defined with =define-pipeline= under the pipeline name
=animation=:

#+begin_src scheme
(define-pipeline (apply-animation animation) (scene entity dt)
  guard: (entity-ref entity #:animations #f)
  ...)
#+end_src

Two things fall out of this definition:

1. *The guard.* If an entity has no =#:animations= value, the
   pipeline returns the entity unchanged. You do not have to opt out
   of animation for non-animated entities — not declaring the key is
   the opt-out.
2. *Skip support.* Because the step is registered under the pipeline
   name =animation=, any entity with =#:skip-pipelines= containing
   =animation= is also returned unchanged. Same mechanism as the
   physics skips described in [[file:physics.org][physics.org]].

When the step does run, =animate-entity= looks up the current
animation by =#:anim-name= in the entity's =#:animations= list, and
=advance-animation= does the actual work:

- Increment =#:anim-tick= by 1.
- If tick exceeds the current frame's duration, advance
  =#:anim-frame= (modulo the number of frames), reset =#:anim-tick=
  to 0, and write the new frame's =#:tile-id= onto the entity.
- Otherwise, just write the current frame's =#:tile-id= and the
  incremented tick.

The renderer reads =#:tile-id= directly — so as long as the pipeline
ran, what ends up on screen is always the current frame's tile.

Running the =animated= pipeline after physics means your visual state
reflects the entity's *post-physics* position and flags for the
frame. If you want to swap animations based on state (e.g. walking vs
jumping), your user =update:= hook — which runs after physics too —
is the right place.

** Switching animations

You change what an entity is playing by setting =#:anim-name=. The
helper for this is =set-animation=:

#+begin_src scheme
(set-animation entity 'walk)
#+end_src

=set-animation= has one important subtlety: *if the requested name
matches the entity's current =#:anim-name=, it is a no-op*. The
entity is returned unchanged — tick and frame counters keep their
values. This is what you want almost all the time: calling
=(set-animation entity 'walk)= every frame while the player is
walking should *not* restart the walk cycle on frame 0 each tick.

If the name is different, =set-animation= resets both =#:anim-frame=
and =#:anim-tick= to 0 so the new animation plays from its first
frame.

The typical usage pattern is in your =update:= hook, branching on
input or physics state:

#+begin_src scheme
update: (lambda (game dt)
  (let* ((scene  (game-scene game))
         (input  (game-input game))
         (p0     (car (scene-entities scene)))
         (anim   (cond ((not (entity-ref p0 #:on-ground? #f)) 'jump)
                       ((input-held? input 'left)             'walk)
                       ((input-held? input 'right)            'walk)
                       (else                                  'idle)))
         (p1     (set-animation p0 anim)))
    (game-scene-set! game (update-scene scene entities: (list p1)))))
#+end_src

Because =set-animation= returns a fresh entity alist (it calls
=entity-set= three times internally), the result must be written
back into the scene. See [[file:entities.org][entities.org]] for the
immutable-update convention.

** Interaction with the =animated= mixin

=engine-mixins= in =prefabs.scm= includes a convenience mixin named
=animated=:

#+begin_src scheme
(animated #:anim-name idle
          #:anim-frame 0
          #:anim-tick 0
          #:tile-id 0
          #:animations #t)
#+end_src

Listing =animated= in a prefab gets you all the bookkeeping keys for
free. You almost always want this — it saves repeating
=#:anim-frame 0 #:anim-tick 0= on every animated prefab.

Two of these defaults are booby-traps:

1. *=#:animations #t=* — a placeholder. The pipeline guard only
   checks that the value is truthy, so =#t= is enough to make the
   step run; but the =#t= itself is obviously not a valid animation
   list. You must override =#:animations= with a real list on any
   prefab that uses =animated=. If you forget, =animation-by-name=
   will fail (it calls =filter= on a non-list) the first time the
   step runs.
2. *=#:anim-name idle=* — also a default. The pipeline will then look
   up an animation named =idle= in your =#:animations= list. If you
   don't define one, =animation-by-name= returns =#f=,
   =animate-entity= returns the entity unchanged, and *=#:tile-id=
   is never written* by the pipeline. Your entity will render with
   whatever static =#:tile-id= it happens to have — which, since the
   mixin sets =#:tile-id 0=, is usually tile 0 (a blank or unexpected
   tile). The symptom is "my sprite is the wrong tile and never
   animates" with no error.

The animation demo's prefabs show both ways to avoid this. Neither
defines an =idle= animation; both override =#:anim-name= to match
the animation they do define:

#+begin_src scheme
(timed-frames animated #:type timed-frames #:anim-name walk
              #:animations ((#:name walk #:frames ((28 10) (29 1000)))))
(std-frames   animated #:type std-frames   #:anim-name attack
              #:animations ((#:name attack #:frames (28 29) #:duration 10)))
#+end_src

The rule is simple: either define an =idle= animation, or override
=#:anim-name= to a name you actually defined.

* Common patterns

** Declaring walk/idle/jump in a prefab

The usual player or enemy prefab declares all the animations it
might switch between in one =#:animations= list:

#+begin_src scheme
(player animated physics-body
        #:type player
        #:width 16 #:height 16
        #:tile-id 28
        #:anim-name idle
        #:animations ((#:name idle  #:frames (28))
                      (#:name walk  #:frames (28 29) #:duration 8)
                      (#:name jump  #:frames (30))))
#+end_src

Note that this prefab *does* define an =idle= animation, so the
=animated= mixin's default =#:anim-name idle= works as-is — no
override needed. If the player is standing still and =update:= never
calls =set-animation=, the engine will happily play the single-frame
=idle= cycle forever.

A single-frame animation (like =jump= above) is the idiomatic way to
hold a static pose: the cycle advances, the modulo wraps back to
frame 0 every tick, and =#:tile-id= stays pinned to the one tile.

** Switching animation based on input

Put the decision in your =update:= hook, after you've read input
state but before you hand the entity back to the scene:

#+begin_src scheme
(define (choose-anim entity input)
  (cond ((not (entity-ref entity #:on-ground? #f)) 'jump)
        ((or (input-held? input 'left)
             (input-held? input 'right))          'walk)
        (else                                     'idle)))

update: (lambda (game dt)
  (let* ((scene  (game-scene game))
         (input  (game-input game))
         (p0     (car (scene-entities scene)))
         (p1     (set-animation p0 (choose-anim p0 input))))
    (game-scene-set! game (update-scene scene entities: (list p1)))))
#+end_src

Two details worth noticing:

- =set-animation= is safe to call every frame with the same name; it
  won't reset the cycle.
- =apply-animation= runs as part of =default-engine-update=, which
  runs *before* your user =update:= hook. An =#:anim-name= change you
  make in =update:= takes effect on the next frame's
  =apply-animation= call, not this one — a one-frame latency that is
  imperceptible in practice.

** Per-frame durations for non-uniform timing

Use the =(tile-id duration)= frame form when you want a cycle where
one frame lingers and another flashes past. The canonical example
(from =demo/assets/animation-prefabs.scm=) is a blink-heavy idle:

#+begin_src scheme
(#:name idle #:frames ((28 10) (29 1000)))
#+end_src

Tile 28 shows for 10 ticks (a quick flash), then tile 29 holds for
1000 ticks (a long eye-open pose), then the cycle repeats. You can
mix this with the simple form across different animations in the
same entity — it's the frame shape that matters, not the animation.

Per-frame durations override any top-level =#:duration= on the
animation; in fact the top-level =#:duration= is only consulted when
=advance-animation= falls back to the default of 10 (see
=frame->duration= in =animation.scm=).

** Disabling animation on an entity without touching =#:animations=

If you want to freeze an animated entity on its current frame — for
example, pausing an enemy during a cutscene — the cheapest way is
to list =animation= in its =#:skip-pipelines=:

#+begin_src scheme
(entity-set entity #:skip-pipelines '(animation))
#+end_src

This leaves =#:animations=, =#:anim-name=, =#:anim-frame=, and
=#:anim-tick= untouched. When you remove =animation= from
=#:skip-pipelines= later, the cycle resumes exactly where it left
off. Contrast with =(entity-set entity #:animations #f)=, which
strips the animation data entirely and would require you to rebuild
it to resume.

You can combine =animation= with any of the physics pipeline names
in the same skip list — they all share one =#:skip-pipelines= key.
See [[file:physics.org][physics.org]] for the full list of step
names.

* See also

- [[file:guide.org][guide.org]] — the minimal-game walkthrough.
- [[file:entities.org][entities.org]] — entity alists, the prefab
  system, and how =#:animations= is deep-converted from plist data.
- [[file:physics.org][physics.org]] — the rest of the update
  pipeline and the =#:skip-pipelines= mechanism.
- [[file:tweens.org][tweens.org]] — when you want interpolation
  rather than discrete frame-swapping.
- [[file:../demo/animation.scm][Animation]] (=bin/demo-animation=) — prefab data in [[file:../demo/assets/animation-prefabs.scm][demo/assets/animation-prefabs.scm]].