stingray.Vector4 object reference

Description

Describes a three-dimensional vector.

NOTE: Vector4 objects are temporary. You can only use them in the frame in which they were generated. If you need to save a Vector4 across multiple frames, use a Vector4Box instead. For more information, see Object Lifetimes and Userdata Binding.

Operators

You can use several operators like + and - to modify and transform Vector4 objects, described below.

Addition: +

You can add two vectors together using the + operator. For example:

newVector = vector1 + vector2

This is equivalent to the add() function.

Subtraction: -

You can subtract one vector from another using the - operator. For example:

newVector = vector1 - vector2

This is equivalent to the subtract() function.

Negation: -

You can negate a vector using the - operator as a prefix to any vector variable. For example:

negativeVector = -vector1

Multiplication: *

You can multiply a vector by a scalar value using the * operator. For example:

newVector = vector * scalarFactor

This is equivalent to the multiply() function. See also multiply_elements(), which lets you multiply two vectors together per-element.

Division: /

You can divide a vector by a scalar value using the / operator. For example:

newVector = vector / scalarFactor

This is equivalent to the divide() function. See also divide_elements(), which lets you divide one vector by another per-element.

Accessing components: []

You can set and retrieve component values by using the [] operator. Use the indices 1 or "x" for the X component, 2 or "y" for the Y component, 3 or "z" for the Z component, and 4 or "w" for the W component. For example:

yComponentValue = vector[2]
zComponentValue = vector["z"]

Constructors and accessors

stingray.Vector4() stingray.Vector4.add() stingray.Vector4.divide() stingray.Vector4.divide_elements() stingray.Vector4.lerp() stingray.Vector4.max() stingray.Vector4.min() stingray.Vector4.multiply() stingray.Vector4.multiply_elements() stingray.Vector4.normalize() stingray.Vector4.subtract() stingray.Vector4.zero() stingray.Vector4Box.unbox()

Other related reference items

	stingray.Vector4Box
	color
	stingray.LineObject.add_box() stingray.LineObject.add_capsule() stingray.LineObject.add_circle() stingray.LineObject.add_cone() stingray.LineObject.add_half_sphere() stingray.LineObject.add_line() stingray.LineObject.add_sphere() stingray.Replay.record_debug_line() stingray.Replay.record_screen_debug_text() stingray.Replay.record_world_debug_text() stingray.Vector4Box() stingray.Vector4Box.store()
	Math

Related help topics

Release Notes > Stingray 1.1 Release Notes

Data Members

w : number The W component.

x : number The X component.

y : number The Y component.

z : number The Z component.

Functions

add ( vector_a, vector_b ) : stingray.Vector4 Adds the two specified vectors together, and returns the resulting vector.

Parameters

vector_a :	stingray.Vector4	The first vector to add.
vector_b :	stingray.Vector4	The second vector to add.

Returns

stingray.Vector4

The sum of the two input vectors.

distance ( vector_a, vector_b ) : number Returns the distance between two specified points.

Parameters

vector_a :	stingray.Vector4	The first point.
vector_b :	stingray.Vector4	The second point.

Returns

number

The scalar distance between vector_a and vector_b.

distance_squared ( vector_a, vector_b ) : number Returns the square of the distance between two specified points.

Parameters

vector_a :	stingray.Vector4	The first vector.
vector_b :	stingray.Vector4	The second vector.

Returns

number

The square of the distance between vector_a and vector_b.

divide ( vector, factor ) : stingray.Vector4 Divides the specified vector by a scalar value, and returns the resulting vector.

Parameters

vector :	stingray.Vector4	The vector to divide.
factor :	number	A scalar value to divide into the vector.

Returns

stingray.Vector4

The quotient of the input vector and the scalar value.

divide_elements ( vector_a, vector_b ) : stingray.Vector4 Divides each element of vector_a by the corresponding element of vector_b, and returns the resulting vector.

Parameters

vector_a :	stingray.Vector4	The vector to be divided.
vector_b :	stingray.Vector4	The vector to divide into vector_a.

Returns

stingray.Vector4

The quotient of the two input vectors.

dot ( vector_a, vector_b ) : number Returns the dot product of the two specified vectors.

Parameters

vector_a :	stingray.Vector4	The first vector.
vector_b :	stingray.Vector4	The second vector.

Returns

number

The dot product.

element ( vector, index ) : number Returns the value stored at the specified index within the vector.

Parameters

vector :	stingray.Vector4	The vector whose component will be returned.
index :	integer	The index of the component to return. Use 1 for the X component, 2 for the Y component, 3 for the Z component, or 4 for the W component

Returns

number

The value of the element at the specified index.

equal ( vector_a, vector_b ) : boolean Indicates whether or not the two vectors are identical.

Parameters

vector_a :	stingray.Vector4	The first vector to compare.
vector_b :	stingray.Vector4	The second vector to compare.

Returns

boolean

Returns true if the two vectors are identical, or false otherwise.

is_valid ( vector ) : boolean Indicates whether or not the vector is composed entirely of valid values.

Parameters

vector :

stingray.Vector4

The vector to be validated.

Returns

boolean

Returns true if all components of the vector are valid numbers, or false if any component is #NaN or #INF.

length ( vector ) : number Returns the scalar length of the specified vector.

Parameters

vector :

stingray.Vector4

The vector whose length will be returned.

Returns

number

The length of the vector.

