L15: the Game Engine API

Today we continue our introduction to Python and we show how to setup a Blender session so that you can write and debug python controllers. We also go through a fairly sophisticated example of using Python controllers in a game, and then we turn to a more structured introduction to the use of Python in Blender Games.

Here are some useful links (which will also be placed in the Resources page on the class website -- at the left!)

Setting up a Blender Session

On windows, when you start blender you'll get an automatic command window which will show error messages from python programs. On a Mac, you need to start blender from a command window. I'll show how to do this in the screenrecorded lecture, but the basic idea is to go into your blender folder and copy the blender.app Then move to the applications folder and paste it there, and finally copy the blender.command file attached to this page into your applications folder. Double clicking on the blender.command file will start Blender from a terminal window where you can see the python error messages.

The blender.command file is a simple text file that contains the command to start the blender application/Applications/blender.app/Contents/MacOS/blender

City Quest demo

In this demo, we have a "monkey" avatar that is controlled by the arrow keys and the goal is to collide with all of the "jewels" which are currently represented as cubes.

Today we'll focus on how to use Python controllers to examine the rigid body state of the objects in the scene and to modify the positions, velocities, and forces/torques acting on those objects. This is useful for creating interesting enemy behavior.

First we look at how the jewel enemies are coded using the python module jewel.pyWhen a jewel collides with the avatar it calls the function jewel.teleport() which is defined as follows:

def teleport(): "move the object to the location of the object named 'portal' " # get current controller and the owner controller = bge.logic.getCurrentController() obj = controller.owner

# get the current scene scene = bge.logic.getCurrentScene() # and use it to get a list of the objects in the scene objList = scene.objects # get the avatar destination = objList["portal"] #find and print its position [x,y,z] = destination.position print("teleporting!") #print(str([x,y,z])) #set current position to destination obj.position = [x,y,z]

The first two lines are standard. We get the current controller and the current object. The next two statements grab the scene and the list of all objects in the scene. We use the objectlist to get the object whose name is "portal" which is where the jewel will be teleported. Next we get the position of the portal and set the jewel's position to the portal's position. We could have done this more simply using

where the last line sets the position of the current object to the position of the portal. We could even compress the function body into one line, as shown below, but the line gets too long and its too easy to make a mistake!

def teleport(): "move the object to the location of the object named 'portal' "bge.logic.getCurrentController().owner.position = bge.logic.getCurrentScene().objects["portal"].position

We will also discuss the following functions in the jewel module:

move - set the local linear velocity to some random value between -25 and 25

turn - set the local angular velocity to some random value between -15 and 15

increment_score - add 1 to the score property of the avatar object

chase_avatar - move toward the avatar at 50 m/s

Next we look at the avatar module and the following functions

seek_jewels - turn the avatar toward the closest jewel

list_jewels - print a list of all objects and their distance from the avatar, mark the jewels!

subtract - subtract two vectors

distance - find the distance between two points in space

and finally we look at the hud module and the function

update_score - get the score updates out of the message bodies and store them in the "Text" property