Python Scripting in Blender

Python Scripting in
Blender
Gordon Erlebacher
Fall 2012
Tuesday, October 2, 12
Audience
• Python classes are for the programmers
• Non-programmers should try to
understand, but will not be required to do
homeworks based on Python
• Non-Programmers and Programmers must
work together to develop the game, not in
isolation
Python Console
Python Basics
• From the command line (mac/linux/
windows with cygwin)
• type python
>>> 3+3
6
>>> a = “gor”; b = “fran”
>>> a + b
>>> ‘gorfran‘ # concatenation of strings
Scripting Language
• Write Python in
• Blender Window
• Editor outside Python
• An interpreter reads each line, checks for errors
and executes the line
• it is somewhat more complex than that
• Allows complex interactions not possible in the
game engine
Example
print(5+6)
exit() # Stop the program
print("x = 6") # line is never executed
Example
print(5+6)
exit() # Stop the program
a = 3/; # Error (stops program from running)

print("x = 6") # line is never executed
•First, the program is checked for syntactical errors
•Second, the program is executed
When to use Python
• When the logic panel becomes too complex and hard to
understand
• In situations with complex series of states
• When multiple objects should interact with each other
• When one wishes to create actions (animations) on the fly
• Fancy use of random numbers
• Program complex motions
• Handle the mouse
• Handle multiple cameras, multiple players, multiple viewports
• ... whatever your imagination dictates ...
Everything is an Object
• Actuator, Controller, Sensor
• Mesh
• IPO
• Texture, Material
• Camera
• etc.
Scenes
• One can construct one or more scenes

• Each scene contains a collection of objects
• Objects can be shared between scenes
• Scenes help with level design
Documentation
• Documentation of 2.63 API
• Code fragments (outside the game engine)
• Thread on scripts (outside the game
engine)
• 2.6 Manual (with section on game engine)
• Blender Basics, 4th Edition
Interactive Console
MacOSx/Linux
cd /Applications/blender-2.63a-release-
OSX_10.6_x86_64/blender.app/Contents/
MacOS/
./blender # start blender
# errors will be printed out to the window

