Text

Namespace:

namespace Lenga\Engine\UI;

final class Text extends UIElement

Text is the UI element you use for labels, score counters, instructions, menu titles, and other screen-space text. It inherits the common layout and hierarchy features from UIElement, including rectTransform, visible, name, and setParent(...).

Where Text Code Lives

Most Text code lives inside a Behaviour class attached to a scene GameObject.

For example, you might create a HUDController object in your scene, attach a HUDController Behaviour to it, then let that Behaviour find a canvas and update the Score Label text element.

The Text element does not need to live on the same GameObject as the Behaviour. The common workflow is:

1. Put your UI elements under a Canvas.
2. Attach a controller Behaviour to a normal scene GameObject, such as GameManager or HUDController.
3. In the Behaviour, ask the active scene for the canvas.
4. Find the text element by name.
5. Update the text from start() or update().

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\SceneManagement\Scene;
use Lenga\Engine\UI\Text;

final class HUDController extends Behaviour
{
    private ?Text $scoreLabel = null;

    public function start(): void
    {
        $canvas = Scene::getActive()?->findCanvas('Canvas');
        $this->scoreLabel = $canvas?->findTextByName('Score Label');

        if ($this->scoreLabel !== null) {
            $this->scoreLabel->text = 'Score: 0';
        }
    }
}

If your code already has a direct Text reference from another API, you can use that reference directly. You only need Scene::getActive()?->findCanvas(...) when you are starting from the scene and need to look up a UI element by name.

Properties

Colour Methods

Text colour is read and written through methods rather than a direct property.

public function getColor(): array
public function setColor(int $red, int $green, int $blue, int $alpha = 255): void

getColor() returns:

array{r:int, g:int, b:int, a:int}

Example:

$label->setColor(255, 255, 255, 255);

Outline State for Raster Text

These methods expose the outline settings used when a Text element renders with a normal .ttf or .otf font:

public function getOutlineColor(): array
public function getOutlineDistance(): array

These outline settings are useful when you are using a normal .ttf or .otf font directly. For the crispest scalable outlines, generate an SDF font asset and use $sdfOutlineWidth instead.

SDF Font Workflow

For beginner-friendly editor steps, see Generate SDF Fonts for Crisp UI Text.

The short version is:

1. Import a .ttf or .otf font into your project.
2. Right-click the font in the Assets panel.
3. Choose Generate SDF Font.
4. Assign the generated .sdf-font.json file to the Font field on a Text element.
5. Tune SDF Outline and SDF Softness on that Text element.

You can also set those values from PHP:

$title->fontPath = 'Assets/Fonts/MenuTitle.sdf-font.json';
$title->useSdf = true;
$title->sdfOutlineWidth = 3.0;
$title->sdfSoftness = 0.75;

If fontPath points to a normal .ttf or .otf file and useSdf is false, Lenga uses the standard raster font rendering path.

Complete Example

This example belongs inside a Behaviour attached to a normal scene GameObject, such as HUDController.

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\Input;
use Lenga\Engine\Core\KeyCode;
use Lenga\Engine\SceneManagement\Scene;
use Lenga\Engine\UI\Text;

final class ScoreDisplay extends Behaviour
{
    private int $score = 0;
    private ?Text $scoreLabel = null;

    public function start(): void
    {
        $canvas = Scene::getActive()?->findCanvas('Canvas');
        $this->scoreLabel = $canvas?->findTextByName('Score Label');

        if ($this->scoreLabel !== null) {
            $this->scoreLabel->text = 'Score: 0';
            $this->scoreLabel->fontSize = 36.0;
            $this->scoreLabel->fontPath = 'Assets/Fonts/HUD.sdf-font.json';
            $this->scoreLabel->useSdf = true;
            $this->scoreLabel->sdfOutlineWidth = 2.0;
            $this->scoreLabel->sdfSoftness = 0.5;
            $this->scoreLabel->setColor(255, 255, 255, 255);
        }
    }

    public function update(): void
    {
        if (Input::getKeyDown(KeyCode::SPACE)) {
            $this->score += 10;
            $this->scoreLabel?->text = 'Score: ' . $this->score;
        }
    }
}