Let animation keys ease with Sine to Bounce in, out or in-out

A key could only ease quadratically, which makes quick moves like a
sword swing feel soft. Animators know the Penner curves from CSS,
GSAP and Unity, so a key now offers all of them.

- Ten curves (Sine, Quad, Cubic, Quart, Quint, Expo, Circ, Back,
  Elastic, Bounce), each in, out and in-out, next to Linear and Step.
- The inspector shows two fields instead of one long list: Easing,
  and Direction only when a curve is picked. Switching the curve
  keeps the direction. Coming from Linear or Step starts at in-out.
- Old projects keep working. ease-in/out/in-out now read as Quad and
  are still saved under that name. New curves save as cubic-out,
  back-in-out and so on.
- Back and Elastic overshoot on purpose. A number property with min
  or max is clamped in play and preview, so a Back in from scale 0
  does not flip the sprite. trackWriteAt now takes the property
  definition, and animatedKind* is renamed to animatedDef*.
- The timeline marker still shows only the direction.
- In-out is built for every curve from its in-curve and its mirror.
  easings.net uses own constants for Back and Elastic in-out, so our
  Back in-out winds up about 5 % instead of 10 %.

Tests:
- ./check.sh: 165 files, 2413 tests, CHECK EXIT 0.
- 12 new unit tests in tests/core/easing-curves.test.ts: round trip
  of all 30 values, start/end/midpoint of every curve, reference
  values, only Back and Elastic leave 0..1, clamping in play and
  preview, unknown values are rejected.
- e2e 25: ALL PASSED, 28 checks. New 25b-ii (3 checks) clicks both
  fields and undoes the four choices. Check sum 1393 -> 1396.
- Counter-checks, each fails its test: no clamping (2), Quad saved
  as quad-* (2), mirrored in-out wrong (2), curve lookup with `in`
  instead of Object.hasOwn (1), no Direction field (e2e 25).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/model/Asset.ts

@@ -149,8 +149,16 @@ export interface TextureAsset extends AssetBase {
   frames: TextureFrame[];
 }
 
