en:vci:script:reference:vector3

Vector3

You can see the latest list of available methods in types.lua.
Vector3 is a class with three values: X, Y and Z.
It is used to describe a position or direction of a force.

List of methods

For the latest list of the methods, refer to “types.lua” file in “EmbeddedScriptWorkspace” folder.
To shorten the description, Vector3 type is abbreviated as Vec and number type is abbreviated as num.
Arguments are shown in () and return values are shown after semicolons :.

Method name Description
Slerp (a: Vec3, b: Vec3, t: num): Vec3 Spherically interpolates between two vectors by the coefficient t. The range of t is [0, 1].
SlerpUnclamped (a: Vec3, b: Vec3, t: num): Vec3 Same as Slerp, but doesn't restrict the t range to [0, 1]. Used for things like springs.
OrthoNormalize (normal: usertype, tangent: usertype)
RotateTowards (current, target, maxRadiansDelta, maxMagnitudeDelta): Vec3
Lerp (a: Vec3, b: Vec3, t: num): Vec3 Linearly interpolates between two vectors by the coefficient t. The range of t is [0, 1].
LerpUnclamped (a: Vec3, b: Vec3, t: num): Vec3 Same as Lerp, but doesn't restrict the t range to [0, 1]. Used for things like springs.
MoveTowards (current: Vec3, target: Vec3, maxDistanceDelta: num): Vec3
SmoothDamp (current: Vec3, target: Vec3, currentVelocity: usertype, smoothTime: num, maxSpeed: num): Vec3 Change the vector gradually toward the target as the time proceeds.
set_Item (index: num, value: num)
Set (newX: num, newY: num, newZ: num)
Scale (a: Vec3, b: Vec3): Vec3 Multiply each element of two vectors.
Cross (lhs: Vec3, rhs: Vec3): Vec3 Calculate the cross product of two vectors.
GetHashCode(): num Not to be used.
Reflect (inDirection: Vec3, inNormal: Vec3): Vec3
Normalize (value: Vec3): Vec3 Normalize a vector to a unit vector.
Dot (lhs: Vec3, rhs: Vec3): num Calculate the inner product of two vectors.
Project (vector: Vec3, onNormal: Vec3): Vec3 Calculate the vector of the projection of the first argument, using onNormal as the base.
ProjectOnPlane (vector: Vec3, planeNormal: Vec3): Vec3
Angle (from: Vec3, to: Vec3): num Return the angle of the vector between two points (Return the result of Dot() as Euler angle)
SignedAngle (from: Vec3, to: Vec3, axis: Vec3): num
Distance (a: Vec3, b: Vec3): num Calculate the distance between two points: a and b. * Same as (a-b).magnitude
ClampMagnitude (vector: Vec3, maxLength: num): Vec3
Magnitude (vector: Vec3): num Calculate the length of the vector.
SqrMagnitude (vector: Vec3): num Calculate the squared length of the vector.
Min (lhs: Vec3, rhs: Vec3): Vec3 Compare each element of two vectors and create a vector with the smallest values.
Max (lhs: Vec3, rhs: Vec3): Vec3 Compare each element of two vectors and create a vector with the largest values.
ToString (): string
AngleBetween (from: Vec3, to: Vec3): num
Exclude (excludeThis: Vec3, fromThat: Vec3): Vec3
normalized: Vec3 Normalize the vector (Read-only)
magnitude: num Read the vector as length.
sqrMagnitude: num Read the vector as squared length.

Methods for initialization

Method name Description
_new (x: num, y: num, z: num): Vec3
zero: Vec3 (0.0, 0.0, 0.0)
one: Vec3 (1.0, 1.0, 1.0)
forward: Vec3 (0.0, 0.0, 1.0) positive Z-axis
back: Vec3 (0.0, 0.0, -1.0) negative Z-axis
up: Vec3 (0.0, 1.0, 0.0) positive Y-axis
down: Vec3 (0.0, -1.0, 0.0) negative Y-axis
left: Vec3 (0.0, 0.0, 0.0) negative X-axis
right: Vec3 (0.0, 0.0, 0.0) positive X-axis
positiveInfinity: Vec3 (Infinity, Infinity, Infinity)
negativeInfinity: Vec3 (-Infinity, -Infinity, -Infinity)
fwd: Vec3 (0.0, 0.0, 1.0) positive Z-axis (same as forward)
kEpsilon: num
kEpsilonNormalSqrt: num
x: num Access only the “x” in a “Vec3”
y: num Access only the “y” in a “Vec3”
z: num Access only the “z” in a “Vec3”

About initialization

Example

main.lua
local pos = Vector3.__new(1,1,1)
local zero = Vector3.zero
local one = Vector3.one
print(pos)
print(zero)
print(one)

The result

(1.0, 1.0, 1.0)
(0.0, 0.0, 0.0)
(1.0, 1.0, 1.0)

In VCI, to initialize a Vector3, use “new” as shown above.
You can also specify the value by using “zero” and “one” after “Vector3”.
The types of value will be number, which is handled as floating-point numbers internally.

List of initialization types

Example

main.lua
    local zero = Vector3.zero
    print(zero)
    local one = Vector3.one
    print(one)
    local forward = Vector3.forward
    print(forward)
    local back = Vector3.back
    print(back)
    local up = Vector3.up
    print(up)
    local down = Vector3.down
    print(down)
    local left = Vector3.left
    print(left)
    local right = Vector3.right
    print(right)

The result

(0.0, 0.0, 0.0)
(1.0, 1.0, 1.0)
(0.0, 0.0, 1.0)
(0.0, 0.0, -1.0)
(0.0, 1.0, 0.0)
(0.0, -1.0, 0.0)
(-1.0, 0.0, 0.0)
(1.0, 0.0, 0.0)

The X-axis corresponds to left-right direction, Y-axis corresponds to up-down direction and Z-axis corresponds to a forward-backward direction. For example, by using SetVelocity() (ExportTransform) to add Vector3.forward on a SubItem, you can move the SubItem to the direction of Z-axis.

Access each x y z element

Example

main.lua
    local pos = Vector3.__new(1,1,1)
    pos.x = pos.x + 1
    pos.x = pos.y + 2
    pos.x = pos.z + 3
    print(pos.x)
    print(pos.y)
    print(pos.z)

The result

2
3
4

To access each element of Vector3 individually, specify the element you want to access after a variable.
Use the format VariableName.ElementToAccess.

fwd, negativeInfinity, positiveInfinity

Example

main.lua
    local fwd = Vector3.fwd
    print(fwd)
    local negativeInfinity = Vector3.negativeInfinity
    print(negativeInfinity)
    local positiveInfinity = Vector3.positiveInfinity
    print(positiveInfinity)

The result

(0.0, 0.0, 1.0)
(-Infinity, -Infinity, -Infinity)
(Infinity, Infinity, Infinity)

Vector3.fwd is the same as Vector3.forward.

normalized

Example

main.lua
    local vec3 = Vector3.__new(0.5,1,2)
    print(vec3)
    print(vec3.normalized)

The result

(0.5, 1.0, 2.0)
(0.2, 0.4, 0.9)

Normalize a vector.
When comparing two vectors, it is difficult to handle them in their original values, therefore, perform normalization to align to the standard unit vector.
When you want to handle a vector as a direction, you need to align the vector to the length of 1, so that it can be handled as an element with just the direction.

en/vci/script/reference/vector3.txt · Last modified: 2021/06/29 19:52 by t-daihisa

Page Tools