Physics
1. Introduction
Physics allows you to define rigid bodies that can collide with each other (following the designated collider geometry). These collisions (by default) automatically result in proper response, i.e. objects "bounce off" each other when they collide.
Castle Game Engine is integrated with Kraft Physics Engine made by Benjamin 'BeRo' Rosseaux. Read on to learn how to add rigid-body physics to your own games.
2. Demo Videos
3. Usage
You can turn any TCastleTransform instance into a rigid body, which means that it will be affected by gravity and collisions with other rigid bodies. TCastleScene, which you use to render 3D objects, is a descendant of TCastleTransform, so this implies that TCastleScene can be a rigid body too. Or you can use TCastleTransform as a container for other transformations and scenes inside, and thus a group of objects can be treated as a single rigid body.
To make a rigid body you need to:
-
Create
TCastleScene(see also viewport and scenes documentation). -
Create and configure an instance of
TRigidBody. -
Create and configure an instance of some
TColliderdescendant, likeThe collider will be connected to the parent rigid body at construction (the
TRigidBody.Colliderproperty will be automatically set when creating the collider). -
Link to your rigid body from the
TCastleTransform.RigidBodyproperty.
This is a sample code:
var
Scene: TCastleScene;
RigidBody: TRigidBody;
Collider: TBoxCollider;
begin
// Create TCastleScene
Scene := TCastleScene.Create(Application);
Scene.Load(URL);
Scene.Spatial := [ssRendering, ssDynamicCollisions];
// Scene.Translation := Vector3(1, 2, 3); // set initial position
// Create TRigidBody
RigidBody := TRigidBody.Create(Application);
// RigidBody.Dynamic := ?; // boolean, default true
// RigidBody.Gravity := ?; // boolean, default true
// RigidBody.InitialLinearVelocity := Vector3(10, 0, 0);
// Create TCollider (a TBoxCollider, to be more precise, in this case).
// Note that TBoxCollider assumes that box is centered around (0,0,0) for now
Collider := TBoxCollider.Create(RigidBody);
Collider.Size := Scene.BoundingBox.Size;
// Collider.Restitution := 0.3;
// Collider.Density := 100.0;
// Connect rigid body
Scene.RigidBody := RigidBody;
// Add Scene to the Viewport, to make it visible
Viewport.Items.Add(Scene);
end;See physics_3d_demo, in particular the physics_3d_demo/code/gameinitialize.pas source code, for a complete working example.
Notes:
-
Right now the instruction to assign
TCastleTransform.RigidBodyshould be at the very end, when you configured all the rigid body and collider parameters. Right now, this is when the rigid body is actually created on the physics engine side. Right now changing the properties of rigid body or collider later has no effect (if you need it, the temporary workaround is to setTCastleTransform.RigidBodytoniland then again to yourTRigidBodyinstance). -
The collider shape is not synchronized with the scene shape in any way. This also applies to the
TMeshColliderthat has aTMeshCollider.Scene: the mesh is created once from the scene geometry, it is not synchronized with scene changes later. (If you need it, the workaround is the same as above: setTCastleTransform.RigidBodytoniland then again to yourTRigidBodyinstance. But creating a mesh collider is a costly operation, so think twice before doing this during the game!)
4. Physics in 2D games
Although internally Castle Game Engine and Kraft work in 3D, the physics can work just fine for 2D games too.
-
Simply position everything around Z = 0 (or any other Z = constant plane).
-
When creating colliders, make sure that they have some non-zero size in Z axis too. Even though the Z axis is not visible in 2D games, but the colliders need to have some volume in all 3 axes.
-
Constrain rotations and movement of dynamic rigid bodies to 2D by calling
TRigidBody.Setup2D.
The example how to do this is in physics_2d_game_sopwith (see in particular the physics_2d_game_sopwith/code/gameinitialize.pas source code).
5. Future plans (TODOs)
Current physics engine integration is just a start. The plans are:
-
Expose physics to be available in editor, by making
TCastleRigidBodyandTCastleColliderbe descendants fromTCastleBehavior. As of 2022-02-07, Andrzej Kilijański is working on it, so it will happen soon :) -
Expose Kraft layers.
-
Enable to "run" physics in the editor, by saving the state + observing the effect of physics.
-
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.
-
The current implementation doesn’t expose any API for joints.
-
Maybe: A shape within the TCastleScene should be able to act like a rigid body, independent of the rest of the scene. Ideally, this should be configurable in Blender, and exported nicely to glTF or X3D. The X3D specification has a rigid-body component to describe such things.
Our current preferred plan to this is resign from X3D and Blender integration for this, instead depend that you will assign rigid bodies and colliders in CGE editor (or by Pascal code). If we can just synchronize changes from bones exposed by
ExposeTransformsback to the original model, this will allow you to attach physics to particular parts (any transformation) of the 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.
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.