Este documento apresenta uma introdução à API Python da Blender Game Engine, explicando os principais módulos bge.logic, bge.render, bge.events, bge.texture e bge.constraints através de pequenos exemplos de código. O leitor aprende como importar a API bge, rodar scripts no modo game engine do Blender, acessar sensores e atuadores, capturar eventos de teclado, criar texturas dinâmicas de vídeo e manipular constraints físicas.

1. Introdução à API da BGE
Tutorial de Introdução à API da Blender Game Engine
Olá! Esse é um pequeno tutorial de introdução à API python da Blender Game Engine 2.5x que
eu decidi escrever para os iniciantes após ver muitas dúvidas a respeito disso. Vamos começar com:
import bge
print("Hello World")
Isso importa o módulo bge, onde fica toda a API da BGE. Para executar esse script, mude seu
“modo” do blender para Blender Game, e sua screen (tela) para Game Logic. No menu direito
(editor de texto), escreva esse script e nomeie-o de meuscript.py. No menu inferior crie um sensor
Always e conecte-o a um controlador python com o nome meuscript.py. Se fez tudo certo, quando
posicionar o ponteiro do mouse sobre a 3d view e teclar P, o script será rodado. Verifique no console
do blender (para os linuxers, é necessário abrir o blender num terminal ou configurar seu lançador
para fazê-lo) se há algum erro entre “Blender Game Engine Started” e “Blender Game Engine
Finished”. Se na verdade houver um Hello World, então parabéns, seu primeiro script funciona ;-)
bge.logic
O bge.logic é um sub-módulo do bge, equivalente ao antigo GameLogic. Lembre-se que
isto é apenas uma introdução, se quiser uma documentação completa, visite
http://www.blender.org/documentation/250PythonDoc/ e clique em bge.logic. Como o próprio
nome diz, ele nos permite realizar operações lógicas no jogo, considero como fundamental num
script para BGE. Vejamos o próximo exemplo.
#-*- coding: utf-8 -*-
import bge
from bge import logic
#O controlador em que o nosso script está inserido
cont = logic.getCurrentController()
#Cada controlador tem uma lista de sensores
#e atuadores conectados a ele mesmo. Podemos
#usá-las para controlar o que acontece no jogo
sen = cont.sensors['meusensor']
act = cont.actuators['meuatuador']
#Cada sensor tem um atributo booleano positive que
#é verdadeiro sempre que ele detecta alguma coisa
if sen.positive:
act.dLoc = [0.1,0,0] #vetor X,Y,Z do motion actuator
cont.activate(act) #ativa o nosso atuador
Agora, testemos esse script. Modifique seu sensor para um do tipo Keyboard e configure para
disparar com a barra de espaço, então nomeie-o de meusensor. Adicione um atuador Motion,
nomeie-o de meuatuador e conecte-o ao sensor python.
Solano Felício 1

2. Introdução à API da BGE
Agora, quando você iniciar o jogo e teclar espaço, o sensor keyboard será “disparado”, ou seja,
seu atributo positive será True, e as duas últimas linhas no nosso script serão executadas, ativando o
atuador ;-)
Se quiser uma documentação de todos os sensores, controladores, atuadores etc. da BGE, vá em
http://www.blender.org/documentation/250PythonDoc e clique em bge.types.
O módulo bge.logic, obviamente, permite-nos fazer muito mais que isso. Esse foi apenas um
pequeno exemplo de uso ;-)
bge.render
Esse módulo é equivalente ao antigo Rasterizer. Não há muito o que explicar; ele é
responsável pela renderização em tempo real. Vejamos um pequeno exemplo de uso:
#-*- coding: utf-8 -*-
import bge
from bge import render
from bge import logic
co = logic.getCurrentController()
sen = co.sensors['meusensor']
if sen.positive:
render.makeScreenshot("//screen_#.png")
Adicionando um sensor keyboard com True level triggering e nomeando-o de meusensor fará
com que sempre que você tecle determinada tecla, seja criada uma imagem da tela atual do jogo na
pasta atual (do .blend) no formato screen_numerodoframe.png. Para uma documentação
completa do bge.render, como já disse, visite a documentação online no site blender.org.
bge.events
Esse módulo é equivalente ao antigo GameKeys. Sua função, como o nome já diz, é capturar
eventos (de teclado ou mouse). Na verdade, ele só contem constantes com os eventos, o que se usa
para capturá-los são sensores. Vejamos um exemplo:
#-*- coding: utf-8 -*-
import bge
from bge import logic, events
co = logic.getCurrentActuator()
sen = co.sensors['meusensor']
for key,status in sensor.events:
for key, status in sen.events:
#tecla pressionada
if status == bge.logic.KX_INPUT_JUST_ACTIVATED:
if key == events.WKEY: #tecla W
Solano Felício 2