lerp ( vector_a, vector_b, ratio ) : stingray.Vector4 Produces a new vector by interpolating linearly between the two specified vectors with the specified ratio.

Parameters

vector_a :	stingray.Vector4	The first vector.
vector_b :	stingray.Vector4	The second vector.
ratio :	number	The interpolation ratio, or weight. May be any value between 0 and 1 inclusive. Values closer to 0 produce vectors closer to vector_a; values closer to 1 produce vectors closer to vector_b.

Returns

stingray.Vector4

The resulting vector.

max ( vector_a, vector_b ) : stingray.Vector4 Returns a vector that contains the greatest value for each component in the two specified vectors.

Parameters

vector_a :	stingray.Vector4	The first vector.
vector_b :	stingray.Vector4	The second vector.

Returns

stingray.Vector4

The resulting vector.

min ( vector_a, vector_b ) : stingray.Vector4 Returns a vector that contains the smallest value for each component in the two specified vectors.

Parameters

vector_a :	stingray.Vector4	The first vector.
vector_b :	stingray.Vector4	The second vector.

Returns

stingray.Vector4

The resulting vector.

multiply ( vector, factor ) : stingray.Vector4 Multiplies the specified vector by a scalar value, and returns the resulting vector.

Parameters

vector :	stingray.Vector4	The vector to multiply.
factor :	number	A scalar value to multiply with the vector.

Returns

stingray.Vector4

The product of the input vector and the scalar value.

multiply_elements ( vector_a, vector_b ) : stingray.Vector4 Multiplies each element of vector_a by the corresponding element of vector_b, and returns the resulting vector.

Parameters

vector_a :	stingray.Vector4	The first vector to multiply.
vector_b :	stingray.Vector4	The second vector to multiply.

Returns

stingray.Vector4

The product of the two input vectors.

normalize ( vector ) : stingray.Vector4 Normalizes the specified vector -- i.e. converts its scalar length to 1 -- and returns the result.

Parameters

vector :

stingray.Vector4

The vector to be normalized.

Returns

stingray.Vector4

The normalized vector.

set_element ( vector, index, value ) Sets the specified index within the vector to the specified value.

Parameters

vector :	stingray.Vector4	The vector whose component will be set.
index :	integer	The index of the component to set. Use 1 for the X component, 2 for the Y component, 3 for the Z component, or 4 for the W component.
value :	number	The value to set at the specified index.

Returns

This function does not return any values.

set_w ( vector, value ) Sets the value of the vector's W component.

Parameters

vector :	stingray.Vector4	The vector whose component will be set.
value :	number	The new value for the W component.

Returns

This function does not return any values.

set_x ( vector, value ) Sets the value of the vector's X component.

Parameters

vector :	stingray.Vector4	The vector whose component will be set.
value :	number	The new value for the X component.

Returns

This function does not return any values.

set_xyzw ( vector, x, y, z, w ) Sets the values of the vector's X, Y, Z and W components.

Parameters

vector :	stingray.Vector4	The vector whose components will be set.
x :	number	The new value for the X component.
y :	number	The new value for the Y component.
z :	number	The new value for the Z component.
w :	number	The new value for the W component.

Returns

This function does not return any values.

set_y ( vector, value ) Sets the value of the vector's Y component.

Parameters

vector :	stingray.Vector4	The vector whose component will be set.
value :	number	The new value for the Y component.

Returns

This function does not return any values.

set_z ( vector, value ) Sets the value of the vector's Z component.

Parameters

vector :	stingray.Vector4	The vector whose component will be set.
value :	number	The new value for the Z component.

Returns

This function does not return any values.

subtract ( vector_a, vector_b ) : stingray.Vector4 Subtracts vector_b from vector_a, and returns the resulting vector.

Parameters

vector_a :	stingray.Vector4	The starting vector.
vector_b :	stingray.Vector4	The vector that will be subtracted.

Returns

stingray.Vector4

The result of the subtraction.

to_elements ( vector ) : number, number, number, number Decomposes the specified vector into its component values.

Parameters

vector :

stingray.Vector4

The vector to be broken down into its components.

Returns

number	The X component of the vector.
number	The Y component of the vector.
number	The Z component of the vector.
number	The W component of the vector.

Other related reference items

color

to_string ( vector ) : string Returns a string representation of the specified vector.

Parameters

vector :

stingray.Vector4

The vector to return as a string.

Returns

string

The string representation.

Use this function only for debugging purposes; do not attempt to save the string and read it back into a new vector. Use a Vector4Box to save vectors across multiple frames.

w ( vector ) : number Returns the value of the vector's W component.

Parameters

vector :

stingray.Vector4

The vector whose component will be returned.

Returns

number

The value of the W component.

x ( vector ) : number Returns the value of the vector's X component.

Parameters

vector :

stingray.Vector4

The vector whose component will be returned.

Returns

number

The value of the X component.

y ( vector ) : number Returns the value of the vector's Y component.

Parameters

vector :

stingray.Vector4

The vector whose component will be returned.

Returns

number

The value of the Y component.

z ( vector ) : number Returns the value of the vector's Z component.

Parameters

vector :

stingray.Vector4

The vector whose component will be returned.

Returns

number

The value of the Z component.

zero ( ) : stingray.Vector4 Returns a new vector with all values initialized to zero.

Parameters

This function does not accept any parameters.

Returns

stingray.Vector4

The zero vector.