Element category: Vector

Represents a 3D Vector. Used for storing and manipulating three-dimensional coordinates (x, y, z).

OOP-Only Methods and Variables

create

Default constructor for the Vector3 class. Returns a Vector3 object.

​Vector3 create ( ​float|​table|​Vector3 vectorOrX, [ ​float y = 0, ​float z = 0 ] )

• vectorOrX: Vector3, table, or floats indicating vector's coordinates.
• y: If vectorOrX is a float, this is the Y coordinate.
• z: If vectorOrX is a float, this is the Z coordinate.

cross

Calculates the cross product of two vectors. The result is a vector orthogonal to both.

​Vector3|false cross ( ​Vector3 vectorA, ​Vector3 vectorB )

• vectorA: Source vector.
• vectorB: Vector to calculate the cross product with.

dot

Calculates the dot (scalar) product of two vectors.

​float|false dot ( ​Vector3 vectorA, ​Vector3 vectorB )

• vectorA: Source vector.
• vectorB: Vector to calculate the dot product with.

getX

Returns the X component of the vector.

​float|false getX ( ​Vector3 vector )

• vector: Vector3 to get X coordinate from.

Variable: .x

setX

Sets the X component of the vector.

​bool setX ( ​Vector3 vector, ​float x )

• vector: Vector3 to set X coordinate on.
• x: The new X value.

Variable: .x

getY

Returns the Y component of the vector.

​float|false getY ( ​Vector3 vector )

• vector: Vector3 to get Y coordinate from.

Variable: .y

setY

Sets the Y component of the vector.

​bool setY ( ​Vector3 vector, ​float y )

• vector: Vector3 to set Y coordinate on.
• y: The new Y value.

Variable: .y

getZ

Returns the Z component of the vector.

​float|false getZ ( ​Vector3 vector )

• vector: Vector3 to get Z coordinate from.

Variable: .z

setZ

Sets the Z component of the vector.

​bool setZ ( ​Vector3 vector, ​float z )

• vector: Vector3 to set Z coordinate on.
• z: The new Z value.

Variable: .z

normalize

Normalizes the vector to a unit vector (length of 1). Modifies the original vector.

​bool normalize ( ​Vector3 vector )

• vector: Vector3 to normalize.

getNormalized

Returns a normalized version of the vector without modifying the original.

​Vector3|false getNormalized ( ​Vector3 vector )

• vector: Vector3 to get normalized version of.

Variable: .normalized

getLength

Returns the length (magnitude) of the vector.

​float|false getLength ( ​Vector3 vector )

• vector: Vector3 to get length from.

Variable: .length

getSquaredLength

Returns the squared length of the vector (useful to avoid square root operations).

​float|false getSquaredLength ( ​Vector3 vector )

• vector: Vector3 to get squared length from.

Variable: .squaredLength

intersectsSegmentTriangle

Determines if a line segment intersects with a triangle.

​Vector3|false intersectsSegmentTriangle ( ​Vector3 origin, ​Vector3 segmentDir, ​Vector3 triVert0, ​Vector3 triVert1, ​Vector3 triVert2 )

• origin: Origin point of the segment.
• segmentDir: The direction vector of the segment.
• triVert0: First vertex of the triangle.
• triVert1: Second vertex of the triangle.
• triVert2: Third vertex of the triangle.

Code Examples

Example 1 Example 2 Example 3 Example 4 Example 5

shared

This example sorts all players in a nice line on the center of the map.

