Vector3

3D vector value type with mutating and pure helper operations.

Namespace:

namespace Lenga\Engine\Core;

class Vector3

Methods

zero

public static function zero()

Vector with all components set to 0.

one

public static function one()

Vector with all components set to 1.

up

public static function up()

Unit vector pointing up (0, 1, 0).

down

public static function down()

Unit vector pointing down (0, -1, 0).

left

public static function left()

Unit vector pointing left (-1, 0, 0).

right

public static function right()

Unit vector pointing right (1, 0, 0).

forward

public static function forward()

Unit vector pointing forward (0, 0, 1).

back

public static function back()

Unit vector pointing back (0, 0, -1).

negativeInfinity

public static function negativeInfinity()

Shorthand for Vector3(-INF, -INF, -INF).

positiveInfinity

public static function positiveInfinity()

Shorthand for Vector3(INF, INF, INF).

add

public function add(Vector3 $other)

Adds another vector to this vector in place.

subtract

public function subtract(Vector3 $other)

Subtracts another vector from this vector in place.

multiply

public function multiply(Vector3 $other)

Multiplies this vector component-wise by another vector in place.

divide

public function divide(Vector3 $other)

Divides this vector component-wise by another vector in place.

scale

public function scale(float $scalar)

Scales this vector by a scalar in place.

normalize

public function normalize()

Normalizes the vector to have a magnitude of 1 in place.

set

public function set(float $x, float $y, float $z)

Sets the x, y, and z components of this vector.

clone

public function clone()

Creates and returns a clone of this vector.

equals

public function equals(Vector3 $other)

Checks if this vector is exactly equal to another vector.

__toString

public function __toString()

Returns a formatted string representation of this vector.

toVector4

public function toVector4(float $w = 0.0)

Converts this Vector3 to a Vector4 with an optional w component.

toVector2

public function toVector2()

Converts this Vector3 to a Vector2 by dropping the z component.

toArray

public function toArray()

@return array{x: float, y: float, z: float}

fromArray

public static function fromArray(array $data)

@param array{x?: float, y?: float, z?: float} $data

fromVector4

public static function fromVector4(Vector4 $vector)

Builds a Vector3 from a Vector4 by dropping the w component.

fromVector2

public static function fromVector2(Vector2 $vector, float $z = 0.0)

Builds a Vector3 from a Vector2 with an optional z component.

sum

public static function sum(Vector3 $a, Vector3 $b)

Returns the sum of two vectors.

difference

public static function difference(Vector3 $a, Vector3 $b)

Returns the difference of two vectors.

product

public static function product(Vector3 $a, Vector3 $b)

Multiplies two vectors component-wise and returns the result.

quotient

public static function quotient(Vector3 $a, Vector3 $b)

Returns the quotient of two vectors.

scaleNew

public static function scaleNew(Vector3 $vector, float $scalar)

Returns a new vector scaled by a scalar.

dot

public static function dot(Vector3 $a, Vector3 $b)

Returns the dot product of two vectors.

cross

public static function cross(Vector3 $a, Vector3 $b)

Returns the cross product of two vectors.

angle

public static function angle(Vector3 $from, Vector3 $to)

Returns the unsigned angle in degrees between two vectors.

signedAngle

public static function signedAngle(Vector3 $from, Vector3 $to, Vector3 $axis)

Returns the signed angle in degrees between two vectors around an axis.

distance

public static function distance(Vector3 $a, Vector3 $b)

Returns the distance between two points.

lerp

public static function lerp(Vector3 $a, Vector3 $b, float $t)

Linearly interpolates between two vectors by t, clamped to [0, 1],

lerpUnclamped

public static function lerpUnclamped(Vector3 $a, Vector3 $b, float $t)

@var array{x: float, y: float, z: float}|false $result */

slerp

public static function slerp(Vector3 $a, Vector3 $b, float $t)

Spherically interpolates between two vectors, treating them as directions.

slerpUnclamped

public static function slerpUnclamped(Vector3 $a, Vector3 $b, float $t)

@var array{x: float, y: float, z: float}|false $result */

max

public static function max(Vector3 $a, Vector3 $b)

Returns a vector made from the largest components of two vectors.

min

public static function min(Vector3 $a, Vector3 $b)

Returns a vector made from the smallest components of two vectors.

clampMagnitude

public static function clampMagnitude(Vector3 $vector, float $maxLength)

Returns a copy of vector with its magnitude clamped to maxLength.

moveTowards

public static function moveTowards(Vector3 $current, Vector3 $target, float $maxDelta)

Moves current towards target by at most maxDelta.

project

public static function project(Vector3 $vector, Vector3 $onNormal)

Projects a vector onto another vector.

projectOnPlane

public static function projectOnPlane(Vector3 $vector, Vector3 $planeNormal)

Projects a vector onto a plane defined by a normal.

reflect

public static function reflect(Vector3 $inDirection, Vector3 $inNormal)

Reflects a vector off the plane defined by a normal vector.

rotateTowards

public static function rotateTowards(Vector3 $current,
        Vector3 $target,
        float $maxRadiansDelta,
        float $maxMagnitudeDelta,)

Rotates current towards target by an angular step, while also moving the

smoothDamp

public static function smoothDamp(Vector3 $current,
        Vector3 $target,
        Vector3 &$currentVelocity,
        float $smoothTime,
        float $maxSpeed = PHP_FLOAT_MAX,
        ?float $deltaTime = null,)

Gradually changes a vector towards a target over time using a spring-like damper.

orthoNormalize

public static function orthoNormalize(Vector3 &$normal, Vector3 &$tangent)

@var array{

offsetExists

public function offsetExists(mixed $offset)

Checks whether an array offset maps to a valid vector component.

offsetGet

public function offsetGet(mixed $offset)

Gets a vector component by index: 0|'x' => x, 1|'y' => y, 2|'z' => z.

offsetSet

public function offsetSet(mixed $offset, mixed $value)

Sets a vector component by index: 0|'x' => x, 1|'y' => y, 2|'z' => z.

offsetUnset

public function offsetUnset(mixed $offset)

Unsets a vector component by index.

Example

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

class Movement3D extends Behaviour
{
    public function update(): void
    {
        // Create vectors for positions and directions
        $position = $this->transform->position;
        $target = new Vector3(10, 0, 10);

        // Calculate direction and distance
        $direction = Vector3::subtract($target, $position)->normalized();
        $distance = Vector3::distance($position, $target);

        // Move towards target
        $moveAmount = 5.0 * Time::deltaTime();
        $newPosition = Vector3::add($position, Vector3::scale($direction, $moveAmount));
        $this->transform->position = $newPosition;

        // Perform vector operations
        $velocity = new Vector3(1, 0, 0);
        $gravity = new Vector3(0, -9.8, 0);
        $netForce = Vector3::add($velocity, Vector3::scale($gravity, Time::deltaTime()));

        // Cross product and rotation
        $forward = $this->transform->forward;
        $up = new Vector3(0, 1, 0);
        $right = Vector3::cross($forward, $up);
    }
}