Using Python in the Blender Game Engine - Part 1

Hey, there. So, we'll be learning about using Python in the Blender Game Engine today.
Perhaps you've never heard of the Blender Game Engine; If so, then look at this previous entry explaining what the BGE is. Now,since I believe that the best way to learn is by doing, we'll be making... A Maze-type game! No, not one like Pacman, but one like the oldschool Atari game Adventure, or Berzerk. So, then, first you'll start up Blender. Since we'll be making a game, it would be wise to configure your window setup to be efficient for making games, and if you plan to make many games, then you should go into the File > User Preferences menu and select "Make Default". This will make it so that the windows you have set up in Blender will carry over each time you want to create a new .blend file or restart Blender.

The Basic Window Setup for Game Development (for me)

Now, then, you should have a Cube to start off with, as usual, like so. What we'll be doing is using Python for most everything in our game, including to move the cube, which will become our Player, so go ahead and rename the Cube to "Player". Open up a Logic Window (if there isn't one already; there is one built-in to the Game Logic screen on the default build of Blender 2.5), and plug an Always sensor into a Python controller. The Python controller will be running our player's Python script.

There are two different ways to code in Python for use in the Blender Game Engine. The first way is internally. This means that you script for each object to run in Blender itself, and point to the code via a Python controller. The second way is externally, which means coding a python script and saving it externally in the same directory as the blend file, then using a Python controller to point to the file and function that we wish to execute. The second method is what we will be using, as this also allows us the capability to code in an external text editor. One editor that is good is Komodo Edit, which is free and cross-platform.

The way this works is that we create a Python file (a file that ends in .py, a source file, or .pyc, a compiled source file that cannot be edited) that will hold the code our Player runs. Blender supports for multiple pieces of code per code file via functions, so we can make multiple objects run code that is in a single file. So, it's up to us how we organize our code - for example, the Player's code and the Player's bullet's code could be in the Player code file, while enemy code could be in an Enemy code file.
What we will be doing for our game is pretty simple - we specify each object (like the Player) to run a function that specifies how our object will behave. Here's the setup for the game logic in Blender.

Logic Brick setup for the Player - just an Always sensor with True pulse setting active going into a Python controller.

As can be seen, the Always sensor runs every frame, and drives the Python controller it is attached to. The Python controller is set to Module mode, which allows us to use external python files and run single functions, rather than having to use whole script files for separate objects. So, then as you can see, the Python controller is running an external script file - the first word is the file in which to find the script, and inside of it, which function to use. This script file, "Objects.py", contains a single function that we will be running - the Player function, which is the second half of the controller's setting. The Player function will be defined inside of the 'Objects.py' Python file. So, the Player can run the script by setting the controller's module to execute 'Objects.Player'.

OK, so on to the actual code. It's actually quite simple.

from bge import logic
def Player():

cont = logic.getCurrentController()

obj = cont.owner

print ("Hi! I'm at", obj.position)

Not too much to it, is there? Let's step through the code line by line, shall we?

from bge import logic

This line imports the logic submodule from the bge code module so that we can access it. The logic submodule contains useful functions and capabilities for us, like getting the current game scene or getting the current object, which we do below. The bge module also contains other modules, like render and types for use in-game.

def Player():

This line begins the definition of the Player function - this function is what the Player object in the Blender Game Engine runs, and will begin our code for the Player. Python uses indents to evaluate statements or define blocks of code. Every line after the def statement is in that block, and so that code is defined by the function name ("Player", in this case).

cont = logic.getCurrentController()

This line creates a new variable, cont, and sets it to be the controller used by the Player object in Blender. The controller of the script can be used to activate actuators, read sensors, and do other useful things.

obj = cont.owner

This line creates a new variable, like before, named obj. This variable is set to point to the owner of the code controller (The Player object itself). This is used to find out object-related variables, like position, rotation, and scale.

print ("Hi! I'm at", obj.position)

This line prints out a string, "Hi! I'm at", and also prints another value - the position of the object, next to the previous string. Now that the source code has been explained, you can play the game to see the result. Play (the P-key in the 3D window), and you should see something like this below...

As can be seen, the console of Blender is printed to every frame.

If you read the output, it reads "Vector" - what is that? Well, Vector is a built-in variable type in Blender. Vectors are like simple lists or arrays, but have additional variables and functions, like reflection or the ability to access the individual x, y, and z parts of the vector. If you want to learn more about Blender python, then you can use print( dir( function or variable ) ) to learn more about what a specific part of Blender can do. I would also recommend reading up on Python (specifically the version that Blender uses; To find out, check the console when starting Blender up). Here's the link to the download of the Maze Crawl Part 1 source code. Next up, we'll be moving our Player with Python!