-/** How a key blends into the next one (#101); absent is `linear`. `step` holds until the next key. */
-export type KeyInterpolation = 'linear' | 'step' | 'ease-in' | 'ease-out' | 'ease-in-out';
+export type EasingCurve =
+  'sine' | 'quad' | 'cubic' | 'quart' | 'quint' | 'expo' | 'circ' | 'back' | 'elastic' | 'bounce';
+export type EasingDirection = 'in' | 'out' | 'in-out';
+
+/**
+ * How a key blends into the next one (#101); absent is `linear`. `step` holds until the next key. A
+ * curve is stored as `<curve>-<direction>`, except quad, which keeps its first name `ease-<direction>`.
+ */
+export type KeyInterpolation =
+  'linear' | 'step' | `ease-${EasingDirection}` | `${Exclude<EasingCurve, 'quad'>}-${EasingDirection}`;
 
 /**
  * A value on a whole frame. Its interpolation rules the way to the next key. A value that cannot

src/core/model/animation.ts

@@ -1,7 +1,15 @@
 import { isKindWith } from '../properties/kinds';
 import { type PropertyDef, schemaFor, shaderParamRows } from '../properties/PropertySchema';
 import { shaderOf } from '../properties/shaders';
-import type { AnimationAsset, AnimationKey, AnimationTrack, Asset, KeyInterpolation } from './Asset';
+import type {
+  AnimationAsset,
+  AnimationKey,
+  AnimationTrack,
+  Asset,
+  EasingCurve,
+  EasingDirection,
+  KeyInterpolation,
+} from './Asset';
 import type { AssetType } from './AssetTypes';
 import { treeOrder } from './hierarchy';
 import { instanceChildId, resolveObjects } from './instance';
@@ -104,17 +112,85 @@ export function blends(kind: string): boolean {
   return kind === 'number' || kind === 'color';
 }
 
-/** In the order the inspector offers them; `linear` first, since it is what an absent field means. */
-export const KEY_INTERPOLATIONS: readonly { value: KeyInterpolation; label: string }[] = [
+export type EasingShape = 'linear' | 'step' | EasingCurve;
+
+/** The inspector's first easing field, in the order it offers them; `linear` is what an absent field means. */
+export const EASING_SHAPES: readonly { value: EasingShape; label: string }[] = [
   { value: 'linear', label: 'Linear' },
   { value: 'step', label: 'Step' },
-  { value: 'ease-in', label: 'Ease in' },
-  { value: 'ease-out', label: 'Ease out' },
-  { value: 'ease-in-out', label: 'Ease in-out' },
+  { value: 'sine', label: 'Sine' },
+  { value: 'quad', label: 'Quad' },
+  { value: 'cubic', label: 'Cubic' },
+  { value: 'quart', label: 'Quart' },
+  { value: 'quint', label: 'Quint' },
+  { value: 'expo', label: 'Expo' },
+  { value: 'circ', label: 'Circ' },
+  { value: 'back', label: 'Back' },
+  { value: 'elastic', label: 'Elastic' },
+  { value: 'bounce', label: 'Bounce' },
 ];
 
+/** The second field, for a curve only. */
+export const EASING_DIRECTIONS: readonly { value: EasingDirection; label: string }[] = [
+  { value: 'in', label: 'In' },
+  { value: 'out', label: 'Out' },
+  { value: 'in-out', label: 'In-out' },
+];
+
+const BACK = 1.70158;
+const ELASTIC = (2 * Math.PI) / 3;
+
+function bounceOut(t: number): number {
+  const n = 7.5625;
+  const d = 2.75;
+  if (t < 1 / d) return n * t * t;
+  if (t < 2 / d) return n * (t -= 1.5 / d) * t + 0.75;
+  if (t < 2.5 / d) return n * (t -= 2.25 / d) * t + 0.9375;
+  return n * (t -= 2.625 / d) * t + 0.984375;
+}
+
+/** Each curve's `in` form (Penner's); `out` is it mirrored, `in-out` both halves. Back and elastic leave 0…1. */
+const EASE_IN: Record<EasingCurve, (t: number) => number> = {
+  sine: (t) => 1 - Math.cos((t * Math.PI) / 2),
+  quad: (t) => t * t,
+  cubic: (t) => t ** 3,
+  quart: (t) => t ** 4,
+  quint: (t) => t ** 5,
+  expo: (t) => (t <= 0 ? 0 : 2 ** (10 * t - 10)),
+  circ: (t) => 1 - Math.sqrt(1 - t * t),
+  back: (t) => (BACK + 1) * t ** 3 - BACK * t * t,
+  elastic: (t) => (t <= 0 ? 0 : t >= 1 ? 1 : -(2 ** (10 * t - 10)) * Math.sin((10 * t - 10.75) * ELASTIC)),
+  bounce: (t) => 1 - bounceOut(1 - t),
+};
+
+function isCurve(value: string): value is EasingCurve {
+  return Object.hasOwn(EASE_IN, value);
+}
+
+/** A stored interpolation split into the inspector's two fields; unknown text reads as `linear`. */
+export function easingOf(interpolation: KeyInterpolation): {
+  shape: EasingShape;
+  direction?: EasingDirection;
+} {
+  if (interpolation === 'linear' || interpolation === 'step') return { shape: interpolation };
+  const match = /^([a-z]+)-(in|out|in-out)$/.exec(interpolation);
+  if (!match) return { shape: 'linear' };
+  const curve = match[1]!;
+  const direction = match[2] as EasingDirection;
+  if (curve === 'ease') return { shape: 'quad', direction };
+  return isCurve(curve) && curve !== 'quad' ? { shape: curve, direction } : { shape: 'linear' };
+}
+
+/** The stored form of the two fields; a curve without a direction eases both ways. */
+export function easingValue(shape: EasingShape, direction: EasingDirection = 'in-out'): KeyInterpolation {
+  if (shape === 'linear' || shape === 'step') return shape;
+  return shape === 'quad' ? `ease-${direction}` : `${shape}-${direction}`;
+}
+
 export function isKeyInterpolation(value: unknown): value is KeyInterpolation {
-  return KEY_INTERPOLATIONS.some((i) => i.value === value);
+  if (typeof value !== 'string') return false;
+  const { shape, direction } = easingOf(value as KeyInterpolation);
+  return easingValue(shape, direction) === value;
 }
 
 export function interpolationOf(key: AnimationKey): KeyInterpolation {
@@ -122,21 +198,21 @@ export function interpolationOf(key: AnimationKey): KeyInterpolation {
 }
 
 /**
- * How far along the way to the next key a value is, `t` the share of the time passed. The eases are
- * quadratic: ease-in reaches 0.25 at half the time, ease-out 0.75, ease-in-out 0.5 but 0.125 at a quarter.
+ * How far along the way to the next key a value is, `t` the share of the time passed. Quad, the eases
+ * of old, reaches 0.25 at half the time going in, 0.75 going out, and 0.125 at a quarter going both.
  */
-function easedShare(interpolation: KeyInterpolation, t: number): number {
-  switch (interpolation) {
-    case 'linear':
-      return t;
-    case 'step':
-      return 0;
-    case 'ease-in':
-      return t * t;
-    case 'ease-out':
-      return 1 - (1 - t) * (1 - t);
-    case 'ease-in-out':
-      return t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t);
+export function easedShare(interpolation: KeyInterpolation, t: number): number {
+  const { shape, direction } = easingOf(interpolation);
+  if (shape === 'linear') return t;
+  if (shape === 'step') return 0;
+  const easeIn = EASE_IN[shape];
+  switch (direction ?? 'in-out') {
+    case 'in':
+      return easeIn(t);
+    case 'out':
+      return 1 - easeIn(1 - t);
+    case 'in-out':
+      return t < 0.5 ? easeIn(2 * t) / 2 : 1 - easeIn(2 - 2 * t) / 2;
   }
 }
 
@@ -182,34 +258,50 @@ export function trackValueAt(
 /**
  * What a row writes at a frame: its value, or for a relative number row that value added to `base`,
  * what the target held when the animation started. Shared by the runtime player and the tab's
- * preview, so both show the same picture. `undefined` for a row without keys.
+ * preview, so both show the same picture. A number is held to the property's `min`/`max`, which a
+ * back or elastic curve overshoots. `undefined` for a row without keys.
  */
 export function trackWriteAt(
   track: AnimationTrack,
-  kind: string,
+  def: RowDef,
   frame: number,
   base: PropertyValue | undefined,
   reverse = false,
 ): PropertyValue | undefined {
-  const value = trackValueAt(track.keys, kind, frame, reverse);
+  const value = trackValueAt(track.keys, def.kind, frame, reverse);
   if (value === undefined) return undefined;
-  const offset = track.relative && kind === 'number' && typeof base === 'number';
-  return offset ? base + Number(value) : value;
+  if (def.kind !== 'number') return value;
+  const offset = track.relative && typeof base === 'number';
+  return heldTo(def, offset ? base + Number(value) : value);
 }
 
-/** The kind a row's property has on an asset of that type; undefined for one the timeline cannot animate. */
-export function animatedKind(type: AssetType, key: string): string | undefined {
-  return animatableDefs(type).find((d) => d.key === key)?.kind;
+/** What `trackWriteAt` needs of a property; a `PropertyDef` has it. */
+export interface RowDef {
+  kind: string;
+  min?: number;
+  max?: number;
 }
 
-/** The kind `key` has on an asset holding `bag` – see `animatableDefsOf`. */
-export function animatedKindOf(
+function heldTo(def: RowDef, value: PropertyValue): PropertyValue {
+  if (typeof value !== 'number') return value;
+  if (def.min !== undefined && value < def.min) return def.min;
+  if (def.max !== undefined && value > def.max) return def.max;
+  return value;
+}
+
+/** A row's property on an asset of that type; undefined for one the timeline cannot animate. */
+export function animatedDef(type: AssetType, key: string): PropertyDef | undefined {
+  return animatableDefs(type).find((d) => d.key === key);
+}
+
+/** The property `key` is on an asset holding `bag` – see `animatableDefsOf`. */
+export function animatedDefOf(
   project: Project,
   asset: Asset,
   bag: PropertyBag,
   key: string,
-): string | undefined {
-  return animatableDefsOf(project, asset, bag).find((d) => d.key === key)?.kind;
+): PropertyDef | undefined {
+  return animatableDefsOf(project, asset, bag).find((d) => d.key === key);
 }
 
 function hasPosition(type: AssetType): boolean {

src/core/model/animationPreview.ts

@@ -5,7 +5,7 @@
  */
 import {
   animatableDefs,
-  animatedKindOf,
+  animatedDefOf,
   frameCount,
   isPositionRow,
   PLACED_ROOT_ID,
@@ -72,7 +72,7 @@ function placedHolder(root: Asset): ObjectHolder {
 function writeScene(holder: ObjectHolder, track: AnimationTrack, frame: number, reverse: boolean): void {
   const def = animatableDefs('scene').find((d) => d.key === track.property);
   if (!def) return;
-  const value = trackWriteAt(track, def.kind, frame, holder.props[track.property] ?? def.default, reverse);
+  const value = trackWriteAt(track, def, frame, holder.props[track.property] ?? def.default, reverse);
   if (value !== undefined) holder.props[track.property] = value;
 }
 
@@ -89,14 +89,14 @@ function writeObject(
   if (!ref || !asset) return;
   // Resolved, so a shader worn through an override or an instance edit brings its parameters (#104).
   const props = resolveSceneObjectProps(project, asset, ref.object);
-  const kind = animatedKindOf(project, asset, props, track.property);
-  if (!kind) return;
+  const def = animatedDefOf(project, asset, props, track.property);
+  if (!def) return;
   const key = track.property;
   if (isPositionRow(asset.type, key)) {
-    const value = trackWriteAt(track, kind, frame, ref.object.position[key], reverse);
+    const value = trackWriteAt(track, def, frame, ref.object.position[key], reverse);
     if (value !== undefined) ref.setPosition({ ...ref.object.position, [key]: Number(value) });
     return;
   }
-  const value = trackWriteAt(track, kind, frame, props[key], reverse);
+  const value = trackWriteAt(track, def, frame, props[key], reverse);
   if (value !== undefined) ref.setOverride(key, value);
 }

src/editor/animation/TimelineCanvas.ts

@@ -10,6 +10,7 @@ import {
 } from '../../core/commands/animationCommands';
 import {
   animationPlayheadAt,
+  easingOf,
   fpsOf,
   frameCount,
   hasKey,
@@ -683,8 +684,8 @@ export class TimelineCanvas extends Widget {
 
 /**
  * A key's outline tells its easing: the right half is the start of the way to the next key, the left
- * half its end, and a round half is a slow one. Linear is the diamond, ease-in-out the circle, a step
- * – which holds – the square.
+ * half its end, and a round half is a slow one. Linear is the diamond, any curve in-out the circle, a
+ * step – which holds – the square.
  */
 function drawKeyShape(
   g: Graphics,
@@ -694,8 +695,9 @@ function drawKeyShape(
   half: number,
 ): Graphics {
   if (interpolation === 'step') return g.rect(x - half * 0.75, y - half * 0.75, half * 1.5, half * 1.5);
-  const slowStart = interpolation === 'ease-in' || interpolation === 'ease-in-out';
-  const slowEnd = interpolation === 'ease-out' || interpolation === 'ease-in-out';
+  const { direction } = easingOf(interpolation);
+  const slowStart = direction === 'in' || direction === 'in-out';
+  const slowEnd = direction === 'out' || direction === 'in-out';
   g.moveTo(x, y - half);
   if (slowStart) g.arc(x, y, half, -Math.PI / 2, Math.PI / 2);
   else g.lineTo(x + half, y).lineTo(x, y + half);

src/editor/inspector/trackSection.ts

@@ -7,15 +7,25 @@ import {
 } from '../../core/commands/animationCommands';
 import {
   blends,
+  EASING_DIRECTIONS,
+  EASING_SHAPES,
+  easingOf,
+  type EasingShape,
+  easingValue,
   findKey,
   findTrack,
   interpolationOf,
-  KEY_INTERPOLATIONS,
   type KeyRef,
   trackDef,
   trackLabel,
 } from '../../core/model/animation';
-import type { AnimationAsset, AnimationKey, AnimationTrack, KeyInterpolation } from '../../core/model/Asset';
+import type {
+  AnimationAsset,
+  AnimationKey,
+  AnimationTrack,
+  EasingDirection,
+  KeyInterpolation,
+} from '../../core/model/Asset';
 import { findAssetOf, type Project } from '../../core/model/Project';
 import { Button } from '../../ui';
 import { openRowDialog, RowDialog } from '../animation/RowDialog';
@@ -132,30 +142,57 @@ function buildKey(host: InspectorHost, asset: AnimationAsset, ref: KeyRef): void
 }
 
 /**
- * How the picked keys blend into their next key – for all of them at once. It shows the easing of the
- * key picked last among those that can blend; a row that cannot blend offers none, it always jumps.
+ * How the picked keys blend into their next key – for all of them at once: a curve and, for one that
+ * is not linear or step, its direction. It shows the easing of the key picked last among those that
+ * can blend; a row that cannot blend offers none, it always jumps.
  */
 function buildEasing(host: InspectorHost, asset: AnimationAsset, keys: readonly KeyRef[]): void {
   const shown = easingKey(host.state.project, asset, keys);
   if (!shown) return;
-  const row = createFieldRow(
+  const easing = easingOf(interpolationOf(shown));
+  // Read at the click, not now: the other field may have changed the key since this row was built.
+  const current = () => {
+    const key = easingKey(host.state.project, asset, keys);
+    return easingOf(key ? interpolationOf(key) : 'linear');
+  };
+  const set = (value: KeyInterpolation) =>
+    host.state.execute(new SetKeyInterpolationCommand(asset.id, [...keys], value));
+  const shape = createFieldRow(
     host,
     {
       key: 'easing',
       label: 'Easing',
       kind: 'enum',
       default: 'linear',
-      options: KEY_INTERPOLATIONS.map((i) => ({ ...i })),
+      options: EASING_SHAPES.map((i) => ({ ...i })),
     },
-    interpolationOf(shown),
+    easing.shape,
     {
       onInput: () => {},
-      onChange: (value) =>
-        host.state.execute(new SetKeyInterpolationCommand(asset.id, [...keys], value as KeyInterpolation)),
+      onChange: (value) => set(easingValue(value as EasingShape, current().direction)),
     },
   );
-  host.fields.set('easing', row);
-  host.body.add(row.row);
+  host.fields.set('easing', shape);
+  host.body.add(shape.row);
+  if (easing.direction) {
+    const direction = createFieldRow(
+      host,
+      {
+        key: 'direction',
+        label: 'Direction',
+        kind: 'enum',
+        default: 'in-out',
+        options: EASING_DIRECTIONS.map((i) => ({ ...i })),
+      },
+      easing.direction,
+      {
+        onInput: () => {},
+        onChange: (value) => set(easingValue(current().shape, value as EasingDirection)),
+      },
+    );
+    host.fields.set('direction', direction);
+    host.body.add(direction.row);
+  }
   addNote(host, 'Easing: the way from this key to the next one.', 'small');
 }
 
@@ -193,7 +230,11 @@ export function refreshTrackSection(
   }
   const eased = easingKey(host.state.project, asset, keys);
   if (Boolean(eased) !== host.fields.has('easing')) return false;
-  if (eased) host.fields.get('easing')?.setValue(interpolationOf(eased));
+  if (!eased) return true;
+  const easing = easingOf(interpolationOf(eased));
+  if (Boolean(easing.direction) !== host.fields.has('direction')) return false;
+  host.fields.get('easing')?.setValue(easing.shape);
+  if (easing.direction) host.fields.get('direction')?.setValue(easing.direction);
   return true;
 }
 

src/runtime/systems/AnimationSystem.ts

@@ -1,8 +1,8 @@
 import { isHandleEnabled } from '../../core/graph';
 import {
   type AnimationPlayer,
-  animatedKind,
-  animatedKindOf,
+  animatedDef,
+  animatedDefOf,
   animationPlayheadAt,
   blendShare,
   blends,
@@ -15,6 +15,7 @@ import type { AnimationAsset, AnimationTrack } from '../../core/model/Asset';
 import { instanceChildId, splitInstanceId } from '../../core/model/instance';
 import { findAsset, findAssetOf } from '../../core/model/Project';
 import type { PropertyValue } from '../../core/model/Properties';
+import type { PropertyDef } from '../../core/properties/PropertySchema';
 import type { Entity } from '../Entity';
 import type { World } from '../World';
 import type { System } from './System';
@@ -28,7 +29,7 @@ export interface AnimationFinish {
 /** A row that reaches something this tick: how to read and write it, and the kind it blends as. */
 interface Binding {
   track: AnimationTrack;
-  kind: string;
+  def: PropertyDef;
   /** Where the player keeps the starting value: `<entity id> <property>`, or `scene <property>`. */
   base: string;
   read(): PropertyValue;
@@ -80,16 +81,17 @@ export class AnimationSystem implements System {
       const fade = player.fade;
       const fadeShare = fade ? blendShare(fade) : 0;
       for (const b of bindings) {
-        let value = trackWriteAt(b.track, b.kind, head.frame, player.bases[b.base], head.reverse);
+        let value = trackWriteAt(b.track, b.def, head.frame, player.bases[b.base], head.reverse);
         if (value === undefined) continue;
         const below = written.has(b.base) ? b.read() : undefined;
-        if (share < 1 && blends(b.kind)) {
+        if (share < 1 && blends(b.def.kind)) {
           const from = below ?? blend?.from?.[b.base];
-          if (from !== undefined) value = blendValue(b.kind, from, value, share);
+          if (from !== undefined) value = blendValue(b.def.kind, from, value, share);
         }
         if (fade) {
           const back = below ?? player.bases[b.base];
-          if (back !== undefined) value = blends(b.kind) ? blendValue(b.kind, value, back, fadeShare) : back;
+          if (back !== undefined)
+            value = blends(b.def.kind) ? blendValue(b.def.kind, value, back, fadeShare) : back;
         }
         b.write(value);
         written.add(b.base);
@@ -139,11 +141,11 @@ function bind(world: World, asset: AnimationAsset, owner: Entity): Binding[] {
   for (const track of asset.tracks) {
     const key = track.property;
     if (root.type === 'scene' && track.target === '') {
-      const kind = world.sceneId === root.id ? animatedKind('scene', key) : undefined;
-      if (kind)
+      const def = world.sceneId === root.id ? animatedDef('scene', key) : undefined;
+      if (def)
         bindings.push({
           track,
-          kind,
+          def,
           base: `scene ${key}`,
           read: () => world.sceneProps[key] ?? 0,
           write: (value) => {
@@ -157,12 +159,12 @@ function bind(world: World, asset: AnimationAsset, owner: Entity): Binding[] {
       entity = world.sceneId === root.id ? world.findByObjectId(track.target) : undefined;
     else if (track.target === '') entity = owner;
     else entity = world.findByObjectId(childId(owner.objectId, track.target));
-    const kind = entity && kindOn(world, entity, key);
-    if (entity && kind) {
+    const def = entity && defOn(world, entity, key);
+    if (entity && def) {
       const aimed = entity;
       bindings.push({
         track,
-        kind,
+        def,
         base: `${aimed.id} ${key}`,
         read: () => read(aimed, key),
         write: (value) => write(aimed, key, value),
@@ -173,12 +175,12 @@ function bind(world: World, asset: AnimationAsset, owner: Entity): Binding[] {
 }
 
 /**
- * The kind `key` has on the entity as it is now: its bag names the shader it wears, and swapping that
+ * The property `key` is on the entity as it is now: its bag names the shader it wears, and swapping that
  * shader at runtime takes the parameter rows with it (#104).
  */
-function kindOn(world: World, entity: Entity, key: string): string | undefined {
+function defOn(world: World, entity: Entity, key: string): PropertyDef | undefined {
   const asset = findAsset(world.project, entity.assetId);
-  return asset && animatedKindOf(world.project, asset, entity.props, key);
+  return asset && animatedDefOf(world.project, asset, entity.props, key);
 }
 
 /**