Physics Related Components

In this Page you'll find all the Physics related Components that Cave provides to your.

Character Physics

Starting with a very important one: the cave.CharacterComponent. If you're creating a regular character for your game, you'll probably use this one.

cave.CharacterComponent

Variables

Variable	Description
fallSpeed	The max fall speed of the character.
gravity	The gravity that will be applied to the character. It is different from the physics world's gravity because you may want to control this separately for your characters.
jumpSpeed	As the name suggests, the jump speed. The higher this number is, the higher the character will jump.
maxSlope	The max slope angle that the character can climb.

Here is the Python API for Reference:

fallSpeed : float
gravity   : float
jumpSpeed : float
maxSlope  : float

Methods

If you want the character to jump, just call this:

jump()

In order to detect collisions, you ca use one of those methods below. Check the Scene's cave.CollisionInfo Documentation for more information regarding it.

getCollisions() -> list of cave.CollisionInfo
getCollisionsWith(tag: str) -> list of cave.CollisionInfo
collidedWith(tag: str) -> bool

The Character needs to walk, right? In order to do it, you ccan use those methods below.

setWalkDirection(x: float, y: float, z: float, local=True)
setWalkDirection(dir: cave.Vector3, local=True)
getWalkDirection(ignoreDeltaTime=False) -> cave.Vector3

Last but not least, here is some useful methods for you to get certain data from the Character Physics:

getMoveSpeed(ignoreDeltaTime=False) -> float
isMoving()  -> bool
isFalling() -> bool
onGround()  -> bool

---

Rigid Body Physics

Rigid bodies are useful in pretty much every situation where you need to add a Physics shape to an object. It could be Dynamic, like a Box, or Static, like your scenary props.

cave.RigidBodyComponent

Variables

Variable	Description
alwaysActive	If True, the Physics Engine will never let this body sleep, meaning that it will always calculate its physics condition. Having the physics shape to sleep is an optimization that you might want to have, but in some cases, like an object that really needs to be taken into account in your game like the ball of a soccer game or a flying bullet, the alwaysActive option could be a good option to have enabled.
linearVelocity	The Entity's linear Velocity.
angularVelocity	The Entity's angular Velocity.
angularFactor	The Entity's angular Factor.

Here is the Python API for Reference:

alwaysActive    : bool
linearVelocity  : cave.Vector3
angularVelocity : cave.Vector3
angularFactor   : cave.Vector3

Methods

In order to detect collisions, you ca use one of those methods below. Check the Scene's cave.CollisionInfo Documentation for more information regarding it.

getCollisions() -> list of cave.CollisionInfo
getCollisionsWith(tag: str) -> list of cave.CollisionInfo
collidedWith(tag: str) -> bool

As you might know, Physics are all about forces! That's why you can apply various forces to your Rigid Body by calling one of those method below.

applyTorque( x : float, y : float, z : float)
applyForce(  x : float, y : float, z : float, location : cave.Vector3)
applyImpulse(x : float, y : float, z : float, location : cave.Vector3)

If the Rigid Body is Dynamic, it means that it will fall with gravity and reach to other bodies colliding with it.

isDynamic() -> bool

If you set the Rigid Body's mass to ZERO, it will make the body Static (a.k.a. "not dynamic").

setMass(value : float)

---

Vehicle Physics

If you want to make a car or any wheeled vehicle using Cave, you can use the prodived Vehicle and Wheel physics components. Note: In order to make the VehicleComponent work, the Entity must also have a RigidBody attached to it.

cave.VehicleComponent

Variables

The vehicle component have two important variables, both defined by their own class types. You can see their specifications and settings later in this page. Here is the Python API for Reference:

engineForce : cave.VehicleEngineConfig
steering    : cave.VehicleSteeringConfig

Methods

