Math
The following functions and classes are related to Math operations. Cave engine does have a cave.math submodule, but in order to simplify and speedup your code writting, the classes belongs to the main cave. module. Only the functions belongs to the submodule.
cave.math
Functions
cave.math.normalized(vec : cave.Vector3) -> cave.Vector3
cave.math.length(vec : cave.Vector3) -> float
cave.math.clamp(x : float, minValue : float, maxValue: float) -> float
You can also lerp two values by a factor (value) using cave.math.lerp. The supported types are: float, Vector2, Vector3, Vector4 and Quaternion. Reference:
cave.math.lerp(a: TYPE, b: TYPE, value: float) -> TYPE
If you're using Quaternions, slerp is also supported. See this link to understand slerp. Reference:
cave.math.slerp(a: cave.Quaternion, b: cave.Quaternion, value: float) -> cave.Quaternion
Map Range is also an useful function that allows you to map a value from one range to other. For example, if you have a health variable that is represented in percentage (0 to 100) and you want to make a mesh becomes invisible as the health decreases, you can map the health value from the range [0, 100] to the range [1.0, 0.0] and apply that as the alpha tint of the mesh, since alpha 1.0 (when health is 100%) means completely opaque and alpha 0.0 (when health is 0%) means completely transparent. Reference:
cave.math.mapRange(value: float, fromMin: float, fromMax: float, toMin: float, toMax: float) -> float
A common vector operator is the dot product. Supported in cave with the cave.math.dot(...) function and works with Vector2, Vector3 and Vector4. See this link to understand how dot product works. Reference:
cave.math.dot(a: VectorX, b: VectorX) -> VectorX
Cave also supports the inverse function to invert a Quaternion or Matrix4:
cave.math.inverse(quat: cave.Quaternion) -> cave.Quaternion
cave.math.inverse(quat: cave.Matrix4) -> cave.Matrix4
If you want to Project a vector into another, you can use the cave.math.project(...) function, that takes the vector that you want to project as the first argument and the target vector (the "other") as the second. It will return the final projected vector. The function works with Vector2, Vector3 and Vector4. If you don't know what is a vector projection, consider reading this article. Reference:
cave.math.project(vec: cave.VectorX, other: cave.VectorX) -> cave.VectorX
Intersection Checks
When creating games, you ofter want to check for some geometric intersections, such as a point and sphere intersection. Cave Engine provides some builtin functions for you to do it so.
If you want to get the intersection points and normals between a line and a sphere, you can use the following function:
cave.math.intersectLineSphere(
lineP1 : cave.Vector3, lineP2 : cave.Vector3,
sphereCenter : cave.Vector3, sphereRadius : float
) -> list of tuples
This function takes two point coordinates as arguments to define the line (lineP1 and lineP2) and a position and radius to define the sphere. It returns a list of tuples containing the (position, normal) for each intersection point. If the shapes don't collide, the list will be empty.
You can do a similar check between a line and a geometry triangle. In this case, here is the API:
cave.math.intersectLineTriangle(
lineP1 : cave.Vector3, lineP2 : cave.Vector3,
p1 : cave.Vector3, p2 : cave.Vector3, p3 : cave.Vector3
) -> cave.Vector3 or None
It takes two point coordinates as arguments to define the line (lineP1 and lineP2) and three coordinates (p1, p2, p3) to specify the triangle. Returns the intersection point (as a cave.Vector3) fi it hits or None, otherwise.
Vector Classes
Cave Engine provides wrappers to low level C++ vector classes and operations.
Initialization Example
Here is an initialization example to get started:
# Default constructor:
vec = cave.Vector()
# Intialize the vector with (0, 0):
myVec1 = cave.Vector2(0)
# Regular (x, y) constructor for the 2D Vector:
myVec2 = cave.Vector2(0, 1)
# Copy the vector:
myVec3 = cave.Vector3(myVec2)
Supported Vector Operations
You can do all sorts of operations using vectors:
| Operation | Usage |
|---|---|
| == | if vecA == vecB: ... |
| + | vec = vecA + vecB |
| += | vec += vecB |
| - | vec = vecA - vecB |
| -= | vec -= vecB |
| * | vec = vecB * 50.0 |
| * | vec = 50.0 * vecB |
| *= | vec *= 100.0 |
Including operations between a cave.Vector3 and an cave.Quaternion:
| Operation | Usage |
|---|---|
| * | vec = vec * quaterion |
| * | vec = quaterion * vecB |
| *= | vec *= quaterion |
cave.Vector2
Variables
x : float
y : float
Note: You can also access the x, y parameters by using s, t or u, v.
cave.Vector3
Variables
x : float
y : float
z : float
Note: You can also access the x, y, z parameters by using r, g, b as an acronym for the color channels Red, Green and Blue.
cave.Vector4
Variables
x : float
y : float
z : float
w : float
Note: You can also access the x, y, z, w parameters by using r, g, b, a as an acronym for the color channels Red, Green, Blue and Alpha.
Other Classes
cave.Quaternion
Quaternions, just like the vectors, are low level implementations that supports all sorts of operations (==, +, +=, -, -=, *, *=).
Variables
x : float
y : float
z : float
w : float
cave.Matrix4
This class is declared for the Cave API, but not yet implemented, so right now there is no way to directly manipulate the Matrix4 using Python.
cave.UIVector
The cave.UIVector is a different vector, used specifically for the in Game User Interface (Game UI). It needs to be a different type of vector because it also takes into account the anchoring and if the element is relative (or not) to it's parent.
If the vector is relative, the X, Y values will be represented with a [0-1] ranged float number (percentage). If not, it will be represented by two ints for the pixels.
Variables
anchoringX : int
anchoringY : int
The supported anchoring values are: -1, 0, 1.
Methods
isRelativeX() -> bool
isRelativeY() -> bool
getX(parentScale = 1.0) -> float
getY(parentScale = 1.0) -> float
setPixelX(value : int)
setPixelY(value : int)
setPixel(x : int, y : int)
setRelativeX(value : float)
setRelativeY(value : float)
setRelative(x : float, y : float)