Awerere Physics Engine

Rubeus: Awerere Physics Engine

Created by SDSLabs with ❤️

(pronounced as 'auror')

Awerere is a homegrown physics engine currently supporting circle, squares and straight lines. It is designed to specifically with Rubeus and the RML(Rubeus Maths Library) library.

How to use it?

First, let us get familiar with some of the Awerere jargon:

• Each game object has a ACollider object attached to it. This ACollider class is accessible in the Rubeus::Awerere namespace. Awerere keeps track of all colliders initialised and it is currently designed to update the collision status of each object every frame.

• Shapes supported by Awerere:

  • Spheres/circles a.k.a. ASphereCollider
    • Defined by center position and radius value
  • Axis aligned bounding boxes/rectangles a.k.a. ABoxCollider
    • Defined by lower left corner position and an upper right corner position
  • Straight lines a.k.a. APlaneCollider
    • Defined by a normal vector and a point on the 2D space.

All of the different types of colliders are child classes of ACollider Let us take an example of creating two different squares that bounce around and allows Awerere to handle the collisions in between them.

Steps:

1. Create two different game objects named as Foo and Bar. Use the Making a ping-pong game guide to see how to set up a project and further creating your own game objects. For now we may use the default image available to us i.e. /RubeusCore/Assets/debug.png.

2. Your user_init.cpp should look like this in the end:

UFoo * Foo = new UFoo(
	"Foo",
	"sample_level",
	6.0f, 3.0f,
	3.0f, 3.0f,
	"Assets/debug.png",
	true,
	Rubeus::Awerere::EColliderType::BOX,                               // Type of collider. We need EColliderType::BOX
	new Rubeus::Awerere::ABoxCollider(RML::Vector3D(6.0f, 3.0f, 1.0f), // Lower left corner position of the collider
                                          RML::Vector3D(9.0f, 6.0f, 1.0f)),// Upper right corner position of the collider
	true                                                               // Whether this object reponds to collision.
                                                                           // We need this object to bounce back from surfaces,
                                                                           // So this parameter needs to be turned on
);

UBar * Bar = new UBar(
	"Foo",
	"sample_level",
	10.0f, 3.0f,
	3.0f, 3.0f,
	"Assets/debug.png",
	true,
	Rubeus::Awerere::EColliderType::BOX,
	new Rubeus::Awerere::ABoxCollider(RML::Vector3D(10.0f, 3.0f, 1.0f),
					  RML::Vector3D(13.0f, 6.0f, 1.0f)),
	true
);

Notice that the enablePhysics parameter is now turned to true and we have provided the constructor with our own collider objects. Use intellisense and the Rubeus API documentation to know what each parameter does to the game object.

3. Run your level by setting startupLevel = "sample_level" at the top of user_init.cpp.

4. You will find that when the level runs, nothing happens and the boxes just fall down due to gravity. You will need to add some velocities to these boxes first and also disable their gravity.

5. See if you can figure out how to get a reference to the ABoxCollider object attached with Foo and Bar (Use a lot of intellisense if you want to find your way around Rubeus' class structure).

6. You will need to set the m_Momentum object to a non-zero vector and find the reference of the APhysicsMaterial object linked to Foo and Bar objects. Change the m_Gravity object of the linked APhysicsMaterial object, so that all its spatial components are 0.0f.

7. Run the game and play with the velocity and acceleration values to get a hang of how things work in Rubeus. You can also map inputs to add different velocities to the objects based on the button pressed.

Awerere can handle all permutations of collisions amongst all pairs consisting of the above-mentioned shapes.

Contributor's Guide

Awerere's Collision Engine uses a grid based collision detection algorithm that works in O(n^2) but offers more speed when compared to the naive O(n^2) way to checking collision with every other object in the 2D world.

The engine assumes the world covered by a grid of cells and maintains a string containing bool values for each object of whether that object falls in the region covered by that particular cell. These strings are then logically ORed (boolean algebra) to find whether there is any chance of a collision between objects lying in different cells.

If any of the OR operations return true (i.e. any non-zero value), then the collision is absolutely calculated and a hit event is generated.

These hit events are then evaluated during the rest of the update loop.

The collision response process of Awerere is completely homegrown and it under active maintenance. There may be bugs popping up in game objects involving multiple collisions with different types of colliders all at once. If you happen to find such a bug, please look into tryIntersect() functions defined for each collider. These functions handle the narrow-phase collision detection algorithm for each pair of colliders.

To debug the collision response, looking into narrowPhaseResolution() under Rubeus::Awerere::APhysicsEngine namespace would be a good place to start looking for bugs.