To control the VehicleComponent yourself, you'll be doing it all by calling one of the provided methods. Meaning that you'll find useful functions here to accelerate, reverse, brake, turn and so on. You may notice that some methods have an optional scale parameter. This parameter will be used as a multiplier to the provided engine forces (variable engineForce), useful to add local boosts to your vehicles (like nitrous or power ups). Check the API reference below:

accelerate(scale=1.0)
reverse(scale=1.0)

# You need to call this if you're not accelerating or reversing!
idle()

If you want to brake, you can use the brake method. But they have an important note: If do to brake, you need to make sure to release it later (by calling brakeRelease), otherwise the wheels will keep locked.

brake(scale=1.0)
brakeRelease()

Most of the times, you don't want to use the applyForce method directly, sinde the acc/rev/idle methods will internally handle it. But if you want, you can! Here you go:

applyForce(force)

Last but not least, the following methods will allow you to turn the vehicle (steering). The steer amount is defined by the Vehicle's steering variable. Just like the acc/rev, you also need to call turnStraight when you don't want othe car to turn.

turnLeft()
turnRight()
turnStraight()

cave.VehicleEngineConfig

This class is intended to allow you to controll the Vehicle's Engine settings.

Variables

The following variables lets you control the engine forces. Here is the Python API for Reference:

acceleration : float
reverse      : float
brake        : float

cave.VehicleSteeringConfig

This class is a data storage to adjust the Vehicle's Wheel settings for the ones who have steering (can turn with the steering wheel).

Variables

Variable	Description
clamp	Set the clamp to the max angle that you'll allow this wheel to turn.
increment	A higher increment mean that the wheel will turn faster.

Here is the Python API for Reference:

clamp     : float
increment : float

---

Wheel Physics

The vehicle alone is not a vehicle without their wheels! That's why you'll also find Wheel related components. Note: The Wheels must be direct children of an Entity witl a VehicleComponent, otherwise they will not work.

Tip: You can add the Wheel Component to an empty Entity and then create a child Mesh Entity to represent its visual shape. That way you can have more control over how it looks and its rotation.

cave.WheelComponent

Variables

You'll be able to adjust the wheel tuning (and suspension) as well as its controls by using one of those two class storage variables. You can find their documentation in this page.

tuning       : cave.WheelTuningConfig
control      : cave.WheelControlsConfig

The variables below ranges from [0 to 5], mapping: [X, Y, Z, -X, -Y, -Z]

# default is -Y (4)
dirAxis      : int 

# default is +X (0)
axleAxis     : int 

Here you can adjust the suspension rest length and also the wheel radius:

suspensionRestLength : float
radius : float

You can specify if the wheel is a front or back wheel here. Keep in mind that this name ("front wheel") is only for the ease to understand, but their practical functionality is that only wheels marked as "front wheel" will have steering! So you can mark any wheel you want to steer as a front wheel.

isFrontWheel : bool

Methods

getDirection() -> cave.Vector3
getAxle() -> cave.Vector3

cave.WheelTuningConfig

This class container will help you to specify all the wheel's suspension settings.

Variables

suspensionStiffness   : float
suspensionCompression : float
suspensionDamping     : float
suspensionTravelCmMax : float
suspensionForceMax    : float
frictionSlip          : float

cave.WheelControlsConfig

This class container will help you to specify wheel control settings.

Variables

Variable	Description
hasTraction	If True, the wheel will rotate when the VehicleComponent applies some forces (such as accelerating or reversing).
hasBrake	If True, the wheel will brake when the VehicleComponent requests.

Here is the Python API for Reference:

hasTraction : bool
hasBrake    : bool

---

Vehicle Controller

Just like we have a PlayerComponent to control the CharacterComponent physics, we also have this VehicleControllerComponent to control the VehicleComponent. You're not obbligated to use it since you can write your own controller by using the Vehicle's methods. But having it here definitely helps!

Methods

cave.VehicleControllerComponent

Variables

Variable	Description
active	The VehicleControllerComponent will only run if this is set to True (as it is by default). You can use this do temporarely disable the Vehicle Controller.

Here is the Python API for Reference:

active: bool