blender is started in.
Windows XP/Visa/7
When Blender is started on a Windows operating system, the Console Window is first
created as a separate window on the desktop. Assuming that the right start-up
conditions are met, the main Blender window should also appear and the Console
Window will then be toggled off. This is unlike the 2.4x series where theConsole
Window would remain visible while the main Blender window was open. To display the
console in current versions of Blender, go to Help » Toggle System Console.When
Blender is started on a Windows operating system, the Console Window is first created
as a separate window on the desktop. Assuming that the right start-up conditions are
met, the main Blender window should also appear and the Console Window will then be
toggled off. This is unlike the 2.4x series where theConsole Window would remain
visible while the main Blender window was open. To display the console in current
versions of Blender, go to Help » Toggle System Console.
Module bge
• bge : Blender Game Engine
• First program:
• import bge
print(dir(bge))
• Output
• Blender Game Engine Started
['__doc__', '__name__', 'constraints', 'events', 'logic', 'render',
'texture', 'types']
['__doc__', '__name__', 'constraints', 'events', 'logic', 'render',
'texture', 'types']
• Blender Game Engine Finished
Simplest Program
Python script
How to use the output
import bge
print(dir(bge))
#['__doc__', '__name__', 'constraints', 'events', 'logic', 'render', 'texture', 'types']
print(dir( bge.events))
['__doc__', '__name__', 'constraints', 'events', 'logic', 'render', 'texture', 'types']
['ACCENTGRAVEKEY', 'AKEY', 'BACKSLASHKEY', 'BACKSPACEKEY', 'BKEY',

'CAPSLOCKKEY', 'CKEY', 'COMMAKEY', 'DELKEY', 'DKEY', 'DOWNARROWKEY',
'EIGHTKEY', 'EKEY', 'ENDKEY', 'ENTERKEY', 'EQUALKEY', 'ESCKEY', 'EventToCharacter',
'EventToString', 'F10KEY', 'F11KEY', 'F12KEY', 'F13KEY', 'F14KEY', 'F15KEY', 'F16KEY',
'F17KEY', 'F18KEY', 'F19KEY', 'F1KEY', 'F2KEY', 'F3KEY', 'F4KEY', 'F5KEY', 'F6KEY',
'F7KEY', 'F8KEY', 'F9KEY', 'FIVEKEY', 'FKEY', 'FOURKEY', 'GKEY', 'HKEY', 'HOMEKEY',
'IKEY', 'INSERTKEY', 'JKEY', 'KKEY', 'LEFTALTKEY', 'LEFTARROWKEY',
'LEFTBRACKETKEY', 'LEFTCTRLKEY', 'LEFTMOUSE', 'LEFTSHIFTKEY', 'LINEFEEDKEY',
'LKEY', 'MIDDLEMOUSE', 'MINUSKEY', 'MKEY', 'MOUSEX', 'MOUSEY', 'NINEKEY',
'NKEY', 'OKEY', 'ONEKEY', 'PAD0', 'PAD1', 'PAD2', 'PAD3', 'PAD4', 'PAD5', 'PAD6', 'PAD7',
'PAD8', 'PAD9', 'PADASTERKEY', 'PADENTER', 'PADMINUS', 'PADPERIOD',
'PADPLUSKEY', 'PADSLASHKEY', 'PAGEDOWNKEY', 'PAGEUPKEY', 'PAUSEKEY',
'PERIODKEY', 'PKEY', 'QKEY', 'QUOTEKEY', 'RETKEY', 'RIGHTALTKEY',
print(bge.logic)
['BL_DST_ALPHA', 'BL_DST_COLOR', 'BL_ONE', 'BL_ONE_MINUS_DST_ALPHA',
'BL_ONE_MINUS_DST_COLOR', 'BL_ONE_MINUS_SRC_ALPHA',
'BL_ONE_MINUS_SRC_COLOR', 'BL_SRC_ALPHA', 'BL_SRC_ALPHA_SATURATE',
'BL_SRC_COLOR', 'BL_ZERO', 'CAM_POS', 'CONSTANT_TIMER',
'CONSTRAINT_IK_COPYPOSE', 'CONSTRAINT_IK_DISTANCE',
... many more items ...
EWMATRIX_TRANSPOSE', '__doc__', '__name__', '__package__', 'addScene', 'endGame',

'error', 'expandPath', 'getAverageFrameRate', 'getBlendFileList', 'getCurrentController',
'getCurrentScene', 'getExitKey', 'getLogicTicRate', 'getMaxLogicFrame', 'getMaxPhysicsFrame',
'getPhysicsTicRate', 'getRandomFloat', 'getSceneList', 'getSpectrum', 'globalDict', 'keyboard',
'loadGlobalDict', 'mouse', 'restartGame', 'saveGlobalDict', 'sendMessage', 'setExitKey',
'setGravity', 'setLogicTicRate', 'setMaxLogicFrame', 'setMaxPhysicsFrame', 'setPhysicsTicRate',
'startGame']
Do not sweat
the details
Example 1
Make a cube move with the Akey
bge.logic.getCurrentScene()
['__class__', '__contains__', '__delattr__', '__delitem__',
'__doc__', '__eq__', '__format__', '__ge__', '__getattribute__',
'__getitem__', '__gt__', '__hash__', '__init__', '__le__', '__lt__',
'__ne__', '__new__', '__reduce__', '__reduce_ex__',
'__repr__', '__setattr__', '__setitem__', '__sizeof__', '__str__',
'__subclasshook__', 'active_camera', 'activity_culling',
'activity_culling_radius', 'addObject', 'cameras', 'dbvt_culling',
'drawObstacleSimulation', 'end', 'get', 'invalid', 'lights', 'name',
'objects', 'objectsInactive', 'post_draw', 'pre_draw', 'replace',
'restart', 'resume', 'suspend', 'suspended']
Scene objects
import bge
control = bge.logic.getCurrentController()
scene = bge.logic.getCurrentScene()
objs = scene.objects
print(objs)
#Output
[Cube.001, Cube, __default__cam__]
What are keyboard sensor
properties?
cube = objs[‘Cube.001’]
sensor = cube.sensors[‘mykey’]
print(sensor)
['__class__', '__delattr__', '__doc__', '__eq__',
'__format__', '__ge__', '__getattribute__', '__gt__',
'__hash__', '__init__', '__le__', '__lt__', '__ne__',
'__new__', '__reduce__', '__reduce_ex__', '__repr__',
'__setattr__', '__sizeof__', '__str__', '__subclasshook__',
'events', 'executePriority', 'frequency', 'getKeyStatus',
'hold1', 'hold2', 'invalid', 'invert', 'key', 'level', 'name',
'neg_ticks', 'owner', 'pos_ticks', 'positive', 'reset', 'status',
'tap', 'targetProperty', 'toggleProperty', 'triggered',
'useAllKeys', 'useNegPulseMode', 'usePosPulseMode']
Press and release akey
import bge
control =
bge.logic.getCurrentController()
objs = scene.objects The printout occurs twice.
cube = objs['Cube.001'] WHY?
sensor = cube.sensors['mykey']
print(dir(sensor))
Controllers and pulses
• The python controller gets called every time
a pulse hits it
• The keyboard sensor sends a positive pulse
when the key is pressed
• The keyboard sensor sends a negative pulse
when the key is released
• How to prevent the negative pulse from
having an effect?
Avoid negative pulse
import bge
control = bge.logic.getCurrentController()
objs = scene.objects
cube = objs['Cube.001'] The printout only occurs
sensor = cube.sensors['mykey'] when the key is pressed
if (sensor.positive):
print(dir(sensor))
Notice the “:” in the “if statement”

Also: lines inside “if statement” all have the same indentation
(imposed by Python)
Now, avoid keyboard
sensor
• It is possible to have python capture
keyboard events, without a sensor
• Advantage: you can give the Python code to
your friend
• More complicated, so we will avoid this for
now
• Working with Python sensors/actuators is
faster then writing your own, in most cases
Two Cameras
• Create a cube and a cone
• camCube and camCone are two cameras,
which point to the cube and to the cone
• “akey” will select the camCube
• “bkey” will select the camCone
• First step: create the scene
(two_cams_python.blend)
Add two camera actuators, one tracking the cube, one
tracking the cone.
Tracking constraints are not maintained in the game engine
Object
• bge is an object
• bge has the following variables/subclasses
['__doc__', '__name__', 'constraints',
'events', 'logic', 'render', 'texture', 'types']
• Each subclasses has its own subclasses and
so on
• Check out the API documentation
Control of the Mouse
• Use the MouseLookup.py module

• Download from class website (Oct.2/Oct.
4)
• How does it work?
Steps
• Parent a camera to a character object
• The camera is the child of the character
• The character is the parent of the camera
• The character is a dynamic object
• rigid might make the object rotate
• Create flow logic for the camera
• All objects can have any name
• Example on next slide
Properties that control the
Mouselookup script
Code in file: mouselook.py

Execute main function, which is
the entry point:
mouselook.main
The source code is not loaded with Python. If the blender file is
transferred elsewhere, remember to transfer the source files as well
Try it out!
• http://www.sc.fsu.edu/~gerlebacher/gd/
• mouseCamera.blend
• Activate layer 2 only
• Layer 1 contains the example that comes with mouselook.py
package.
• 0key to see the view from the camera
• pkey to start the game
• use mouse to rotate the view, then ASWD to move the
dynamic object around (and the parented camera will follow)
Object Properties
How are they used from within Python?
Let us do something not possible without Python ...
Object Rotation
• Start an object to rotate slowly (keyboard
Rkey)
• Every time the Rkey is pressed, the object
will rotate a little faster
• Without Python, the rotation value in the
motion actuator is a fixed value, which
cannot be changed.
Constant Rotation
Key ups are ignored
Once the motion actuator is

turned on, motion only stops
when it is deactivated
No Deactivation
Script: rotate_start_nostop
Better: cube = cont.owner

Usually bad idea to use specific
object names. If the object name
changes, strange things might
happen
The motion actuator is never deactivated
Properties
Get property ‘acc’

Use default -.01 if non-existent
The property value is always the

same when accessed. How to
change it?
Update Property
Every time the key is pressed,
rotz increases by 0.01
Keeping the key pressed does not
increase the acceleration
Increase the acceleration by keeping a
key pressed: simply use positive
frequency button
Global Variables
• I would like to keep track of the total

number of enemies: nb_enemies
• Multiple objects would like to access this
property
• How is this done?
Method 1
• Choose an object in the game, and give it a property:
‘nb_enemies’
• cube[‘nb_enemies’] = 5
• Another object: hero, needs access to ‘nb_enemies’
• Inside a script for hero,
cube = objects[‘cube’]
nb_en = cube[‘nb_enemies’]
• Disadvantage: Why should this variable be associated with
‘cube’? If all objects need access to this variable, better to have
a more centralized location. Thus the game dictionary.
Method 2:
Game Dictionary
• bge.logic.gameDict
• Initially, the dictionary is empty
• Initialize variables in the game:
• bge.logic.gameDict[‘nb_enemies’] = 3
• update as needed
• access:
nbe = bge.logic.gameDict[‘nb_enemies’]
Always sensor: only gets executed once.
Useful for one-time initializations
save and load globalDict

Save variables between game restarts
When is game restarted?
- when player gets killed (same level)
- when moving from one level to the next
Without save/load
Change Scenes
• Create two scenes
• Scene1: a cube, light, camera
• health [0-100] property
• Scene2: a cone, light, camera
• Same health property
• Store health in globalDict.
• maintained between scenes
Cube Scene
Change scene
Cube.001
cube.camera
Cone Scene
Cone.001
cone.camera
Change scene
Notes
• Camera trackers are required
• A TrackTo contraint outside the game engine is not respected
inside the game engine
• The globalDict is not destroyed when changing scenes,
however,
• Object properties are reset to initial values when changing
scenes. Thus, the advantage of the globalDict
• What about when a game is restarted?
• Object variables can be initialized from the dictionary in an
initialization python script (once per game, or for each object)
Blender 2.49a
Anatomy of a program
(blender 2.49b)
• Import GameLogic # not required
• cs = getCurrentScene()
• objs = cs.objects
• gd = GameLogic.globalDict;
• gd[‘house’] = ‘number of bullets’
gd[‘nb_bul’] = 30
• I stored two variables in the Global Dictionary
• Any object can access the global dictionary, from any
script, from any scene
Anatomy of a program
(blender 2.59)
• Import bge # not required
• cs = bge.logic.getCurrentScene()
• objs = cs.objects # list of all objects in the scene
• gd = bge.logic.globalDict;
• gd[‘house’] = ‘number of bullets’
gd[‘nb_bul’] = 30
• I stored two variables in the Global Dictionary
• Any object can access the global dictionary, from any
script, from any scene
Printing variables
• print(objs)
• parenthesis are very important!!! Not necessary in the
past
• printout can be seen on the console
• on Windows, the console is behind the Blender
window
• on the Mac, one must start Blender from the command
line within a window, which becomes the console
• Printing simplifies debugging
Arrays
• How to store objects and information
• In Python, use lists
• a = [4,5,6] (all the same type)
• b = [73,‘gordon’, -45.34] (different types)
• a[0]+b[2] ==> 4-45.35 = -41.35
• different types, but integer converted to float
• a[0]+b[1] ==> error (different types)
• string ‘gordon’ cannot be converted to integer
Accessing properties
con = bge.logic.getCurrentController()
sc = bge.logic.getCurrentScene()
print(sc.objects) # prints to console
ob = sc.objects['Cube']
print dir(ob)
Hash tables
• Special kind of array
• Array index can be any type (object, string, ...)
• a = {} # dictionary creation
• a[‘gordon’] = 3
• a[5] = ‘blender’
• a[6] = 23.5
• a[‘gordon’] + a[6] ==> 26.5
Dictionary
is a hash table
GameLogic = bge.logic
con = GameLogic.getCurrentController()
sc = GameLogic.getCurrentScene()
print(sc.objects)
ob = sc.objects[‘Cube’]
print(dir(ob))
a = {}
a[ob] = 3 # argument can be list, integer, float, string
a[sc] = ‘gordon‘ # probably will not work
print(a)
Example
demonstrate_simple_python_script.blend
Program name: test_program
import bge
GameLogic = bge.logic
con = GameLogic.getCurrentController()
sc = GameLogic.getCurrentScene()
print(sc.objects)
ob = sc.objects['Cube']
print(dir(ob))
a = {}
Storing information in
objects
• # ob name is ‘Cube’
ob = objects[‘Cube’]
• # to see this variable, create obj property
ob[‘newvel’] = 3.4
print dir(ob) # ‘newvel’ appears in the list
• To see object in debug mode (blender 2.49b)
• changed in blender 2.59b
• Game menu -> Debug Properties
• Add Property (in property panel)

Python Scripting in Blender

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Python Scripting in Blender

Uploaded by

Copyright:

Available Formats

Python Scripting in

print("x = 6") # line is never executed

a = 3/; # Error (stops program from running)

•First, the program is checked for syntactical errors

•Second, the program is executed

• One can construct one or more scenes

# errors will be printed out to the window

#['__doc__', '__name__', 'constraints', 'events', 'logic', 'render', 'texture', 'types']

['__doc__', '__name__', 'constraints', 'events', 'logic', 'render', 'texture', 'types']

['ACCENTGRAVEKEY', 'AKEY', 'BACKSLASHKEY', 'BACKSPACEKEY', 'BKEY',

... many more items ...

EWMATRIX_TRANSPOSE', '__doc__', '__name__', '__package__', 'addScene', 'endGame',

Make a cube move with the Akey

Notice the “:” in the “if statement”

• Use the MouseLookup.py module

Code in file: mouselook.py

How are they used from within Python?

Let us do something not possible without Python ...

Key ups are ignored

Once the motion actuator is

Better: cube = cont.owner

The motion actuator is never deactivated

Get property ‘acc’

The property value is always the

• I would like to keep track of the total

save and load globalDict

You might also like

#['doc', 'name', 'constraints', 'events', 'logic', 'render', 'texture', 'types']

['doc', 'name', 'constraints', 'events', 'logic', 'render', 'texture', 'types']

EWMATRIX_TRANSPOSE', 'doc', 'name', 'package', 'addScene', 'endGame',