Transform Component
cave.TransformComponent
Variables
position : cave.Vector3
scale : cave.Vector3
Note that you can't get/set the rotation using regular variables as you can with the position and scale. That's due to the way the engine works internally. So use the getters and setters for euler angles or quaternions to rotate as you need to. You can see the details bellow. Sample code (as it would be in the update method of a Component):
transform = self.entity.getTransform()
# Modifying the current euler angles by adding 0.1 on the Y axis:
euler = transform.getEuler()
euler.y += 0.1
transform.setEuler(euler)
# or you can use this to ROTATE the object:
# (will produce the same result as the approach above)
transform.rotate(0, 0.1, 0)
Last but no least, you can also do this variant below to Set the euler. Note that this approach will not produce the same result as the two others presented above. This one wil SET the rotation to [0, 0, 0]:
transform.setEuler(0, 0, 0)
Methods
As explained above, the rotation can be handled by using the getters and setters for the Euler angles or Quaternion. Here is the API for reference:
# Euler Angles:
getEuler() -> cave.Vector3
setEuler(euler : cave.Vector3)
setEuler(x : float, y : float, z : float)
# Quaternions:
getQuaternion() -> cave.Quaternion
setQuaternion(quaternion : cave.Quaternion)
setQuaternion(x : float, y : float, z : float, w: float)
- Rotating a Transform
In order to Rotate a Transform, other than getting and setting the euler or quaternion by hand, Cave provides a lot of different Transform methods to make your life easier. Starting with the rotate and rotateEuler.
The different between them is that the first one expects the values in radians and the second, in degrees:
rotate(x : float, y : float, z : float)
rotateEuler(x : float, y : float, z : float)
If you want to rotate the Transform around a specific axis, you can also use the rotateOnAxis method, that expects an angle (in radians) and the axis to rotate the Transform in.
rotateOnAxis(angle : float, axis : cave.Vector3)
Alternatively, you can rotate it around the Pitch, Yaw and Roll axis. If you don't know what is this, I strongly recommend you to read this article first.
rotateOnPitch(angle : float)
rotateOnYaw(angle : float)
rotateOnRoll(angle : float)
Talking about Roll, Pitch and Yaw, Cave Engine makes it very easy for you to retrieve those values from a Transform as well:
getPitch() -> float
getYaw() -> float
getRoll() -> float
- Moving a Transform
Just like rotating, you can either manually get and set the Transform's position, this time using the position variable, or you can count on the various Cave methods provided to make your life easier.
Starting with the basic move method, it will add the provided x, y, z values to the transform's position. But what makes this special is the local parameter. If True (as it is by default), it will first transform those x, y, z values to align to the Transform's orientation. Meaning that, for example, Z will always face the Transform's Forward instead of the world's +Z axis.
move(x : float, y : float, z : float, local = True)
Alternatively, if you want to apply the movement locally, you can also call this method directly:
applyLocalMovement(x : float, y : float, z : float)
applyLocalMovement(movement: cave.Vector3)
If you read the Entity's Parent Documentation, you may have noticed the following sentence: Entities with a parent will have their Transforms local to their parent's Transform. In other words, the position variable will always be local to the Transform's Entity's parent. If you want to get or set it globally (what we call "world"), you can do it so by using this two methods:
getWorldPosition() -> cave.Vector3
setWorldPosition(pos: cave.Vector3)
- Useful Methods
Sometimes you want to do more than simply moving or rotating a Transform. For example, you may want to also lerp it with something else or even make it look at certain direction. Cave Engine's API got you covered in all those cases!
But let's start small with some other useful methods first: If you need to know what is the forward, right (and consequently left) or up direction that a Transform is pointing at, you can use those methods to easily get them:
getForwardVector() -> cave.Vector3
getRightVector() -> cave.Vector3
getUpVector() -> cave.Vector3
Now, starting to get interesting, Cave provides some built in methods to make a Transform look at certain direction. Imagine that you're making a tower defense game and you want the turret to aim at the nearest enemy. This is probably what you'll be using to achieve that. Same case to make the enemy look at the player.
Cave provides two different methods: lookAt and lookAtSmooth. The difference between them is that the first one will immediatly set the Transform to the final orientation and the last one will let you choose a lerp factor, giving you more options to smooth this movement.
lookAt(direction : cave.Vector3, up = cave.Vector3(0, 1, 0))
lookAtSmooth(direction : cave.Vector3, lerp = 0.5, up = cave.Vector3(0, 1, 0))
It's also good to know that the lookAtSmooth internally uses Quaternion's sLerp functionalities to get the best possible result. If you don't know what's that, I recommend you reading this Article.
Talking about lerp... you can lerp the Transform's quaternions with another directly by using this method:
slerpQuaternion(target : cave.Quaternion, value=0.5)
And if that's not enough for you, it's possible to lerp the entire Transform with another by calling this:
lerp(target : cave.TransformComponent, value=0.5)
It also uses slerp internally. This method is very useful if you want to smoothly make a Entity go to a specific place in the world. Let's say that you're about to execute a live action cutscene animation and you want the player to be in a specific spot. Instead of drastically setting the player's position, rotation and scale to that spot, causing it to "teleport" right in front of who is playing your game, you can lerp the Transform to the final and desired one. Good!
- Transforming a Vector
Sometimes you want to work with Vector math but also take into account the Entity's Transform, meaning that you may want to do some operations to make the vector's transform or rotation local or global and so on. Cave Engine provides some specific methods to help you with that. If you know Vector, Quaternion and Matrices math, you'll probably understand out of the box what those methods are, but I'll try to explain them in details.
The first set of helpful methods are to rotate or unrotate a Vector by the Transform's rotation. As an example, if you rotate the vector (0, 0, 1), it will endup looking at the Transform's forward direction.
(If you know the math behind it, those functions basicaly means quat * vec and inverse(quat) * vec, respectively).
rotateVector(vec : cave.Vector3) -> cave.Vector3
unrotateVector(vec : cave.Vector3) -> cave.Vector3
The second set of helpful methods are to transform or untransform a Vector by the Transform. They work in the same way as the rotate ones, except that now it will take the Transform's scale and position into account.
(If you know the math behind it, those functions basicaly means mat * vec and inverse(mat) * vec, respectively).
transformVector(vec : cave.Vector3) -> cave.Vector3
untransformVector(vec : cave.Vector3) -> cave.Vector3
- Matrix Operations
If you understand how Transform Matrices works, you can also use those two methods to get/set its matrix directly:
getMatrix() -> cave.Matrix4
setMatrix(mat : cave.Matrix4)
If you don't understand or even if you do, most of the times it's better to use the other functions instead of this because they are easier to work with. :)