# b3ll/motion architecture

> Architecture diagram of the GitHub repository b3ll/motion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/b3ll/motion
- Repository: https://github.com/b3ll/motion

## Overview

Motion is a Swift animation engine for gesture-driven interfaces. A caller configures and starts a spring, decay, or basic animation; the animation advances over frames, updates its value through a callback, and can be interrupted or completed. The runtime uses SIMD-compatible values and an environment-specific animator/driver. Documented extensions include SwiftUI support, Core Animation keyframe emission, rubber-banding, and curve graphing. The graph also includes the indexed movie-maker example; unsampled links are omitted where the excerpts do not establish ownership.

Main entry points: [`Sources/Motion/Animations/SpringAnimation.swift`](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/SpringAnimation.swift) (Spring Animation), [`Sources/Motion/Animations/DecayAnimation.swift`](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/DecayAnimation.swift) (Decay Animation), [`Sources/Motion/Animations/ValueAnimation.swift`](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/ValueAnimation.swift) (Value Animation), [`Sources/Motion/Utilities/Animator.swift`](https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/Animator.swift) (Animator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_animation["Animation Models"]
  node_spring["Spring Animation"]
  node_decay["Decay Animation"]
  node_basic["Basic Animation"]
  node_valueanim["Value Animation"]
  node_groupanim["Animation Group"]
end

subgraph group_runtime["Frame Runtime"]
  node_animator["Animator<br/>[Animator.swift]"]
  node_driver["Frame Driver"]
  node_environment["Animation Environment"]
  node_envproxy["Environment Proxy"]
end

subgraph group_primitives["Math and Values"]
  node_simd["SIMD Values"]
  node_equatable["Approximate Equality"]
  node_springfn["Spring Function"]
  node_decayfn["Decay Function"]
  node_easingfn["Easing Functions"]
end

subgraph group_extensions["Animation Extensions"]
  node_keyframes["Keyframe Emission"]
  node_rubberband["Rubber-Banding"]
  node_graphing["Animation Graphs"]
  node_curves["Curve Graphing"]
end

subgraph group_example["Movie Maker Example"]
  node_moviecontroller["Movie Controller"]
  node_bouncyview["Bouncy View<br/>[BouncyView.swift]"]
end

node_caller(("App or Gesture"))

node_caller -->|"configures and starts"| node_spring
node_caller -->|"configures and starts"| node_decay
node_caller -->|"configures and starts"| node_basic
node_spring -->|"inherits from"| node_valueanim
node_decay -->|"inherits from"| node_valueanim
node_basic -->|"inherits from"| node_valueanim
node_valueanim -->|"registers with"| node_animator
node_animator -->|"drives frames"| node_driver
node_animator -->|"uses environment"| node_environment
node_driver -->|"reads display settings"| node_environment
node_environment -->|"provides animator"| node_animator
node_envproxy -->|"implements"| node_environment
node_valueanim -->|"converts values"| node_simd
node_simd -->|"uses comparisons"| node_equatable
node_spring -->|"uses spring model"| node_springfn
node_decay -->|"uses decay model"| node_decayfn
node_spring -->|"emits keyframes"| node_keyframes
node_decay -->|"emits keyframes"| node_keyframes
node_basic -->|"emits keyframes"| node_keyframes
node_graphing -->|"ticks animation"| node_spring
node_graphing -->|"ticks animation"| node_decay
node_moviecontroller -->|"configures and ticks"| node_spring
node_moviecontroller -->|"adds to view"| node_bouncyview
node_caller -.->|"may apply"| node_rubberband
node_caller -.->|"may configure"| node_easingfn
node_caller -.->|"may inspect curves"| node_curves

click node_spring "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/SpringAnimation.swift"
click node_decay "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/DecayAnimation.swift"
click node_basic "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/BasicAnimation.swift"
click node_valueanim "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/ValueAnimation.swift"
click node_groupanim "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/AnimationGroup.swift"
click node_animator "https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/Animator.swift"
click node_driver "https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/AnimationDriver.swift"
click node_environment "https://github.com/b3ll/motion/blob/main/Sources/Motion/Protocols/AnimationEnvironment.swift"
click node_envproxy "https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/AnimationEnvironmentProxy.swift"
click node_simd "https://github.com/b3ll/motion/blob/main/Sources/Motion/Protocols/SIMDRepresentable.swift"
click node_equatable "https://github.com/b3ll/motion/blob/main/Sources/Motion/Protocols/EquatableEnough.swift"
click node_springfn "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/Functions/SpringFunction.swift"
click node_decayfn "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/Functions/DecayFunction.swift"
click node_easingfn "https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/Functions/EasingFunctions.swift"
click node_keyframes "https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/CAKeyframeAnimationEmittable.swift"
click node_rubberband "https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/RubberBanding.swift"
click node_graphing "https://github.com/b3ll/motion/blob/main/Sources/Graphing/ValueAnimationGraph.swift"
click node_curves "https://github.com/b3ll/motion/blob/main/Sources/Graphing/EasingFunctionGraph.swift"
click node_moviecontroller "https://github.com/b3ll/motion/blob/main/Resources/MotionMovieMaker/MotionMovieMaker/ViewController.swift"
click node_bouncyview "https://github.com/b3ll/motion/blob/main/Resources/MotionMovieMaker/MotionMovieMaker/BouncyView.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spring,node_decay,node_basic,node_valueanim,node_groupanim toneBlue
class node_animator,node_driver,node_environment,node_envproxy toneAmber
class node_simd,node_equatable,node_springfn,node_decayfn,node_easingfn toneMint
class node_keyframes,node_rubberband,node_graphing,node_curves toneRose
class node_moviecontroller,node_bouncyview,node_caller toneIndigo
```

## Components

### Animation Models

- [Spring Animation](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/SpringAnimation.swift): `Sources/Motion/Animations/SpringAnimation.swift`
- [Decay Animation](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/DecayAnimation.swift): `Sources/Motion/Animations/DecayAnimation.swift`
- [Basic Animation](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/BasicAnimation.swift): `Sources/Motion/Animations/BasicAnimation.swift`
- [Value Animation](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/ValueAnimation.swift): `Sources/Motion/Animations/ValueAnimation.swift`
- [Animation Group](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/AnimationGroup.swift): `Sources/Motion/Animations/AnimationGroup.swift`

### Frame Runtime

- [Animator](https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/Animator.swift): `Sources/Motion/Utilities/Animator.swift`
- [Frame Driver](https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/AnimationDriver.swift): `Sources/Motion/Utilities/AnimationDriver.swift`
- [Animation Environment](https://github.com/b3ll/motion/blob/main/Sources/Motion/Protocols/AnimationEnvironment.swift): `Sources/Motion/Protocols/AnimationEnvironment.swift`
- [Environment Proxy](https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/AnimationEnvironmentProxy.swift): `Sources/Motion/Utilities/AnimationEnvironmentProxy.swift`

### Math and Values

- [SIMD Values](https://github.com/b3ll/motion/blob/main/Sources/Motion/Protocols/SIMDRepresentable.swift): `Sources/Motion/Protocols/SIMDRepresentable.swift`
- [Approximate Equality](https://github.com/b3ll/motion/blob/main/Sources/Motion/Protocols/EquatableEnough.swift): `Sources/Motion/Protocols/EquatableEnough.swift`
- [Spring Function](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/Functions/SpringFunction.swift): `Sources/Motion/Animations/Functions/SpringFunction.swift`
- [Decay Function](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/Functions/DecayFunction.swift): `Sources/Motion/Animations/Functions/DecayFunction.swift`
- [Easing Functions](https://github.com/b3ll/motion/blob/main/Sources/Motion/Animations/Functions/EasingFunctions.swift): `Sources/Motion/Animations/Functions/EasingFunctions.swift`

### Animation Extensions

- [Keyframe Emission](https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/CAKeyframeAnimationEmittable.swift): `Sources/Motion/Utilities/CAKeyframeAnimationEmittable.swift`
- [Rubber-Banding](https://github.com/b3ll/motion/blob/main/Sources/Motion/Utilities/RubberBanding.swift): `Sources/Motion/Utilities/RubberBanding.swift`
- [Animation Graphs](https://github.com/b3ll/motion/blob/main/Sources/Graphing/ValueAnimationGraph.swift): `Sources/Graphing/ValueAnimationGraph.swift`
- [Curve Graphing](https://github.com/b3ll/motion/blob/main/Sources/Graphing/EasingFunctionGraph.swift): `Sources/Graphing/EasingFunctionGraph.swift`

### Movie Maker Example

- [Movie Controller](https://github.com/b3ll/motion/blob/main/Resources/MotionMovieMaker/MotionMovieMaker/ViewController.swift): `Resources/MotionMovieMaker/MotionMovieMaker/ViewController.swift`
- [Bouncy View](https://github.com/b3ll/motion/blob/main/Resources/MotionMovieMaker/MotionMovieMaker/BouncyView.swift): `Resources/MotionMovieMaker/MotionMovieMaker/BouncyView.swift`

### Other components

- **App or Gesture**

## Connections

- App or Gesture → Spring Animation: configures and starts (evidence: `README.md`)
- App or Gesture → Decay Animation: configures and starts (evidence: `README.md`)
- App or Gesture → Basic Animation: configures and starts (evidence: `README.md`)
- Spring Animation → Value Animation: inherits from (evidence: `Sources/Motion/Animations/SpringAnimation.swift`)
- Decay Animation → Value Animation: inherits from (evidence: `Sources/Motion/Animations/DecayAnimation.swift`)
- Basic Animation → Value Animation: inherits from (evidence: `Sources/Motion/Animations/BasicAnimation.swift`)
- Value Animation → Animator: registers with (evidence: `Sources/Motion/Animations/ValueAnimation.swift`)
- Animator → Frame Driver: drives frames (evidence: `Sources/Motion/Utilities/Animator.swift`)
- Animator → Animation Environment: uses environment (evidence: `Sources/Motion/Utilities/Animator.swift`)
- Frame Driver → Animation Environment: reads display settings (evidence: `Sources/Motion/Utilities/AnimationDriver.swift`)
- Animation Environment → Animator: provides animator (evidence: `Sources/Motion/Protocols/AnimationEnvironment.swift`)
- Environment Proxy → Animation Environment: implements (evidence: `Sources/Motion/Utilities/AnimationEnvironmentProxy.swift`)
- Value Animation → SIMD Values: converts values (evidence: `Sources/Motion/Animations/ValueAnimation.swift`)
- SIMD Values → Approximate Equality: uses comparisons (evidence: `Sources/Motion/Protocols/SIMDRepresentable.swift`)
- Spring Animation → Spring Function: uses spring model (evidence: `Sources/Motion/Animations/SpringAnimation.swift`)
- Decay Animation → Decay Function: uses decay model (evidence: `Sources/Motion/Animations/DecayAnimation.swift`)
- Spring Animation → Keyframe Emission: emits keyframes (evidence: `Sources/Motion/Utilities/CAKeyframeAnimationEmittable.swift`)
- Decay Animation → Keyframe Emission: emits keyframes (evidence: `Sources/Motion/Utilities/CAKeyframeAnimationEmittable.swift`)
- Basic Animation → Keyframe Emission: emits keyframes (evidence: `Sources/Motion/Utilities/CAKeyframeAnimationEmittable.swift`)
- Animation Graphs → Spring Animation: ticks animation (evidence: `Sources/Graphing/ValueAnimationGraph.swift`)
- Animation Graphs → Decay Animation: ticks animation (evidence: `Sources/Graphing/ValueAnimationGraph.swift`)
- Movie Controller → Spring Animation: configures and ticks (evidence: `Resources/MotionMovieMaker/MotionMovieMaker/ViewController.swift`)
- Movie Controller → Bouncy View: adds to view (evidence: `Resources/MotionMovieMaker/MotionMovieMaker/ViewController.swift`)
- App or Gesture → Rubber-Banding: may apply (evidence: `README.md`)
- App or Gesture → Easing Functions: may configure (evidence: `README.md`)
- App or Gesture → Curve Graphing: may inspect curves (evidence: `README.md`)
