1# Physics-Based Animations Reference
2 
3Physics-based animations create natural-feeling motion using simulations like springs, gravity, and momentum.
4 
5## Core Concept
6 
7Instead of linear interpolation, use physics simulations for realistic motion that responds naturally to forces like velocity and damping.
8 
9## Fling Animation
10 
11### Basic Fling
12 
13```dart
14class FlingWidget extends StatefulWidget {
15  @override
16  State<FlingWidget> createState() => _FlingWidgetState();
17}
18 
19class _FlingWidgetState extends State<FlingWidget>
20    with SingleTickerProviderStateMixin {
21  late AnimationController _controller;
22 
23  @override
24  void initState() {
25    super.initState();
26    _controller = AnimationController(
27      duration: const Duration(seconds: 1),
28      vsync: this,
29    );
30    _controller.fling(velocity: 2.0);
31  }
32 
33  @override
34  void dispose() {
35    _controller.dispose();
36    super.dispose();
37  }
38 
39  @override
40  Widget build(BuildContext context) {
41    return AnimatedBuilder(
42      animation: _controller,
43      builder: (context, child) {
44        return Transform.translate(
45          offset: Offset(_controller.value * 100, 0),
46          child: child,
47        );
48      },
49      child: const FlutterLogo(),
50    );
51  }
52}
53```
54 
55### Fling with Gesture
56 
57```dart
58class DraggableFling extends StatefulWidget {
59  @override
60  State<DraggableFling> createState() => _DraggableFlingState();
61}
62 
63class _DraggableFlingState extends State<DraggableFling>
64    with SingleTickerProviderStateMixin {
65  late AnimationController _controller;
66  double _dragX = 0;
67  Offset? _startPosition;
68 
69  @override
70  void initState() {
71    super.initState();
72    _controller = AnimationController.unbounded(vsync: this);
73  }
74 
75  @override
76  void dispose() {
77    _controller.dispose();
78    super.dispose();
79  }
80 
81  void _handlePanStart(DragStartDetails details) {
82    _controller.stop();
83    _startPosition = details.globalPosition;
84  }
85 
86  void _handlePanUpdate(DragUpdateDetails details) {
87    if (_startPosition != null) {
88      setState(() {
89        _dragX += details.delta.dx;
90      });
91    }
92  }
93 
94  void _handlePanEnd(DragEndDetails details) {
95    _controller.fling(velocity: details.velocity.pixelsPerSecond.dx / 1000);
96  }
97 
98  @override
99  Widget build(BuildContext context) {
100    return GestureDetector(
101      onPanStart: _handlePanStart,
102      onPanUpdate: _handlePanUpdate,
103      onPanEnd: _handlePanEnd,
104      child: AnimatedBuilder(
105        animation: _controller,
106        builder: (context, child) {
107          return Transform.translate(
108            offset: Offset(_dragX + _controller.value, 0),
109            child: child,
110          );
111        },
112        child: const FlutterLogo(),
113      ),
114    );
115  }
116}
117```
118 
119## Spring Simulation
120 
121### Basic Spring
122 
123```dart
124class SpringAnimation extends StatefulWidget {
125  @override
126  State<SpringAnimation> createState() => _SpringAnimationState();
127}
128 
129class _SpringAnimationState extends State<SpringAnimation>
130    with SingleTickerProviderStateMixin {
131  late AnimationController _controller;
132 
133  @override
134  void initState() {
135    super.initState();
136    _controller = AnimationController.unbounded(vsync: this);
137 
138    _controller.animateWith(
139      SpringSimulation(
140        spring: const SpringDescription(
141          mass: 1.0,
142          stiffness: 200.0,
143          damping: 10.0,
144        ),
145        start: 0.0,
146        end: 1.0,
147        velocity: 0.0,
148      ),
149    );
150  }
151 
152  @override
153  void dispose() {
154    _controller.dispose();
155    super.dispose();
156  }
157 
158  @override
159  Widget build(BuildContext context) {
160    return AnimatedBuilder(
161      animation: _controller,
162      builder: (context, child) {
163        return Transform.scale(
164          scale: _controller.value,
165          child: child,
166        );
167      },
168      child: const FlutterLogo(),
169    );
170  }
171}
172```
173 
174### Spring Description Parameters
175 
176```dart
177SpringDescription(
178  mass: 1.0,        // Mass of the object (higher = more inertia)
179  stiffness: 200.0,   // Spring stiffness (higher = faster, stiffer)
180  damping: 10.0,      // Damping ratio (higher = less oscillation)
181)
182)
183```
184 
185**Mass:**
186- How "heavy" the object feels
187- Typical values: 0.5 - 5.0
188- Higher mass = more momentum, slower response
189 
190**Stiffness:**
191- How stiff the spring is
192- Typical values: 100 - 500
193- Higher stiffness = faster oscillation
194- Lower stiffness = slower, more "bouncy"
195 
196**Damping:**
197- How quickly oscillation stops
198- Typical values: 5 - 20
199- Higher damping = less bounce
200- Lower damping = more bounce
201- Critical damping: ~15-18
202 
203### Spring Presets
204 
205**Bouncy:**
206```dart
207SpringDescription(
208  mass: 0.5,
209  stiffness: 300,
210  damping: 8,
211)
212```
213 
214**Snappy:**
215```dart
216SpringDescription(
217  mass: 1.0,
218  stiffness: 400,
219  damping: 18,
220)
221```
222 
223**Gentle:**
224```dart
225SpringDescription(
226  mass: 2.0,
227  stiffness: 150,
228  damping: 20,
229)
230```
231 
232## Gravity Simulation
233 
234### Falling Animation
235 
236```dart
237class GravityAnimation extends StatefulWidget {
238  @override
239  State<GravityAnimation> createState() => _GravityAnimationState();
240}
241 
242class _GravityAnimationState extends State<GravityAnimation>
243    with SingleTickerProviderStateMixin {
244  late AnimationController _controller;
245 
246  @override
247  void initState() {
248    super.initState();
249    _controller = AnimationController.unbounded(vsync: this);
250 
251    _controller.animateWith(
252      GravitySimulation(
253        acceleration: 980,  // pixels/s²
254        distance: 500,  // pixels to fall
255        startDistance: 0,
256      ),
257    );
258  }
259 
260  @override
261  void dispose() {
262    _controller.dispose();
263    super.dispose();
264  }
265 
266  @override
267  Widget build(BuildContext context) {
268    return AnimatedBuilder(
269      animation: _controller,
270      builder: (context, child) {
271        return Transform.translate(
272          offset: Offset(0, _controller.value),
273          child: child,
274        );
275      },
276      child: const FlutterLogo(),
277    );
278  }
279}
280```
281 
282## Scroll Physics
283 
284### Bouncing Scroll
285 
286```dart
287CustomScrollView(
288  physics: const BouncingScrollPhysics(),
289  slivers: [
290    SliverList(
291      delegate: SliverChildListDelegate([
292        // Items
293      ]),
294    ),
295  ],
296)
297```
298 
299### Clamping Scroll
300 
301```dart
302CustomScrollView(
303  physics: const ClampingScrollPhysics(),
304  slivers: [
305    SliverList(
306      delegate: SliverChildListDelegate([
307        // Items
308      ]),
309    ),
310  ],
311)
312```
313 
314### Fixed Scroll
315 
316```dart
317CustomScrollView(
318  physics: const NeverScrollableScrollPhysics(),
319  slivers: [
320    SliverList(
321      delegate: SliverChildListDelegate([
322        // Items
323      ]),
324    ),
325  ],
326)
327```
328 
329### Platform-Adaptive Scroll
330 
331```dart
332CustomScrollView(
333  physics: const AlwaysScrollableScrollPhysics(),
334  slivers: [
335    SliverList(
336      delegate: SliverChildListDelegate([
337        // Items
338      ]),
339    ),
340  ],
341)
342```
343 
344## Custom Simulation
345 
346### Creating Custom Simulation
347 
348```dart
349class CustomSimulation extends Simulation {
350  final double target;
351 
352  CustomSimulation({required this.target});
353 
354  @override
355  double x(double time) {
356    // Calculate position at given time
357    return target * (1 - math.exp(-time / 0.5));
358  }
359 
360  @override
361  double dx(double time) {
362    // Calculate velocity (derivative) at given time
363    return target * math.exp(-time / 0.5) / 0.5;
364  }
365 
366  @override
367  bool isDone(double time) {
368    return dx(time).abs() < 0.01;
369  }
370}
371```
372 
373**Usage:**
374```dart
375_controller.animateWith(
376  CustomSimulation(target: 1.0),
377);
378```
379 
380### Decay Simulation
381 
382```dart
383class DecaySimulation extends Simulation {
384  final double velocity;
385 
386  DecaySimulation({required this.velocity});
387 
388  @override
389  double x(double time) {
390    return velocity * (1 - math.exp(-time));
391  }
392 
393  @override
394  double dx(double time) {
395    return velocity * math.exp(-time);
396  }
397 
398  @override
399  bool isDone(double time) {
400    return dx(time).abs() < 0.1;
401  }
402}
403```
404 
405## Combining Physics and Animation
406 
407### Spring with Fallback
408 
409```dart
410void animateWithSpring({
411  required AnimationController controller,
412  required double start,
413  required double end,
414}) {
415  try {
416    controller.animateWith(
417      SpringSimulation(
418        spring: const SpringDescription(
419          mass: 1.0,
420          stiffness: 200.0,
421          damping: 15.0,
422        ),
423        start: start,
424        end: end,
425        velocity: 0.0,
426      ),
427    );
428  } catch (e) {
429    // Fallback to linear animation
430    controller.animateTo(end);
431  }
432}
433```
434 
435### Spring with Completion Callback
436 
437```dart
438_controller.animateWith(
439  SpringSimulation(
440    spring: const SpringDescription(
441      mass: 1.0,
442      stiffness: 200.0,
443      damping: 15.0,
444    ),
445    start: 0.0,
446    end: 1.0,
447    velocity: 0.0,
448  ),
449);
450 
451_controller.addStatusListener((status) {
452  if (status == AnimationStatus.completed) {
453    // Animation complete
454  }
455});
456```
457 
458## Physics for Gestures
459 
460### Swipe to Dismiss with Physics
461 
462```dart
463class DismissibleWithPhysics extends StatefulWidget {
464  final Widget child;
465  final VoidCallback onDismiss;
466 
467  const DismissibleWithPhysics({
468    super.key,
469    required this.child,
470    required this.onDismiss,
471  });
472 
473  @override
474  State<DismissibleWithPhysics> createState() => _DismissibleWithPhysicsState();
475}
476 
477class _DismissibleWithPhysicsState extends State<DismissibleWithPhysics>
478    with SingleTickerProviderStateMixin {
479  late AnimationController _controller;
480  double _dragX = 0;
481  bool _isDismissing = false;
482 
483  @override
484  void initState() {
485    super.initState();
486    _controller = AnimationController.unbounded(vsync: this);
487  }
488 
489  @override
490  void dispose() {
491    _controller.dispose();
492    super.dispose();
493  }
494 
495  void _handlePanEnd(DragEndDetails details) {
496    final velocity = details.velocity.pixelsPerSecond.dx;
497    final screenWidth = MediaQuery.of(context).size.width;
498 
499    if (velocity.abs() > 500 || _dragX.abs() > screenWidth / 3) {
500      // Dismiss
501      _controller.fling(velocity: velocity / screenWidth);
502      _isDismissing = true;
503      _controller.addStatusListener((status) {
504        if (status == AnimationStatus.completed && _isDismissing) {
505          widget.onDismiss();
506        }
507      });
508    } else {
509      // Spring back
510      _controller.animateWith(
511        SpringSimulation(
512          spring: const SpringDescription(
513            mass: 1.0,
514            stiffness: 300.0,
515            damping: 15.0,
516          ),
517          start: _dragX,
518          end: 0,
519          velocity: velocity,
520        ),
521      );
522    }
523  }
524 
525  @override
526  Widget build(BuildContext context) {
527    return GestureDetector(
528      onPanUpdate: (details) {
529        if (!_controller.isAnimating) {
530          setState(() {
531            _dragX += details.delta.dx;
532          });
533        }
534      },
535      onPanEnd: _handlePanEnd,
536      child: AnimatedBuilder(
537        animation: _controller,
538        builder: (context, child) {
539          return Transform.translate(
540            offset: Offset(_dragX + _controller.value, 0),
541            child: child,
542          );
543        },
544        child: widget.child,
545      ),
546    );
547  }
548}
549```
550 
551## Performance Considerations
552 
553### Simulation Complexity
554 
555Physics simulations can be computationally expensive. Optimize by:
556 
557- Using simpler simulations when possible (e.g., linear interpolation)
558- Reducing simulation resolution
559- Caching simulation results
560- Using built-in physics widgets
561 
562### Spring Tuning
563 
564Finding the right spring parameters can be trial and error:
565 
5661. Start with moderate values (mass: 1.0, stiffness: 200, damping: 15)
5672. Adjust for feel:
568   - Too slow? Increase stiffness or decrease mass
569   - Too bouncy? Increase damping
570   - Not bouncy enough? Decrease damping or stiffness
5713. Test on real devices
572 
573## Debugging
574 
575### Visualize Physics
576 
577```dart
578void main() {
579  timeDilation = 5.0;  // Slow down physics
580  runApp(MyApp());
581}
582```
583 
584### Print Simulation Values
585 
586```dart
587_controller.addListener(() {
588  print('Position: ${_controller.value}');
589});
590 
591_controller.addStatusListener((status) {
592  print('Status: $status');
593});
594```
595 
596### Physics Inspector
597 
598Use Flutter DevTools to profile physics animations:
5991. Open Performance overlay
6002. Look for frame drops during physics simulations
6013. Identify expensive calculations
602 
603## Best Practices
604 
605### DO
606 
607- Use physics simulations for natural-feeling motion
608- Tune spring parameters for desired feel
609- Test on various devices and screen sizes
610- Profile performance with DevTools
611- Provide fallback animations for physics failures
612 
613### DON'T
614 
615- Use complex physics when simple curves suffice
616- Forget to handle simulation completion
617- Use overly bouncy animations (distracting)
618- Ignore accessibility (respect disable animations preference)
619- Assume physics simulation completes instantly
620 
621## Common Physics Patterns
622 
623### Bouncy Button Press
624 
625```dart
626_controller.animateWith(
627  SpringSimulation(
628    spring: const SpringDescription(
629      mass: 0.5,
630      stiffness: 500,
631      damping: 10,
632    ),
633    start: 1.0,
634    end: 0.9,
635    velocity: 0,
636  ),
637);
638```
639 
640### Swipeable Card
641 
642```dart
643_controller.fling(
644  velocity: details.velocity.pixelsPerSecond.dx / 1000,
645);
646```
647 
648### Pull to Refresh
649 
650```dart
651RefreshIndicator(
652  onRefresh: () async {
653    // Refresh data
654  },
655  child: ListView(...),
656)
657```
658 
659## Accessibility
660 
661- Respect `MediaQuery.disableAnimations` setting
662- Provide non-physics alternatives
663- Ensure physics animations don't cause motion sickness
664- Test with reduced motion settings
665 
666## Platform-Specific Physics
667 
668### Adaptive Scroll Physics
669 
670```dart
671class AdaptiveScrollPhysics extends ScrollPhysics {
672  const AdaptiveScrollPhysics({super.parent});
673 
674  @override
675  AdaptiveScrollPhysics applyTo(ScrollPhysics? ancestor) {
676    return AdaptiveScrollPhysics(parent: buildParent(ancestor));
677  }
678 
679  @override
680  SpringDescription get spring => Platform.isIOS
681      ? const SpringDescription(
682          mass: 0.5,
683          stiffness: 100,
684          damping: 10,
685        )
686      : const SpringDescription(
687          mass: 0.8,
688          stiffness: 150,
689          damping: 15,
690        );
691}
692```
693 
694**Usage:**
695```dart
696ListView(
697  physics: const AdaptiveScrollPhysics(),
698  children: [...],
699)
700```
701