Quaternion

Namespace:

namespace Lenga\Engine\Core;

class Quaternion

Quaternion is Lenga's 3D rotation value type. Use it for world and local Transform rotations, smooth rotation interpolation, direction-to-direction alignment, and rotating direction vectors without relying on Euler-angle addition.

Lenga's PHP API uses lower camelCase method names.

Properties

x

public float $x

X component of the quaternion.

y

public float $y

Y component of the quaternion.

z

public float $z

Z component of the quaternion.

w

public float $w

W component of the quaternion.

sqrMagnitude

public float $sqrMagnitude

Squared length of the quaternion.

magnitude

public float $magnitude

Length of the quaternion.

normalized

public Quaternion $normalized

Returns a normalized copy of the quaternion.

eulerAngles

public Vector3 $eulerAngles

Gets or sets the Euler-angle representation in degrees.

Constructors

public function __construct(float $x = 0.0, float $y = 0.0, float $z = 0.0, float $w = 1.0)

Creates a quaternion from raw x, y, z, and w components.

Static Methods

identity

public static function identity(): self

Returns the identity rotation.

euler

public static function euler(Vector3|float $x, ?float $y = null, ?float $z = null): self

Creates a quaternion from Euler angles in degrees. Pass either a Vector3 or three degree values.

fromEulerAngles

public static function fromEulerAngles(Vector3 $degrees): self

Creates a quaternion from Euler angles in degrees.

angleAxis

public static function angleAxis(float $angleDegrees, Vector3 $axis): self

Creates a rotation around an axis by an angle in degrees.

fromAxisAngle

public static function fromAxisAngle(Vector3 $axis, float $angleDegrees): self

Creates a rotation around an axis by an angle in degrees.

dot

public static function dot(Quaternion $a, Quaternion $b): float

Returns the dot product between two rotations.

angle

public static function angle(Quaternion $a, Quaternion $b): float

Returns the shortest angle in degrees between two rotations.

fromToRotation

public static function fromToRotation(Vector3 $fromDirection, Vector3 $toDirection): self

Creates a rotation that turns one direction into another direction.

lookRotation

public static function lookRotation(Vector3 $forward, ?Vector3 $upwards = null): self

Creates a rotation using a forward direction and optional upwards direction. In Lenga, Vector3::back() is the default forward direction used by Transform::$forward.

inverseOf

public static function inverseOf(Quaternion $rotation): self

Returns the inverse of a rotation.

normalizeRotation

public static function normalizeRotation(Quaternion $rotation): self

Returns a normalized copy of a rotation.

lerp

public static function lerp(Quaternion $a, Quaternion $b, float $t): self

Linearly interpolates between two rotations, clamps t to 0..1, and normalizes the result.

lerpUnclamped

public static function lerpUnclamped(Quaternion $a, Quaternion $b, float $t): self

Linearly interpolates between two rotations without clamping t, and normalizes the result.

slerp

public static function slerp(Quaternion $a, Quaternion $b, float $t): self

Spherically interpolates between two rotations and clamps t to 0..1.

slerpUnclamped

public static function slerpUnclamped(Quaternion $a, Quaternion $b, float $t): self

Spherically interpolates between two rotations without clamping t.

rotateTowards

public static function rotateTowards(Quaternion $from, Quaternion $to, float $maxDegreesDelta): self

Rotates from one orientation toward another by up to maxDegreesDelta.

Instance Methods

toEulerAngles

public function toEulerAngles(): Vector3

Converts the quaternion to Euler angles in degrees.

multiply

public function multiply(Quaternion $other): self

Combines this rotation with another rotation.

set

public function set(float $x, float $y, float $z, float $w): void

Sets the quaternion components.

setFromToRotation

public function setFromToRotation(Vector3 $fromDirection, Vector3 $toDirection): void

Replaces this quaternion with a rotation that turns one direction into another direction.

setLookRotation

public function setLookRotation(Vector3 $forward, ?Vector3 $upwards = null): void

Replaces this quaternion with a look rotation.

toAngleAxis

public function toAngleAxis(): array

Returns an array with angle in degrees and axis as a Vector3.

inverse

public function inverse(): self

Returns the inverse rotation.

rotateVector

public function rotateVector(Vector3 $vector): Vector3

Rotates a direction or offset vector by this quaternion.

normalize

public function normalize(): self

Normalizes this quaternion in place and returns it.

equals

public function equals(Quaternion $other): bool

Performs exact component equality.

__toString

public function __toString(): string

Returns a readable component string.

Index Access

Quaternion supports array-style access:

$rotation[0];     // x
$rotation[1];     // y
$rotation[2];     // z
$rotation[3];     // w
$rotation['w'];   // w

Example

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\Quaternion;
use Lenga\Engine\Core\Time;
use Lenga\Engine\Core\Vector3;

final class TurretAim extends Behaviour
{
    public function update(): void
    {
        $targetRotation = Quaternion::lookRotation($this->targetDirection());

        $this->transform->rotation = Quaternion::rotateTowards(
            $this->transform->rotation,
            $targetRotation,
            120.0 * Time::deltaTime(),
        );
    }

    private function targetDirection(): Vector3
    {
        return Vector3::back();
    }
}