DOCSEARCHbyAlgolia
Submit Docs

LitMotion Documentation

repository·main·Indexed 24 days ago

https://github.com/annulusgames/litmotion

A high-performance, zero-allocation tweening library for Unity (version 2.0.2) utilizing a struct-based design and DOTS optimization. It features LMotion for motion creation, LSequence for chaining animations, and specialized support for TextMeshPro. The library provides integration with UniTask, R3 Observables, and Unity's Awaitable class, while offering tools like MotionDispatcher.EnsureStorageCapacity to mitigate runtime dynamic memory allocation.

Tokens
24.2K
Snippets
105
Records
147
Agent score
78%

What's inside LitMotion

  1. Overview of LitMotion features and performance

    main

    LitMotion is a high-performance tweening library for Unity designed to animate components (like Transform), custom fields, and properties.

    Key characteristics include:

    • High Performance: Optimized using Unity's DOTS (C# Job System and Burst Compiler), performing 2-20x faster than other libraries in various scenarios.
    • Zero Allocations: Uses a struct-based design to ensure no allocations during tween creation.
    • Versatility: Works in both runtime and editor, supports easing, looping, and special motions like Punch and Shake.
    • Async/Await Support: Fully compatible with UniTask for asynchronous workflows.
    • Extensibility: Supports type extension via IMotionOptions and IMotionAdapter.
    • Sequencing: Use LSequence to combine multiple motions into a single sequence.
    • Inspector Integration: The LitMotion.Animation package allows creating complex animations directly from the Unity Inspector.

  2. Overview of LitMotion.Animation

    main

    LitMotion.Animation is an extension package for LitMotion that provides high-performance animation functionality. Its primary purpose is to bridge the gap between code-based animations and the Unity Inspector, allowing developers to build and preview animations visually.

    Key capabilities include:

    • Inspector-driven animations: Create and configure animations directly within the Unity Inspector.
    • Visual Preview: Preview animation playback in both Edit Mode and Play Mode.
    • Extensibility: Developers can create custom animation extensions by inheriting from the LitMotionAnimationComponent class.

  3. Understand the LitMotion package structure

    main

    LitMotion is organized into several namespaces and packages to separate core motion logic from Unity-specific integrations and editor tools:

    • LitMotion: The core namespace containing essential functionalities for creating and driving motions.
    • LitMotion.Adapters: Provides adapters for Unity-specific types, such as primitive types and Vector3.
    • LitMotion.Editor: Contains tools for operating and managing motions within the Unity Editor.
    • LitMotion.Extensions: Provides extension methods for binding motions to Unity components. Note that these are contained in a separate Assembly Definition (asmdef) file.
    • LitMotion.Animation: A separate, optional package that provides high-level animation functionality. It includes the LitMotion Animation component, which enables creating complex animations directly via the Unity Inspector.

  4. Adding callbacks to a Sequence

    main

    LitMotion's Sequence does not implement an AppendCallback() method (unlike DOTween). The Sequence abstraction is strictly designed for combining multiple motions to reduce complexity.

    To execute logic at specific points in a sequence, it is recommended to use async/await patterns instead of attempting to inject callbacks directly into the sequence object.

  7. Combine multiple motions using LSequence

    main

    A LSequence allows you to combine multiple motions into a single complex animation. You build a sequence using LSequence.Create(), chain various motion addition methods, and then execute it by calling .Run().

    Calling .Run() returns a MotionHandle, meaning a sequence can be controlled (e.g., cancelled or completed) just like any individual motion.

    WARNING

    You cannot add motions that are already playing or those with infinite loops to a sequence. Doing so will cause an exception.

    LSequence.Create()
    .Append(LMotion.Create(0f, 1f, 1f).BindToPositionX(transform))
    .Join(LMotion.Create(0f, 1f, 1f).BindToPositionY(transform))
    .Insert(0f, LMotion.Create(0f, 1f, 1f).BindToPositionZ(transform))
    .Run();

  9. Use MotionSettings for reusable motion configurations

    main

    You can use MotionSettings<T, TOptions> to store and reuse motion configuration settings. The type arguments T represents the type of the value to animate, and TOptions represents the options type (e.g., NoOptions, IntegerOptions, StringOptions, PunchOptions, ShakeOptions).

    You can create settings in two ways:

    1. Object Initializer: Directly instantiating the record.
    2. MotionBuilder: Using the ToMotionSettings() extension method on an existing motion builder.

    Once created, you can pass the settings object directly into LMotion.Create() to start a motion.

    // Created using an object initializer
var settings = new MotionSettings<float, NoOptions>
{
    StartValue = 0f,
    EndValue = 10f,
    Duration = 2f,
    Ease = Ease.OutQuad
};

// Created using MotionBuilder
var settings = LMotion.Create(0f, 10f, 2f)
    .WithEase(Ease.OutQuad)
    .ToMotionSettings();

// Use the settings in a new motion
LMotion.Create(settings)
    .Bind(x => { });

  10. Construct motions using MotionBuilder

    main

    A MotionBuilder is a structure used to configure and construct motions. You obtain an instance by calling LMotion.Create(). It supports method chaining to apply configurations like easing, delays, and loops. To actually execute the motion, you must typically use .Bind() to connect the motion to a value or a callback.

    LMotion.Create(0f, 10f, 3f)
    .WithEase(Ease.OutQuad)
    .WithDelay(2f)
    .WithLoops(4, LoopType.Yoyo)
    .Bind(x => value = x);

  11. Extend interpolation with MotionAdapter

    main

    Interpolation logic (how values transition between points) is handled by MotionAdapter implementations of the IMotionAdapter<T, TOptions> interface.

    • Built-in Adapters: Located in the LitMotion.Adapters namespace.
    • Customization: You can create custom interpolation logic by implementing IMotionAdapter<T, TOptions> and defining a corresponding structure that implements IMotionOptions for specific configuration settings.

  12. Compare LitMotion with DOTween and Magic Tween

    main

    When choosing between tweening libraries, consider the following trade-offs:

    FeatureLitMotionDOTween / Magic Tween
    Performance~5x faster than DOTween; ~1.5x faster than Magic Tween; Zero allocations.Standard performance profiles.
    API StyleUnified entry point via the LMotion class; uses method chaining.Often uses extension methods on components.
    Feature SetCurated and 'Simple' to maintain high performance and readability.Often includes a larger number of built-in functionalities.

    LitMotion prioritizes API simplicity and performance by avoiding component extension methods, instead unifying all motion creation through the LMotion class.