⏯️The Animation System

Static UIs can feel rigid. To create a modern, fluid user experience, Paper includes a simple yet powerful animation system built on the concept of transitions. Instead of manually managing animation timers and interpolation, you simply declare which properties should animate, and for how long.

How it Works: The .Transition() Method

The animation system is centered around the .Transition() method. When you apply this to an element, you are telling Paper: "Whenever this property changes, don't jump to the new value instantly. Instead, smoothly animate from the old value to the new one over a specified duration."

The method signature is: .Transition(GuiProp property, double duration, Easing easingFunction = null)

• GuiProp property: The specific property you want to animate. This can be anything from GuiProp.BackgroundColor to GuiProp.Width or GuiProp.ScaleX.

• double duration: The time in seconds the animation should take.

• Easing easingFunction (Optional): An optional function to control the "feel" of the animation, making it accelerate, decelerate, or even bounce. We'll cover this below.

Animating a Simple Change

Let's see it in action. Here is a box that changes its background color based on a boolean. Without a transition, the change is instant and jarring.

// WITHOUT transition - instant change
paper.Box("ToggleButton")
    .BackgroundColor(isToggled ? Color.Green : Color.Red);

Now, let's add a transition. We only need to add one line:

// WITH transition - smooth change
paper.Box("ToggleButton")
    .BackgroundColor(isToggled ? Color.Green : Color.Red)
    .Transition(GuiProp.BackgroundColor, 0.3); // Animate the background color over 0.3s

That's it! Paper's animation engine will now automatically handle interpolating the color from red to green (and back) whenever the isToggled variable changes.

Combining with Conditional Styling

The real power of the animation system is unlocked when you combine it with conditional styling for interactive elements. This is how you create buttons that smoothly change color on hover or panels that animate their size.

The key is to define the transitions in the base style of the element.

paper.Box("AnimatedButton")
    // 1. Define the base styles
    .BackgroundColor(Color.Gray)
    .Scale(1.0)
    // 2. Define the transitions for the properties that will change
    .Transition(GuiProp.BackgroundColor, 0.2)
    .Transition(GuiProp.ScaleX, 0.2)
    .Transition(GuiProp.ScaleY, 0.2)
    // 3. Define the hover/active states that trigger the changes
    .Hovered
        .BackgroundColor(Color.CornflowerBlue)
        .End()
    .Active
        .Scale(0.9)
        .End();

In this example:

• When the mouse enters the box, BackgroundColor changes. Because a transition is defined for it, the color will smoothly animate from Gray to CornflowerBlue.

• When the mouse leaves, the Hovered condition becomes false, and the color animates back to Gray.

• When the mouse is pressed, ScaleX and ScaleY change, causing the button to smoothly shrink. It animates back to its normal size on release.

Easing Functions: Adding Personality

Animations with constant speed can feel robotic. Easing functions control the rate of change during an animation, allowing you to create effects that speed up, slow down, bounce, or overshoot.

You can provide an easing function as the third argument to the .Transition() method. Paper comes with a rich set of built-in functions in the static Easing class.

// This element will "snap" back with an elastic effect
paper.Box("BouncyBox")
    .Scale(1.0)
    .Transition(GuiProp.ScaleX, 0.5, Easing.ElasticOut) // Use an elastic easing
    .Transition(GuiProp.ScaleY, 0.5, Easing.ElasticOut)
    .Hovered
        .Scale(0.8)
        .End();

Here are some of the most common built-in easing functions:

• Linear: Constant speed (no easing).

• EaseIn: Starts slow, then speeds up.

• EaseOut: Starts fast, then slows down.

• EaseInOut: Starts slow, speeds up in the middle, and slows down at the end. (This is a great default choice).

• CubicIn, CubicOut, CubicInOut: More pronounced acceleration/deceleration curves.

• ElasticOut: Overshoots the target value and bounces back, like an elastic band.

• ...and many more.

By thoughtfully applying transitions and easing, you can make your UI not only more visually appealing but also more intuitive and satisfying for the user to interact with. Speaking of Interaction, we'll handle that on the next page.