General Usage: Physics
Telescope allows for high level physics simulations by using Bullet.
Adding Physics Objects
-
void TS_BtAddRigidBox(int id, float size_x, float size_y, float size_z, float mass, float position_x, float position_y, float position_z, bool is_kinematic = false)
add a rigid, axis-aligned collision box to the state
- Parameters
id – id of the newly created object
size_x – size along the x-dimension
size_y – size along the y-dimension
size_z – size along the z-dimension
mass – mass of the box
position_x – x-coordinate of the position of the box
position_y – y-coordinate of the position of the box
position_z – z-coordinate of the position of the box
is_kinematic – should the box be a kinematic object
-
void TS_BtAddStaticBox(int id, float size_x, float size_y, float size_z, float position_x, float position_y, float position_z)
add a static, axis-aligned collision box to the state
- Parameters
id – id of the newly created object
size_x – size along the x-dimension
size_y – size along the y-dimension
size_z – size along the z-dimension
position_x – x-coordinate of the position of the box
position_y – y-coordinate of the position of the box
position_z – z-coordinate of the position of the box
-
void TS_BtAddTriggerBox(int id, float size_x, float size_y, float size_z, float position_x, float position_y, float position_z)
add a box-shaped trigger to the state
- Parameters
id – id of the newly created object
size_x – size along the x-dimension
size_y – size along the y-dimension
size_z – size along the z-dimension
position_x – x-coordinate of the position of the box
position_y – y-coordinate of the position of the box
position_z – z-coordinate of the position of the box
Then, we remove any object by calling TS_BtRemovePhysicsObject, using the id we stored earlier
-
void TS_BtRemovePhysicsObject(int id)
remove a physics object from the state
- Parameters
id – id of the object
Moving Physics Objects
To move an object, we need to modify it’s velocity. This is the amount it moves in 3D spaces per “step”, which is what the smallest unit of time in the simulation is called.
To set an objects velocity, we use TS_BtSetLinearVelocity
-
void TS_BtSetLinearVelocity(int id, float velocity_x, float velocity_y, float velocity_z)
set the linear velocity of a physics object
- Parameters
id – id of the object
velocity_x – velocity along the x-dimension
velocity_y – velocity along the y-dimension
velocity_z – velocity along the z-dimension
For the object to actually move, we need to advance the simulation by at least one step. This is accomplished by using TS_BtStepSimulation:
-
void TS_BtStepSimulation()
advance the physics simulation by one step
When an object is moving, there is potentially more than one variable that affects it’s position per step: gravity.
Each object has a mass. We choose it during object creation before. We can then set the global amount of gravity (in any direction, not just towards the ground like in real life) by using TS_BtSetGravity:
-
void TS_BtSetGravity(float gravity_x, float gravity_y, float gravity_z)
set the global gravity
- Parameters
gravity_x – acceleration along the x-dimension
gravity_y – acceleration along the y-dimension
gravity_z – acceleration along the z-dimension
Collision Detection
When we have multiple objects moving in space, eventually, some will collide. Each step, Telescope will queue a number of TS_CollisionEvent, one representing each collision between two objects:
-
struct TS_CollisionEvent
event used to check whether two objects are colliding
To access the lates collision event, we use TS_BtGetNextCollision
-
TS_CollisionEvent TS_BtGetNextCollision()
query the next collision event
- Returns
TS_CollisionEvent, contains two ids of colliding objects
This way, we can keep track of all the objects moving around.
Each physics objects has a bounding box. This is the space it occupies in all 3 dimensions. During simulation, we sometimes want to increase the minimum amount of space the distance between the surface of two objects can be. This is useful to avoid “clipping”, where two graphics objects collide.
To do this, we increase an objects margin using TS_BtSetCollisionMargin
-
void TS_BtSetCollisionMargin(int id, float margin)
set the outer margin of a specific collision object
- Parameters
id – id of the object
margin – distance between the surface and the outer margin of the object