Skip to content

Add Spring Animation Support#247

Open
Rotanticu wants to merge 64 commits intoannulusgames:mainfrom
Rotanticu:main
Open

Add Spring Animation Support#247
Rotanticu wants to merge 64 commits intoannulusgames:mainfrom
Rotanticu:main

Conversation

@Rotanticu
Copy link

Hi! Bro! Also remember issues188
I now finally have enough time and motivation to finish it!

This PR introduces physics-based spring animations to LitMotion, bringing natural and responsive motion that simulates real-world spring physics.

🎯 What are Spring Animations?

Spring animations are physics-based animations that simulate the behavior of real-world springs. Unlike traditional linear or easing-based animations, spring animations create motion that starts with high velocity and gradually settles into the target position, mimicking natural physical laws. This creates a more organic and intuitive user experience that feels connected to the real world.

As demonstrated in Apple's Spring Animation Design Principles, spring animations are fundamental to creating fluid, responsive interfaces that users find natural and engaging.

🚀 Why Spring Animations are Superior to Traditional Tweens

1. Natural Physics Simulation

  • Tween: Linear or curved interpolation between start and end values
  • Spring: Realistic physics with acceleration, deceleration, and natural settling

2. Velocity Preservation

  • Tween: Abrupt stops when interrupted, losing all momentum
  • Spring: Smooth transitions that preserve velocity when changing targets

3. Dynamic Response

  • Tween: Fixed duration and easing curve regardless of distance
  • Spring: Adaptive motion that responds to target distance and current velocity

4. Continuous Tracking

  • Tween: Requires manual recreation for target changes
  • Spring: Can continuously track moving targets with natural physics

🚀 Usage Examples

// Basic spring animation - much more natural than linear tweens
var motion = LMotion.Spring.Create(0f, 100f, SpringOptions.Critical)
    .Bind(value => transform.position.x = value);

// Continuous tracking - impossible with traditional tweens
var followMotion = LMotion.Spring.Create(currentPos, mousePos, SpringOptions.Overdamped)
    .WithLoops(-1, LoopType.Incremental)
    .Bind(value => transform.position = value);

// Custom physics parameters for fine-tuned control
var options = new SpringOptions(stiffness: 15f, dampingRatio: 0.8f);
var motion = LMotion.Spring.Create(Vector3.zero, targetPosition, options)
    .Bind(value => transform.position = value);

🔧 Implementation Details

  • Backward Compatible: Existing LitMotion code continues to work unchanged
  • Zero GC Design: Uses structs and value types for memory efficiency
  • Burst Optimized: Leverages Unity's Burst compiler for maximum performance
  • SIMD Accelerated: Utilizes float4 operations for vectorized calculations

🧪 Testing

Comprehensive test cases and examples are available in Assets\LitMotion\samples\LitMotion.Spring, including:

  • Visual demonstration comparing spring vs traditional tween animations
  • Performance benchmarks showing spring superiority
  • Interactive parameter adjustment tools
  • Multi-language support (English, Chinese, Japanese)

Test results show that the Spring implementation maintains LitMotion's high performance goal. 1,000,000 Spring animations even consume less energy than Tween!

📚 Documentation

I've uploaded three documents: the description, API documentation, and feature documentation. When you merge them, you can update them into the original documents!

legoritma and others added 30 commits March 18, 2025 14:11
Introduces DurationBasedAnimationSpec, LoopBasedAnimationSpec, SpringAnimationSpec, TweenAnimationSpec, and IVectorizedAnimationSpec to define and implement various animation behaviors and interfaces for LitMotion. These additions provide a foundation for duration-based, loop-based, spring, and tween animations with vectorized support.
I initially wrote these two, but now I think they may not be necessary. Using IVectorizedAnimationSpec and VectorX should suffice as replacements. Anyway, I'll submit them first, and wait until I decide whether they are needed before pushing them
现在来看,我受compose影响太大了。
游戏开发不需要像移动端的函数式编程那样,搞一堆类出来
也不需要什么VectorXD,C#有Vector和结构体,不需要这些东西
我应该只需要改动最核心的Update,增加速度向量就好了

这次的修改作为废弃分支,从新开始做第二次重构
可能用到的弹簧算法
暂时不知道为什么float比double慢一倍,先改成都用double了
增加了阻尼比和刚度的推荐值
按照原有的方式增加了Spring动画类型
按现在的写法性能会稍差,毕竟正常来说应该把热点逻辑和Tween一样放在update里
不过先按照第一版用着吧,先跑起来再说
@nuskey8
Copy link
Member

nuskey8 commented Dec 20, 2025

Thank you for your PR.

First, please do not include unnecessary code. Also, please write all documentation comments in English.

@Rotanticu
Copy link
Author

Thank you for your PR.

First, please do not include unnecessary code. Also, please write all documentation comments in English.

Great to see you back! I'll deal with these later!

@Rotanticu
Copy link
Author

Thank you for your PR.

First, please do not include unnecessary code. Also, please write all documentation comments in English.

First of all, Merry Christmas and Happy New Year!

I finally have time to work on this PR!

I previously thought this project was no longer maintained, so I merged code from other PRs without authorization. However, I've now restored all the merged code.

I've temporarily deleted the documentation and test folders; perhaps I can add more formal test code and documentation later.

I've also added explanations to all my code changes. Some are necessary, and some require discussion.

This is my first attempt at contributing code to another open-source library, so I hope you don't mind. Conversely, if you have any complaints, or if I've made any silly mistakes, please let me know!

Finally, what type of developer are you? Are you very strict about merging code, requiring it to perfectly match the style of the original project? Or do you welcome such large feature modifications? I'd like to understand your development style for better collaboration. @nuskey8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants