Manual

Physics

Table of Contents

1. Introduction
2. Quick Video How To Use Physics Components
3. Rigid Bodies and Colliders
- 3.1. Adding physics components using code
4. Physics Simulation in the Editor
5. 2D Games
6. Forces (Pushing, Rotating Bodies)
- 6.1. Transforming various objects
7. Ray-casting (Querying For Collision)
8. Detecting Collisions
9. Joints
10. Examples
11. Future plans (TODOs)
12. Old system for collisions and gravity

1. Introduction

Physics allows you to define rigid bodies that can

collide with each other (following the designated collider geometry)
are affected by forces (like gravity and custom forces you apply)
are connected by joints.

The physics collisions automatically result in a proper response, i.e. objects "bounce off" each other when they collide.

To achieve all this, Castle Game Engine is integrated with Kraft Physics Engine made by Benjamin 'BeRo' Rosseaux. Read on to learn how to add physics to your own games.

2. Quick Video How To Use Physics Components

3. Rigid Bodies and Colliders

Use these components (available in both editor and code) to control the physics.

TCastleRigidBody : This component activates processing the transformation by physics.
Colliders are components descending from abstract TCastleCollider:
- TCastleSphereCollider
- TCastleBoxCollider
- TCastleCapsuleCollider
- TCastlePlaneCollider (using this collider forces the body to be static)
- TCastleMeshCollider (using this collider forces the body to be static)
  
  A mesh that collides (referenced by TCastleMeshCollider.Mesh) can be TCastleScene, TCastleTerrain, or any primitive descending from TCastleAbstractPrimitive.

To make any TCastleTransform affected by physics add there a collider (any TCastleCollider descendant) and a rigid body (TCastleRigidBody).

In the editor, adding any collider automatically also adds the TCastleRigidBody, so you only need to do one step: add a collider. The usual way to do this is by right-clicking on a TCastleTransform instance in your hierarchy, and choosing from context menu "Add Behavior → Physics → Collider → …".

Note	Adding a collider from `2D` group will automatically also add `TCastleRigidBody` configured in an optimal way for 2D (using `TCastleRigidBody.Setup2D`).

Then run "Physics → Play Simulation" (use the menu item or button on the header) and observe that body is affected by

gravity
collisions with other objects.

Note that various components descend from TCastleTransform and thus can act as physics bodies: TCastleScene, primitives like TCastleBox, TCastleSphere, even terrains TCastleTerrain.

There are lots of options to tweak how things behave. See API docs for documentation.

You can visualize physics colliders (esp. useful if you disable the TCastleCollider.AutoSize on them and want to see the effect) using the menu item "Physics → Show Colliders".

The colliders in general should not collide at start. You should set up the colliders to avoid it. To make the collider smaller than automatically calculated you can:

disable the TCastleCollider.AutoSize and setup all collider sizes manually,
or set TCastleCollider.SizeScale to value like 0.9, to make the size (auto-detected or not) smaller by 90%.

Note

A good test to enjoy the physics is to make a "bullet" that will hit some rigid body with significant speed, so that you can see how it behaves on collision. To make a bullet, just

add some collider to the object you want to act as a bullet (this will also add TCastleRigidBody to it)
set TCastleRigidBody.LinearVelocity to something non-zero.

See quick demo movie.

3.1. Adding physics components using code

As with all CGE components, while you can add them by clicking in CGE editor (at design-time), you can also add them using Pascal code at run-time. Like this:

var
  NewBody: TCastleRigidBody;
  NewCollider: TCastleSphereCollider;
begin;
  NewBody := TCastleRigidBody.Create(FreeAtStop);
  //NewBody.Setup2D;
  MyTransform.AddBehavior(NewBody);

  NewCollider := TCastleSphereCollider.Create(FreeAtStop);
  NewCollider.Restitution := 0.6;
  NewCollider.Mass := 1;
  MyTransform.AddBehavior(NewCollider);
end;

4. Physics Simulation in the Editor

You can start a "Physics Simulation" right in the editor. This is a great way to test how physics behaves without the need to actually run the game.

During the simulation you can click around and modify the design even while the physics is runnning. Beware: the design will be restored to the original state when physics stops. If you want to really modify the design (not only make a temporary experiment), you should first stop the physics simulation.

Note	In the editor we only run the physics simulation, not your final game code. That said, various components may adapt to the "simulation" to behave in editor just as they do at run-time. Your custom components can adapt to simulation too, just honor the current `CastleApplicationMode` value.

5. 2D Games

The whole physics can work for 2D games as well as 3D. For 2D, remember to:

Adjust TCastleRigidBody by locking rotation/translation (such that the object stays within the same XY plane). It’s easiest to do this by calling TCastleRigidBody.Setup2D from code.

In CGE editor, just add "Physics → Rigid Body (2D)" component. Actually it will be added automatically if you add "Physics → Collider 2D → …".
Set TCastleCollider.Mode2D to true (to auto-size and to account for scale in a way better for 2D). In CGE editor, just add the "Physics → Collider 2D → …" components.

We feature a number of 2D physics demos in our examples on examples/physics, check them out.

6. Forces (Pushing, Rotating Bodies)

You can apply forces from code. This can be used to simulate forces other than gravity. For example: wind or explosion.

See demos:

examples/physics/physics_forces - test various methods to apply forces.
examples/physics/physics_explosion - test explosion.

To apply the force use on of these methods:

TCastleRigidBody.AddForceAtPosition - push objects in the given direction, with given strength, from the given position.
TCastleRigidBody.AddForce - push objects in the given direction, with given strength. The direction may be in local or global coordinate system.
TCastleRigidBody.AddTorque - rotate the objects using physics.
TCastleRigidBody.ApplyImpulse - apply an instant impulse. This is more instant way of affecting the velocity than the AddXxx methods above.

Here’s how an explosion can look like:

6.1. Transforming various objects

Instead of using forces, you can also just change the position/rotation of the object affected by physics, e.g. by directly changing TCastleTransform.Translation.

Whether this is a good idea, depends on the object type:

Dynamic objects: If the object has TCastleRigidBody.Dynamic = true (TCastleRigidBody.Animated is ignored in this case), it means physics simulation moves and rotates this object.

We allow you to change the object, e.g. by explicitly changing TCastleTransform.Translation, but you should refrain from doing it often. As you effectively override physics calculations, forcing the physics engine also to reposition your object in various internal structures.
Kinematic objects: If the object has TCastleRigidBody.Dynamic = false and TCastleRigidBody.Animated = true, you are welcome to transform this object. Physics engine is prepared for it.
Static objects: If the object has TCastleRigidBody.Dynamic = false and TCastleRigidBody.Animated = false, you can change the object transformation, but you should refrain from doing so.

Physics engine may optimize static objects. You make this optimization counter-productive (the physics engine will have to reposition your object in various internal structures) if you change the transformation of static object often.

7. Ray-casting (Querying For Collision)

Use the TCastleAbstractRootTransform.PhysicsRayCast to cast a ray and see whether it hits something. It takes and returns values (ray origin, direction, returned distance, point) in the world coordinate system.

Alternatively use the TCastleRigidBody.PhysicsRayCast which is similar, but takes parameters in the coordinate system of the parent TCastleTransform.

8. Detecting Collisions

You can detect whether a collision has occurred by

Assigning a callback to events TCastleRigidBody.OnCollisionEnter, TCastleRigidBody.OnCollisionStay, TCastleRigidBody.OnCollisionExit.
Or checking (e.g. in each view Update event) the value of TCastleRigidBody.GetCollidingTransforms.

See the examples/physics/physics_2d_collisions for a demo.

9. Joints

Joints allow to connect one physics body to another in some way that limits their ability to move/rotate relative to each other.

For example a hinge joint forces one physics body to only be rotated relative to another along a given axis. Like a door that is attached to a wall using hinges and can only rotate in a constrained way.

Hitting a physics body with something (like another physics body or using the forces API) will respect the joints.

Joints can be made breakable which means they can be broken if sufficiently big force is used.

Joints are simply components in Pascal that are derived from TCastleBehavior and can be attached to any TCastleTransform.

You can add them from CGE editor using the "Add Behavior → Physics → Joints → …" menu item.
Each joint component has a number of properties to control its behavior.
Often joints have some anchors that can be manipulated visually if you right-click on the joint component in the hierarchy and do "Show Joint Tools".

Note	Joints only make sense for `TCastleTransform` that are affected by physics. So you most often need add `TCastleRigidBody` and some `TCastleCollider` descendant to the same `TCastleTransform` that has a joint.

Here’s a demo:

10. Examples

We have a lot of examples dedicated to physics in the examples/physics subdirectory. Go ahead and check them out!

11. Future plans (TODOs)

Current physics engine integration is just a start. The plans are:

Expose Kraft layers. (Started: branch physics_layers)
Make TCastleWalkNavigation use physics to move (just like TCastleThirdPersonNavigation already can).
(See section below about "Old system") Currently we also have an older, simpler, internal physics/collision engine in CGE, that takes care of some tasks: the collisions of player and creatures (from CastleCreatures), a simple gravity for them, and custom collision methods for you (like RayCollision, SphereCollision etc. in CastleTransform unit). The new physics engine should eventually replace them all, and there should be a flag to make it possible, and eventually it should even become the default, and the old collision implementation should be simply removed.
A shape within the TCastleScene should be able to act like a rigid body, independent of the rest of the scene. Our current preferred plan to this is to depend that you will assign rigid bodies and colliders in CGE editor (or by Pascal code) to TCastleTransform created by the ExposeTransforms feature. And we can just synchronize changes from bones exposed by ExposeTransforms back to the original model.

This will allow you to attach physics to particular parts (any transformation) of the model.

We are close to realizing this goal, except that ExposeTransforms do not (yet) synchronize back their changes to the parent model.
Integration with other physics engines, through a layer providing a common API.

Our best candidate for proving an (alternative) physics engine is Bullet. Very full-featured, e.g. there’s soft body, not only rigid body.

Full integration with Bullet will require proper translation of Bullet API to C and then to Pascal (as Bullet is in C, it's not readily usable from anything other than C). There is a C header for Bullet, see this old Google Code issue and this GitHub issue, but it’s rather minimalistic (only rigid body), although it may be a good start.

12. Old system for collisions and gravity

In parallel to resolving collisions using physics engine (that honors the TCastleRigidBody and TCastleXxxCollider behaviors), for some purposes Castle Game Engine can also use an older "simple physics" implementation.

This "simple physics" implementation is fully implemented in CGE, without using Kraft or any other "full-blown" physics engine. Capabilities:

It can resolve collisions with (potentially dynamic) meshes using octrees, constructed for each TCastleScene or each shape of such scene.
Can perform simple (non-realistic) gravity.

It is used (for now) by:

FPS walk/fly navigation in TCastleWalkNavigation.
API to query for collisions in world-space coordinates using Viewport.Items.WorldXxx methods, like
API to query for collisions in coordinates of particular transform parent using TCastleViewport methods, like:

The long-term goal is to completely remove this "simple physics" implementation in CGE. All it’s functions can be, or will be, possible to achieve using "real physics engine" (like Kraft). But for the time being, some functions are still realized using this "simple physics". The relevant properties are:

TCastleSceneCore.PreciseCollisions:
- false indicates that scene collides as its bounding box.
- true indicates that we build and update a collision structure (octree) reflecting precisely the triangles in the scene. So the scene collides as a precise set of triangles.
This value matters also at design-time (in CGE editor). For larger scenes (like levels), it is necessary to set TCastleSceneCore.PreciseCollisions to true, otherwise picking smaller scenes (like creatures inside a level) will be impossible, because the big level scene will collide as a big box that includes everything.

Underneath, these is a deprecated property TCastleSceneCore.Spatial with a bit more options. But we advise to only use TCastleSceneCore.PreciseCollisions to toggle between the 2 above useful values.
TCastleTransform.Collides. By default this is true. When it is false, the transfomation object (and all its children) does not collide at all.

This affects all collision routines except RayCollision and RayCast that look at TCastleTransform.Pickable.
TCastleTransform.Pickable. By default this is true. When it is false, the transfomation object (and all its children) does not affect the results of ray collision (RayCollision and RayCast).
Note: when both TCastleTransform.Collides and TCastleTransform.Pickable are false, then TCastleSceneCore.Spatial and TCastleSceneCore.PreciseCollisions don’t matter. In such case, the object will not collide ever (neither as bounding box, nor as a precise mesh).
TCastleTransform.Gravity. When true, the relevant object falls down according to (non-realistic) gravity. It will honor (be stopped by) other objects that have Collides = true.
TCastleWalkNavigation.Gravity. When true, the player avatar falls down according to (non-realistic) gravity. It will honor (be stopped by) other objects that have Collides = true.

In the long-term, all these properties/methods will be

deprecated (and later removed)
or they will switch to using physics. They will honor whatever colliders you configure using the TCastleRigidBody and TCastleXxxCollider behaviors, and nothing more. And they will honor physics layers (coming soon).

So all collisions and all gravity should be done using physics engine.

To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax) and create a pull request to Castle Game Engine WWW (cge-www) repository.

Previous: How to render 2D games with images and sprites

Next: Sound

Manual

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.