Lenga Engine — Build Games with Modern PHP

Good examples include:

counting the score up to a new value
fading or tinting an image
moving a pause menu into view
filling a health or progress slider
nudging button text, colour, size, or outline for feedback

If you are new to tweening, read What Are Tweens? first.

Import the Tweening Classes

Most UI tween scripts need:

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\Vector2;
use Lenga\Engine\Tweening\EasingFunction;
use Lenga\Engine\Tweening\Tween;
use Lenga\Engine\Tweening\TweenOptions;
use Lenga\Engine\UI\Text;

Add the UI element classes you need, such as Image, Button, or Slider.

Move or Resize Any UI Element

Every UI element has a RectTransform, so the layout tween methods work with Text, Image, Button, Slider, and other UI elements.

Tween::uiMoveTo(
    $panel,
    new Vector2(0.0, 0.0),
    0.22,
    TweenOptions::make()
        ->unscaled()
        ->ease(EasingFunction::EaseOutCubic),
);

Use these methods for layout and placement:

Tween::uiMoveTo(...) or Tween::anchoredPositionTo(...)
Tween::uiSizeTo(...)
Tween::uiScaleTo(...)
Tween::uiRotateTo(...)
Tween::uiAnchorMinTo(...)
Tween::uiAnchorMaxTo(...)
Tween::uiPivotTo(...)

Use unscaled() for pause menus and overlays that should keep animating while gameplay is paused.

Tween a Score Text

Use uiTextNumberTo when the visible text should count toward a new number.

final class ScoreHud extends Behaviour
{
    public ?Text $scoreText = null;
    private int $displayedScore = 0;

    public function setScore(int $score): void
    {
        if (!$this->scoreText instanceof Text) {
            return;
        }

        Tween::uiTextNumberTo(
            $this->scoreText,
            $score,
            0.25,
            TweenOptions::make()->ease(EasingFunction::EaseOutQuad),
            decimals: 0,
        );

        $this->displayedScore = $score;
    }
}

You can also add a prefix or suffix:

Tween::uiTextNumberTo(
    $this->scoreText,
    1250,
    0.3,
    TweenOptions::make()->ease(EasingFunction::EaseOutQuad),
    decimals: 0,
    prefix: 'Score ',
);

This works with UI elements that display text, such as Text and Button.

Tween Colours

Use colour tweens when the user needs visible feedback.

Tween::uiColorTo(
    $backdrop,
    ['r' => 40, 'g' => 40, 'b' => 40, 'a' => 210],
    0.18,
    TweenOptions::make()
        ->unscaled()
        ->ease(EasingFunction::EaseOutQuad),
);

For specific UI parts, use the more descriptive helpers:

Tween::uiTextColorTo($resumeButton, ['r' => 255, 'g' => 255, 'b' => 255, 'a' => 255], 0.12);
Tween::uiBackgroundColorTo($resumeButton, ['r' => 20, 'g' => 120, 'b' => 180, 'a' => 255], 0.12);
Tween::uiOutlineColorTo($titleText, ['r' => 0, 'g' => 0, 'b' => 0, 'a' => 255], 0.12);

Tween a Slider Value

Sliders are useful for health bars, charge meters, loading indicators, and options screens.

Tween::uiValueTo(
    $healthBar,
    0.65,
    0.2,
    TweenOptions::make()->ease(EasingFunction::EaseOutQuad),
);

You can also tween slider colours:

Tween::uiFillColorTo($healthBar, ['r' => 255, 'g' => 80, 'b' => 80, 'a' => 255], 0.18);
Tween::uiHandleColorTo($volumeSlider, ['r' => 255, 'g' => 255, 'b' => 255, 'a' => 255], 0.18);

Tween Text Size or Button Outlines

For small feedback moments, tween scalar UI properties.

Tween::uiFontSizeTo(
    $titleText,
    42.0,
    0.14,
    TweenOptions::make()
        ->unscaled()
        ->ease(EasingFunction::EaseOutCubic),
);

For a button outline:

Tween::uiOutlineWidthTo($resumeButton, 3.0, 0.12);

Supported UI Targets

Layout tweens work on every UI element because every element has a RectTransform.

Property tweens target the properties that exist on the selected element:

Text: number text, font size, tint colour, outline colour
Image: tint colour
Button: number text, font size, text colour, background colour, hover colour, pressed colour, disabled colour, outline colour, outline width
Slider: value, background colour, fill colour, handle colour

If a tween helper does not match the selected element, use the helper that matches that element's actual role.

A Pause Menu Reveal

Pause menu tweens usually need unscaled time so they keep moving while gameplay is frozen.

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\Vector2;
use Lenga\Engine\Tweening\EasingFunction;
use Lenga\Engine\Tweening\Tween;
use Lenga\Engine\Tweening\TweenOptions;
use Lenga\Engine\UI\Image;
use Lenga\Engine\UI\Text;

final class PauseMenuAnimator extends Behaviour
{
    public ?Image $backdrop = null;
    public ?Text $title = null;

    public function show(): void
    {
        $options = TweenOptions::make()
            ->unscaled()
            ->ease(EasingFunction::EaseOutCubic);

        if ($this->backdrop instanceof Image) {
            Tween::uiColorTo($this->backdrop, ['r' => 40, 'g' => 40, 'b' => 40, 'a' => 210], 0.18, $options);
            Tween::uiScaleTo($this->backdrop, new Vector2(1.0, 1.0), 0.18, $options);
        }

        if ($this->title instanceof Text) {
            Tween::uiMoveTo($this->title, new Vector2(0.0, -90.0), 0.22, $options);
            Tween::uiTextColorTo($this->title, ['r' => 255, 'g' => 255, 'b' => 255, 'a' => 255], 0.18, $options);
        }
    }
}

Keep the gameplay rule separate from the presentation. For example, pause the game because the pause state changed, then use tweens to make that state change feel polished.

Animate UI with Tweens