local players = getElementsByType("player")
local newPlayerPosition = Vector3(-#players - 1, 0, 10) -- Initialize the position vector for the first player in the list
for _, player in ipairs(players) do
    -- Move each player 1 unit forward in X from the previous one

    newPlayerPosition.x = newPlayerPosition.x + 1
    -- OR
    --newPlayerPosition:setX(newPlayerPosition.x + 1)
    -- OR
    --Vector3.setX(newPlayerPosition, newPlayerPosition.x + 1)

    setElementPosition(player, newPlayerPosition)
end

client

This example creates a tiny sun which is always at the right of the vehicle the local player drives. By default it will draw the vectors used to compute the position where it should be, so you can understand what does this function do. Note that the code could be made simpler by simply getting the right component of the vehicle matrix. Make sure that you put this code in a resource which has OOP enabled, or it won't work.

-- OPTIONS --
local debugMode = true -- If true, the script will draw the vectors used to compute the effect

-- EFFECT CONTROL FUNCTIONS --
local playerVehicle, lightMarker, light
local function applyDrivingLightEffect()
    -- Get the vehicle matrix and use it to get the vehicle and vehicle base position
    local vehicleMatrix = playerVehicle.matrix
    local vehiclePosition = vehicleMatrix:getPosition()
    -- Get the vehicle upwards vector and vehicle forward direction vector
    local vehicleUpwardsVector, vehicleForwardVector = vehicleMatrix:getUp(), vehicleMatrix:getForward()
    -- Get the normalized cross product of the vehicle forward vector and the vehicleUpwardsVector vector
    local crossVector = vehicleForwardVector:cross(vehicleUpwardsVector):getNormalized()
    -- Draw all the interesting vectors we have now
    if debugMode then
        local forwardPoint = vehiclePosition + vehicleForwardVector
        dxDrawLine3D(vehiclePosition, forwardPoint, tocolor(255, 0, 0))
        local sx, sy = getScreenFromWorldPosition(forwardPoint)
        if sx then
            dxDrawText("F", sx, sy)
        end

        local vehicleUpwardsVectorPoint = vehiclePosition + vehicleUpwardsVector
        dxDrawLine3D(vehiclePosition, vehicleUpwardsVectorPoint, tocolor(0, 255, 0))
        local sx, sy = getScreenFromWorldPosition(vehicleUpwardsVectorPoint, 1.1)
        if sx then
            dxDrawText("U", sx, sy)
        end

        local crossPoint = vehiclePosition + crossVector
        dxDrawLine3D(vehiclePosition, crossPoint, tocolor(0, 0, 255))
        local sx, sy = getScreenFromWorldPosition(crossPoint)
        if sx then
            dxDrawText("C", sx, sy)
        end
    end
    -- Calculate the half length of the vehicle based in its bounding box, and use it to position the light effects at the right
    local _, bmy, _, _, bMy = playerVehicle:getBoundingBox()
    local newEffectPosition = vehiclePosition + crossVector * (bMy - bmy) / 2
    lightMarker.position = newEffectPosition
    light.position = newEffectPosition
end

local function startDrivingLightEffect()
    -- Create the effects and start updating them every frame
    addEventHandler("onClientPreRender", root, applyDrivingLightEffect)
    playerVehicle, lightMarker, light = localPlayer.vehicle, createMarker(0, 0, 0, "corona", 0.5, 255, 255, 0), createLight(0, 0, 0, 0, 8, 255, 255)
    -- If we are in debug mode, render the vehicle invisible to see the vectors clearly
    if debugMode then
        playerVehicle.alpha = 0
    end
end

local function stopDrivingLightEffect()
    -- Stop applyDrivingLightEffect from being called and destroy everything created
    removeEventHandler("onClientPreRender", root, applyDrivingLightEffect)
    destroyElement(lightMarker)
    destroyElement(light)
    -- If we are in debug mode, reset the vehicle alpha to normal again
    if debugMode then
        playerVehicle.alpha = 255
    end
    playerVehicle, lightMarker, light = nil, nil, nil
end

-- FUNCTIONS THAT MANAGE THE EFFECT --
-- Start or stop the effect when the player is driving a car
local function manageDrivingLightEffectStatus(_, seat)
    if eventName == "onClientPlayerVehicleEnter" then
        if seat == 0 then
            -- The player has just entered a vehicle as the driver. Start the effect
            startDrivingLightEffect()
        end
    elseif playerVehicle then
        -- The player has just exited a vehicle and we were applying the effect. Stop it
        stopDrivingLightEffect()
    end
end
addEventHandler("onClientPlayerVehicleEnter", localPlayer, manageDrivingLightEffectStatus)
addEventHandler("onClientPlayerVehicleExit", localPlayer, manageDrivingLightEffectStatus)

-- Start the effect when the resource starts if the player is driving a vehicle, and reset vehicle alpha back to normal if necessary
local function handleResourceStartStop()
    if eventName == "onClientResourceStart" then
        playerVehicle = localPlayer.vehicle or nil
        if playerVehicle then
            startDrivingLightEffect()
        end
    elseif playerVehicle then
        -- It is not necessary to call this function to just reset the car alpha, but it is a good practise to ALWAYS clean up everything nevertheless
        stopDrivingLightEffect()
    end
end
addEventHandler("onClientResourceStart", resourceRoot, handleResourceStartStop)
addEventHandler("onClientResourceStop", resourceRoot, handleResourceStartStop)

shared

This examples illustrates the concept of dot/scalar product and implements a useful function which can be used to get the angle between two vectors.

-- Calculate angle between vec1 and vec2
function angle(vec1, vec2)
    -- Calculate the angle by applying law of cosines
    return math.acos(vec1:dot(vec2)/(vec1.length*vec2.length))
end

local vec1 = Vector3(1, 0, 0)
local vec2 = Vector3(0, 0, 0)
local dotproduct = vec1:dot(vec2)

if dotproduct == 0 then
    outputDebugString("vec1 is orthogonal to vec2")
end

outputDebugString("Angle between vec1 and vec2: "..math.deg(angle(vec1, vec2)).."°")

client

This example slowly moves all the players' camera to look at the Mount Chilliad.

local targetPosition = Vector3(-2627.32, -1083.2, 433.35) -- Somewhere in Mount Chilliad

local function moveCameraToTarget(deltaTime)
    local currentPosition = Vector3(getCameraMatrix())
    local direction = targetPosition - currentPosition
    direction:normalize() -- Get a direction vector by normalizing the vector from the current position to the target position
    setCameraMatrix(currentPosition + direction * deltaTime * 0.05, -2589.45, -1174.49, 418.09)
end
addEventHandler("onClientPreRender", root, moveCameraToTarget)

client

This example slowly moves all the players' camera to look at the Mount Chilliad with a shorter code than the previous example.

local targetPosition = Vector3(-2627.32, -1083.2, 433.35) -- Somewhere in Mount Chilliad

local function moveCameraToTarget(deltaTime)
    local currentPosition = Vector3(getCameraMatrix())
    local direction = (targetPosition - currentPosition):getNormalized() -- Get a direction vector by normalizing the vector from the current position to the target position
    setCameraMatrix(currentPosition + direction * deltaTime * 0.05, -2589.45, -1174.49, 418.09)
end
addEventHandler("onClientPreRender", root, moveCameraToTarget)

See Also

Vector Elements

• Vector2
• Vector3
• Vector4

Reference

• Element