BlendELF, Tutorial 4, Physics and Collision Basics

This tutorial builds on the first tutorial, so be sure to do that first! [Tutorial 1, BlendELF Basics]

In this tutorial you will learn how apply some physics and collision to objects.

NOTE: there was a bug in the physics system which I fixed and uploaded new builds of the BlendELF 0.9 Alpha 3 development kit, so if you downloaded the development kit before this tutorial came out (2010.3.13 01:15 GMT), please redownload the development kit.

Untill now we haven't really accessed other actors in the scene besides the camera. Now we will be accessing some entities so that we can set some physics and collision settings for them.

Actors in a scene usually have a name which you can use to refer to them. The image below shows you the names of the actors (in this case, entities) we will be accessing in this tutorial:

Why is a sphere named Cube.002 you ask? Well, its a long story and completely irrelevant to this tutorial, so for now, just accept that it is a sphere named Cube.002...

So we will be accessing two entities, the ground entity named Plane and the sphere entity floating above it named Cube.002.

Now we will get to the code. Currently your code should look like this:

First we need get the entities we are going to modify. We can access the entities only after the scene has been loaded, so we put the code lines for that below the elf.LoadScene line. If we try to access the entities before the scene has been loaded, the code will crash because the scn variable (scn variable is set to the current scene when elf.LoadScene is successfully called) has not been set yet and the entities we want simply don't exist even if the scn variable would be set to a previous scene.

The elf.GetEntityByName takes the scene we want to get an entity from as the first argument and the name of tne entity as the second argument. Now that we have the entities, we can set the physics for them.

The first argument elf.SetActorPhysics takes is the actor we want to modify. The second argument is the collision shape we want to set the actor to and the last argument is the mass of the actor.

Wait, collision shapes?

All actors enabled with physics must have a valid collision shape so that the physics engine can calculate the collisions. A collision shape is basically a shape which encloses the actor. Here is an overview of the available collision shapes:

elf.BOX - a simple box shape
elf.SPHERE - a simple sphere shape
elf.MESH - a shape consisting of the polygons of the entity, this works best for static objects
elf.CAPSULE_X - capsule along the X axis
elf.CAPSULE_Y - capsule along the Y axis
elf.CAPSULE_Z - capsule along the Z axis
elf.CONE_X - cone along the X axis
elf.CONE_Y - cone along the Y axis
elf.CONE_Z - cone along the Z axis

Most of the shape sizes are automatically calculated for you according to the mesh of the entity (assuming that the actor we are enabling physics for is an entity), so you don't have to worry about them. You can however set sizes yourself with elf.SetActorBoundingLengths. The elf.MESH shape doesn't need any calculation because the mesh data for an entity is already loaded into BlendELF and supplied to the physics engine.

Okay.. but why are we setting the mass of the "Plane" entity to 0.0?

Because we don't want the Plane entity, which acts as our ground, to fall down. In BlendELF, a mass of 0.0 means that the object is static. Thus it only affect other entities, but forces and velocities don't affect it.

Try running BlendELF. You should see sphere that falls on the ground and rolls to the darkness. If you did, congratulations!