#+title: Tweens
#+author: Downstroke Contributors

* Overview

The =downstroke-tween= module interpolates **numeric** entity properties over wall-clock time. It is **decoupled** from the engine: you create tween values, call =tween-step= each frame from your =update:= hook, and store the returned entity back into the scene.

Durations and delays are in **milliseconds**, matching the =dt= argument to =update:=.

* Import

#+begin_src scheme
(import downstroke-tween)
#+end_src

* Core API

** ~make-tween~

#+begin_src scheme
(make-tween entity #!key props duration (delay 0) ease
            (on-complete #f) (repeat 0) (yoyo? #f))
#+end_src

| Keyword | Meaning |
|---------+---------|
| ~props~ | Alist =((#:x . 200) (#:y . 40))= — keyword keys, numeric targets |
| ~duration~ | Positive integer, milliseconds of interpolation (after ~delay~) |
| ~delay~ | Non-negative integer ms before interpolation starts (first cycle only) |
| ~ease~ | Easing symbol (see table below) or ~(lambda (t) ...)= with ~t~ in $[0,1]$ |
| ~on-complete~ | Optional ~(lambda (entity) ...)=, called **once** when the tween fully ends (not called with ~repeat: -1~) |
| ~repeat~ | ~0~ = play once (default), ~N~ = replay N additional times, ~-1~ = loop forever |
| ~yoyo?~ | ~#f~ (default) = replay same direction, ~#t~ = reverse direction each cycle |

Start values are captured from ~entity~ at construction time. While the tween runs, intermediate values may be **inexact** (flonums) even if starts and ends are integers.

*** Repeat and yoyo

~repeat:~ controls how many extra times the tween replays after the initial play. ~yoyo?: #t~ swaps start and end values on each cycle, creating a ping-pong effect.

| ~repeat~ | ~yoyo?~ | Behavior |
|------+-------+----------|
| ~0~ | either | Play once and finish (default) |
| ~1~ | ~#f~ | Play forward twice, then finish |
| ~1~ | ~#t~ | Play forward, then backward, then finish |
| ~-1~ | ~#f~ | Play forward forever |
| ~-1~ | ~#t~ | Ping-pong forever |

~delay:~ only applies before the first cycle. ~on-complete~ fires once when the last repeat finishes; it never fires with ~repeat: -1~. Overflow time from a completed cycle carries into the next cycle for smooth transitions.

** ~tween-step~

#+begin_src scheme
(tween-step tween entity dt)
#+end_src

Returns ~(values new-tween new-entity)~. Advance time by ~dt~ (ms). Before ~delay~ elapses, ~entity~ is unchanged. After completion, further steps return the same values (idempotent). When the tween completes, ~on-complete~ runs with the **final** entity (targets applied), then the callback slot is cleared. With ~repeat:~ / ~yoyo?:~, the tween automatically resets for the next cycle.

** ~tween-finished?~ / ~tween-active?~

Predicates on the tween struct.

** ~step-tweens~ (pipeline step)

#+begin_src scheme
(step-tweens entity dt)
#+end_src

Auto-advances ~#:tween~ on an entity. If the entity has no ~#:tween~ key, returns the entity unchanged. When the tween finishes (no more repeats), ~#:tween~ is removed from the entity. Respects ~#:skip-pipelines~: skipped when ~'tweens~ is in the list.

This is the recommended way to run tweens in most games. Attach a tween to an entity and include ~step-tweens~ in your per-entity pipeline:

#+begin_src scheme
(scene-update-entities scene
  (lambda (e) (step-tweens e dt)))
#+end_src

** Entity key: ~#:tween~

Attach a tween directly to an entity for automatic advancement by ~step-tweens~:

#+begin_src scheme
(list #:type 'platform
      #:x 100 #:y 300 #:width 48 #:height 16
      #:solid? #t #:immovable? #t #:gravity? #f
      #:tween (make-tween (list #:x 100)
                props: '((#:x . 300))
                duration: 3000 ease: 'sine-in-out
                repeat: -1 yoyo?: #t))
#+end_src

The platform ping-pongs between x=100 and x=300 forever. No manual tween management needed.

* Easing

Each ease maps normalized time ~t ∈ [0,1]~ to an interpolation factor (usually in ~[0,1]~; ~back-out~ may exceed ~1~ briefly).

| Symbol | Procedure |
|--------|-----------|
| ~linear~ | ~ease-linear~ |
| ~quad-in~, ~quad-out~, ~quad-in-out~ | quadratic |
| ~cubic-in~, ~cubic-out~, ~cubic-in-out~ | cubic |
| ~sine-in-out~ | smooth sine |
| ~expo-in~, ~expo-out~, ~expo-in-out~ | exponential |
| ~back-out~ | overshoot then settle (Robert Penner–style) |

** ~ease-named~ / ~ease-resolve~

~ease-named~ turns a symbol into a procedure. ~ease-resolve~ accepts a symbol or procedure (identity for procedures) for use in custom tooling.

All easing procedures are exported if you want to compose curves manually.

* Order of operations with physics

Tweens usually **fight** velocity and gravity if both update ~#:x~ / ~#:y~. Typical pattern:

1. Set the entity’s ~#:skip-pipelines~ to skip integration steps you do not want (see [[physics.org][Physics]]).
2. Run ~tween-step~ for that entity.
3. Run your normal physics pipeline (collisions can still run).

Clear ~#:skip-pipelines~ in ~on-complete~ when the tween ends.

Example skip list for “kinematic shove” while keeping tile collisions:

#+begin_src scheme
(entity-set player #:skip-pipelines
  '(jump acceleration gravity velocity-x velocity-y))
#+end_src

* Demo

=bin/demo-tweens= (source =demo/tweens.scm=) shows one row per easing and a crate that tweens horizontally while integration is skipped and tile resolution still runs.

* Limitations (current version)

- Single segment per tween (no built-in chains or sequences).
- Numeric properties only.