TrailRenderer

Namespace:

namespace Lenga\Engine\Core;

final class TrailRenderer extends Component

TrailRenderer draws a ribbon behind a moving GameObject. It samples the owner transform as it moves, keeps those points for time seconds, and renders the newest part with startWidth/startColor fading toward endWidth/endColor.

Constants

public const string ALIGNMENT_VIEW = 'View';
public const string ALIGNMENT_TRANSFORM_Z = 'TransformZ';

Use View for camera-facing 3D trails. Use TransformZ when the ribbon should follow the GameObject orientation.

Properties

time

public float $time { get; set; }

How long trail points remain alive, in seconds.

minVertexDistance

public float $minVertexDistance { get; set; }

Minimum world distance before a new point is added.

emitting

public bool $emitting { get; set; }

When false, the trail stops adding new points while existing points continue to fade out.

autodestruct

public bool $autodestruct { get; set; }

When enabled, the owner GameObject is destroyed after the trail has been stationary for time seconds, or after emission stops and the remaining trail has expired.

startWidth

public float $startWidth { get; set; }

Width at the newest point in the trail.

endWidth

public float $endWidth { get; set; }

Width at the oldest point in the trail.

widthMultiplier

public float $widthMultiplier { get; set; }

Overall multiplier applied to the trail width.

alignment

public string $alignment { get; set; }

Accepts TrailRenderer::ALIGNMENT_VIEW or TrailRenderer::ALIGNMENT_TRANSFORM_Z.

sortingLayer

public string $sortingLayer { get; set; }

Controls 2D sorting.

orderInLayer

public int $orderInLayer { get; set; }

Controls draw order within the selected 2D sorting layer.

maxPoints

public int $maxPoints { get; set; }

Caps the internal point buffer.

positionCount

public int $positionCount { get; }

Returns the number of stored trail points.

Methods

clear

public function clear(): void

Removes all trail points immediately.

addPosition

public function addPosition(Vector3 $position): void

Adds a world-space point manually.

getPosition

public function getPosition(int $index): ?Vector3

Returns a stored point by index, or null if the index is out of range.

getStartColor

public function getStartColor(): array

Returns ['r' => int, 'g' => int, 'b' => int, 'a' => int].

setStartColor

public function setStartColor(int $red, int $green, int $blue, int $alpha = 255): void

getEndColor

public function getEndColor(): array

Returns ['r' => int, 'g' => int, 'b' => int, 'a' => int].

setEndColor

public function setEndColor(int $red, int $green, int $blue, int $alpha = 255): void

getState

public function getState(): array

Returns the current trail state. Prefer named properties and methods for gameplay code.

Example

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\TrailRenderer;

final class BallTrail extends Behaviour
{
    private ?TrailRenderer $trail = null;

    public function start(): void
    {
        $this->trail = $this->getComponent(TrailRenderer::class);

        $this->trail->time = 0.45;
        $this->trail->startWidth = 0.5;
        $this->trail->endWidth = 0.0;
        $this->trail->setStartColor(255, 255, 255, 255);
        $this->trail->setEndColor(0, 191, 255, 0);
    }

    public function onRespawn(): void
    {
        $this->trail?->clear();
    }
}

For an editor workflow, see Add Motion Trails.