stingray.Math namespace reference

Description

The Math object contains some helpful generic math functions.

Related sample code

Character template: /player.lua Character template: /util.lua

Other related reference items

Math

Functions

box_intersects_frustum ( pose, half_dimensions, frustum_planes, frustum_corners ) : boolean Indicates whether or not an oriented bounding box (specified by the pose and half_dimensions paramaters) iintersects a frustum.

Parameters

pose :	stingray.Matrix4x4	The position and rotation of the center of the box.
half_dimensions :	stingray.Vector3	The distance from the center of the box to the center of its surfaces, along its local right, up and forward axes.
frustum_planes :	any(stingray.Vector3, number)*	The 6 planes for the frustum as pairs of Vector3 and number parameters, the normal vector pointing outside the frustum plane and number being the position of the plane along this normal. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The * notation indicates that there may be zero or more instances of the specified type.
frustum_planes :	any(stingray.Vector3, number)*	The 8 corners for the frustum, provided in order so that near plane is ABCD, far plane is EFGH and AE, BF, CG & DH are the side edges. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The * notation indicates that there may be zero or more instances of the specified type.

Returns

boolean

Returns true if the box is completely inside the frustum or intersect it, or false if completly outside.

The frustum is specified by its 8 corners and its 6 planes, each of which is a pair of a Vector3 value that defines the normal of the plane (facing outward from the frustum) and a float that specifies the position of the plane along the normal.

box_in_frustum ( pose, half_dimensions, n, o, additional_planes ) : boolean Indicates whether or not an oriented bounding box (specified by the pose and half_dimensions paramaters) is completely enclosed within a frustum.

Parameters

pose :	stingray.Matrix4x4	The position and rotation of the center of the box.
half_dimensions :	stingray.Vector3	The distance from the center of the box to the center of its surfaces, along its local right, up and forward axes.
n :	stingray.Vector3	The normal of one plane of the frustum, facing outward from the frustum.
o :	number	The position of the frustum plane along the normal n.
additional_planes :	any(stingray.Vector3, number)*	You can set up more planes for the frustum by adding more pairs of Vector3 and number parameters similar to n and o. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The * notation indicates that there may be zero or more instances of the specified type.

Returns

boolean

Returns true if the box is completely inside the frustum, or false otherwise.

The frustum is specified by a series of planes, each of which is a pair of a Vector3 value that defines the normal of the plane (facing outward from the frustum) and a float that specifies the position of the plane along the normal. You can specify as many of these pairs as necessary in order to set up multiple planes for the frustum.

is_valid ( inputs ) : boolean Indicates whether or not all of the inputs are valid numeric values.

Parameters

inputs :

number*

Any number of number values to test. The * notation indicates that there may be zero or more instances of the specified type.

Returns

boolean

Returns true if all inputs are valid numbers, or false if any component is #NaN or #INF.

merge_boxes ( pose, half_dimensions, additional_boxes ) : stingray.Matrix4x4, stingray.Vector3 Merges a series of oriented bounding boxes together into a single oriented bounding box that encloses all of the input boxes.

Parameters

pose :	stingray.Matrix4x4	The position and rotation of the center of the box.
half_dimensions :	stingray.Vector3	The distance from the center of the box to the center of its surfaces, along its local right, up and forward axes.
additional_boxes :	any(stingray.Matrix4x4, stingray.Vector3)*	You can set up more boxes to merge by adding more pairs of Matrix4x4 and Vector3 parameters similar to pose and half_dimensions. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses. The * notation indicates that there may be zero or more instances of the specified type.

Returns

stingray.Matrix4x4	The position and rotation of the merged box.
stingray.Vector3	The distance from the center of the merged box to the center of its surfaces, along its local right, up and forward axes.

Each box is specified by a pair of values: a Matrix4x4 that contains its position and rotation, and a Vector3 that contains its dimensions. You can provide as many of these pairs as you need.

The resulting box will have the same axes as the first box in the input: i. e., this function does not return the minimum enclosing bounding box.

next_random ( seed, first_bound, second_bound ) : integer, number Generates a random number and a new seed based on the specified seed value.

Parameters

seed :	integer	A seed used to generate the random number.
first_bound :	integer?	The first bound for the generated number. The ? notation indicates that this type is optional: there may be zero or one instances of it.
second_bound :	integer?	The second bound for the generated number. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

integer	A new seed value.
number	The generated random number.

Use this function instead of stingray.Math.random() if you want to query a reproducible series of random numbers.

• If you specify no parameters, the generated number will be a floating-point value between 0 and 1.
• If you specify only first_bound, the generated number will be an integer between 1 and first_bound inclusive.
• If you specify both first_bound and second_bound, the generated number will be an integer value between first_bound and second_bound inclusive.

point_in_box ( point, pose, half_dimensions ) : boolean Indicates whether or not a point (specified by the point parameter) lies inside an oriented bounding box (specified by the pose and half_dimensions paramaters).

Parameters

point :	stingray.Vector3	The point to test.
pose :	stingray.Matrix4x4	The position and rotation of the center of the box.
half_dimensions :	stingray.Vector3	The distance from the center of the box to the center of its surfaces, along its local right, up and forward axes.

Returns

boolean

Returns true if the point is inside the box, or false otherwise.

random ( first_bound, second_bound ) : number Generates a random number.

Parameters

first_bound :	integer?	The first bound for the generated number. The ? notation indicates that this type is optional: there may be zero or one instances of it.
second_bound :	integer?	The second bound for the generated number. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

number

The generated random number.

This function operates exactly like the standard Lua math.random() function, except that it uses a random number generator built in to Stingray rather than the standard Lua random number generator.

• If you specify no parameters, the generated number will be a floating-point value between 0 and 1.
• If you specify only first_bound, the generated number will be an integer between 1 and first_bound inclusive.
• If you specify both first_bound and second_bound, the generated number will be an integer value between first_bound and second_bound inclusive.

Related sample code

Oculus VR template: /project.lua Steam VR template: /project.lua Saving and loading data

Other related reference items

stingray.Math.next_random()

ray_box_intersection ( from, dir, pose, half_dimensions ) : number Computes the intersection between a ray (specified by the from and dir parameters) and an oriented bounding box (specified by the pose and half_dimensions parameters).

Parameters

from :	stingray.Vector3	The starting point of the ray.
dir :	stingray.Vector3	The direction of the ray.
pose :	stingray.Matrix4x4	The position and rotation of the center of the box.
half_dimensions :	stingray.Vector3	The distance from the center of the box to the center of its surfaces, along its local right, up and forward axes.

Returns

number

The distance from the starting point of the ray to the first point of collision with any surface of the box, regardless of whether the ray starts inside or outside the box. If the ray does not collide with the box, returns -1.