The Aim[]
Properties are a useful part of the game engine. They allow weapons to be selected, health to be determined and a whole host of other things. This tutorial will teach you how to start a python script and how to access the properties belonging to a game object.
Because a script runs once per frame, if you have information to preserve over a frame, properties are a useful place to put it.
The Outlines of a Script[]
You may have noticed that nearly all blender python scripts start with the following three lines:
import bge cont = bge.logic.getCurrentController() own = cont.owner
Before it goes on to do other things. There is a good reason for this.
The first line is the python way of importing an already existing script. In this case, it is importing bge: the blender game engine. Doing so allows us to access functions and objects inside the game.
A simple python setup
The second line goes and gets the controller the script is running from. A script has to be run from a controller system, like teh one pictured to the right. This line creates a variable pointing to this controller.
The third line creates a variable pointing at the game object containing the logic brick running the script. Get that? Well, let's say we have an object named Cube. In it is a python controller named 'Controller.' The second line will get 'Controller' and the third line will get 'Cube'.
Once we have these three things done we can start doing something in our script.
Getting a Game Property[]
Let's say we had create a property in our object before we started the game. We now want to access it from our script. We can do this with code similar to this:
property_value = own['property_name']
What this does is it takes a game object (own, which we defined earlier), and find the property with a given name. There are a couple of errors that you may hit when getting a property. These will show up in the system console, and will be things like:
Traceback (most recent call last): File "script.py", line 4, in <module> KeyError: 'value = gameOb[key]: KX_GameObject, key "property_name" does not exist'
What this means is that the property with that name does not exist, most likely because you mistyped the properties name. Note that python is sensitive to capitals.
Setting a Game Property[]
Setting a game property is pretty much the inverse of getting it's value. It uses the code:
own['property_name'] = property_value
This requires a game object (own) and the value we are setting it to. Pretty simple really. It is pretty hard to get an error with this line of code, because if the property does not exist, then python will create it.
An Example []
The text object is the perfect way to demonstrate setting and editing properties, since they use a game property as their input.
So, create a new blend file, delete the default cube, and add a text object (Add Object -> Text).
We'll also make a couple other things:
- A text document called 'Text.py'
- A game property called 'Text' on the text object
- The following logic:
- Always (pulse mode 60) -> Python (Script 'Text.py')
See the image to the right for the setup.
Setup for teaching how to access python properties
Now we have to put something into our program. So for starters, let's display the current text:
cont = bge.logic.getCurrentController() own = cont.owner print(own['Text'])
If you now play your game, in the system console you should see, printed once every second, the contents of the text object. By default this is 'Text', but if you change it, you should see whatever you changed it to.
So how about editing it?
Well, if we replace our script with:
cont = bge.logic.getCurrentController() own = cont.owner own['Text'] = 'Some New Text'
Our text object should change to show 'Some New Text.' Do you see how this works?
Or we can do a combination of the two, and add something to the end:
cont = bge.logic.getCurrentController() own = cont.owner own['Text'] = own['Text'] + '.'
Now every second a dot will appear at the end of the text object.
Extra Challenges:[]
- Spell out a whole sentance word by word, a new word every second. (tip: how often does a script run?)
- Make a flashing cursor at the end of your text object (use the | character as a cursor, it's the key above enter)