3. Introdução à API da BGE
# Fazer alguma coisa se for pressionada
if key == bge.events.SKEY: #tecla S
# Fazer alguma coisa se for pressionada
if key == bge.events.AKEY: #tecla A
# Fazer alguma coisa se for pressionada
if key == bge.events.DKEY: #tecla D
# Fazer alguma coisa se for pressionada
Se você tiver conectado ao seu controlador python um sensor keyboard chamado meusensor
com “All Keys” pressionado, esse script pode tratar de forma diferente cada tecla, assim não é
necessária a criação de um sensor para cada, aumentando o desempenho e a organização do jogo ;-)
Assim como os outros módulos, o bge.events tem uma documentação online, visite-a.
bge.texture
Equivalente ao antigo VideoTexture, esse módulo permite-nos usar texturas em vídeo,
através do uso do poderoso FFMpeg. O princípio é simples: você acha uma textura num objeto
existente com a função materialID e então cria uma nova textura de conteúdo dinâmico que
substituirá a anterior, alocando-a na GPU. Veja um exemplo de uso para rodar um vídeo num
objeto:
#-*- coding: utf-8 -*-
import bge
from bge import logic, texture
cont = logic.getCurrentController()
#vamos usar o objeto que possui o controlador atual
obj = cont.owner
#O script é rodado a cada frame, mas só podemos
#criar a textura uma vez, então criaremos um
#atributo video no bge.logic
if not hasattr(logic, 'video'):
#identifica a textura estática que será substituída
matID = texture.materialID(obj, 'nomedatextura')
#cria a textura dinâmica que substituirá a anterior
logic.video = texture.Texture(obj, matID)
#define a fonte da textura, aqui um vídeo
vid = logic.expandPath('//nomedovideo.ogg')
logic.video.source = texture.VideoFFMpeg(vid)
logic.video.source.scale = True
#roda o vídeo
logic.video.source.play()
logic.video.refresh() #atualiza a textura a cada frame
Solano Felício 3

4. Introdução à API da BGE
Para rodar o exemplo acima, é necessário que o controlador python esteja conectado a um sensor
Always e o objeto que o contém tenha uma textura chamada nomedatextura. Também é
necessário, na pasta do .blend atual, um arquivo de vídeo chamado nomedovideo.ogg. Se tudo
correr bem, você verá o vídeo sendo rodado no objeto atual quando rodar o jogo :-)
O bge.texture também tem documentação online, criada na maior parte por mim :-D
bge.constraints
Chegamos ao nosso último módulo. Ele é equivalente ao antigo PhysicsConstraints, e
permite-nos manipular constraints via python em tempo real. Não tenho muito o que explicar aqui;
Veja o exemplo.
#-*- coding: utf-8 -*-
import bge
from bge import logic
from bge import constraints
#lista de objetos na cena
objetos = logic.getCurrentScene().objects
obj1 = objetos['objeto1']
obj2 = objetos['objeto2']
pid1 = obj1.getPhysicsId() #id físico
pid2 = obj2.getPhysicsId() #id físico
#posições e ângulos dos pontos
posx = 1.0
posy = 0.0
posz = -1.0
angx = 0.0
angy = 1.0
angz = 0.0
#cria o constraint
constraints.createConstraint(pid1, pid2,
constraints.LINEHINGE_CONSTRAINT,
posx, posy, posz
angx, angy, angz)
Esse módulo também tem documentação online (e orgulhosamente escrita inteiramente por
mim :-D), visite-a para mais detalhes.
Obrigado por ler este tutorial, e bons estudos!
Solano Felício 4