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

Step 1: Entity names

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.

Step 2: Collision shapes and mass

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

  scene1 = Engine.LoadScene( "level1.pak" )
  while ( Engine.Run() == true ) do
  end

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 Engine.LoadScene line. If we try to access the entities before the scene has been loaded, the code will crash because the 'scene1' variable ('scene1' variable is set to the current scene when Engine.LoadScene is successfully called) has not been set yet and the entities we want simply don't exist even if the 'scene1' variable would be set to a previous scene.

  scene1 = Engine.LoadScene( "level1.pak" )

  entity1 = Scene.GetEntityByName( scene1, "Plane"    )
  entity2 = Scene.GetEntityByName( scene1, "Cube.002" )

  while ( Engine.Run() == true ) do
  end

The Scene.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.

  scene1 = Engine.LoadScene( "level1.pak" )

  entity1 = Scene.GetEntityByName( scene1, "Plane"    )
  entity2 = Scene.GetEntityByName( scene1, "Cube.002" )

  Actor.SetPhysics( entity1, true )
  Actor.SetShape  ( entity1, MESH )
  Actor.SetMass   ( entity1, 0.0  )

  Actor.SetPhysics( entity2, true   )
  Actor.SetShape  ( entity2, SPHERE )
  Actor.SetMass   ( entity2, 1.0    )

  while ( Engine.Run() == true ) do
  end

The first argument Actor.SetPhysics 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:

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

Step 3: Spicing it up

A falling sphere is a bit boring, so lets spice it up and give it a little starting velocity.

  scene1 = Engine.LoadScene( "level1.pak" )

  entity1 = Scene.GetEntityByName( scene1, "Plane"    )
  entity2 = Scene.GetEntityByName( scene1, "Cube.002" )

  Actor.SetPhysics( entity1, true )
  Actor.SetShape  ( entity1, MESH )
  Actor.SetMass   ( entity1, 0.0  )

  Actor.SetPhysics( entity2, true   )
  Actor.SetShape  ( entity2, SPHERE )
  Actor.SetMass   ( entity2, 1.0    )

  Actor.SetLinearVelocity( entity2, 0.0, 0.0, 6.0 )

  while ( Engine.Run() == true ) do
  end

The Actor.SetLinearVelocity function takes the actor as the first argument, and the next three arguments are the velocity values for x, y and z axises.

Great! Now the sphere bounces a bit before it falls down. Thats it! I hope you enjoyed the tutorial, and if you have any comments about it, please post to the forums.