Данный урок расскажет вам о подключении к игре в Blender скриптов, написанных на языке программирования Python, и об основных модулях игрового движка, доступных скрипту. Вы должны знать основы Blender и BGE.

Язык программирования Python. Экспресс-курс.
(Если вы уже знаете Python, можете пропустить этот раздел. Если вы не знаете Python, но хотите его знать нормально, почитайте что-нибудь нормальное, например, Викиучебник. Часть фактов, изложенных в этом разделе, может быть искажена ради понятности для «чайников».)
UPD: поскольку с понятностью для чайников всё-таки проблемы, читайте какой-нибудь Dive into Python.


Ищем консоль в Blender. Чтобы читать то, что нам выводит функция print, и ошибки, нам надо найти консоль в игровом движке: окно в блендере — это просто интерпретатор, игровой движок выведет всё в стандартный вывод. Чтобы консоль появилась в операционной системе Windows, нужно выбрать в меню Window — Toggle System Console. Для UNIX-подобных систем (Linux, например) достаточно просто запустить блендер из консоли (надеюсь, вы знаете, как это делать).

Подключение скрипта к объекту осуществляется через контроллёр Python. Он имеет два режима.

Режим «Скрипт».


В этом режиме он просто запускает указанный текстовый файл. Ничего особенного. Переменные, которые скрипт создавал внутри себя, не сохраняются.

Режим «Модуль».


В этом режиме требуется указать имя модуля и через точку функцию из этого модуля. Перед вызовом функции Blender импортирует этот модуль и потом вызывает из него функцию. Модуль импортируется один раз и работает в течение всей игры, поэтому все переменные внутри него сохраняются. Также за счёт этого повышается производительность, потому что нет необходимости исполнять весь файл каждый раз: вызывается только нужная функция из модуля, которая загружена заранее при импорте. Модуль должен иметь расширение «.py» в имени файла.

Hello, World! В текстовом редакторе Blender создайте такой файл:


И добавьте какому-нибудь объекту такую логику:


При запуске игры вы должны обнаружить в консоли соответствующее приветствие.

Если вы поменяете сенсор Always на Keyboard, вы обнаружите, что текст выводится два раза. Это связано с тем, что сенсор «будит» контроллёр не только при нажатии клавиши, но и при её отпускании.

Ещё Hello, World! Теперь посмотрим, как работает модуль:



В консоли вы будете наблюдать что-то подобное:


Видно, что код самого модуля выполняется один раз, и при нажатии клавиш вызывается соответствующая функция (два раза: при нажатии и при отпускании).

Модуль bge.logic.Все модули, связанные с игровым движком Blender, хранятся в одном модуле bge. Создадим новый скрипт и напишем туда:

import bge

Здесь мы рассмотрим только два модуля: bge.logic и bge.render.

bge.logic. Контроллёр. Как правило, скрипт начинается с получения контроллёра — того самого контроллёра Python, из которого был запущен скрипт. Переменную с контроллёром обычно называют cont.

import bge

cont = bge.logic.getCurrentController()

Через контроллёр мы может получить доступ к подключенном к нему сенсорам и актуаторам и самому объекту. Переменную с текущим объектом обычно называют obj или me.

obj = cont.owner

Через объект мы тоже может получить доступ к сенсорам и актуаторам, но уже ко всем. Доступ к ним осуществляется через одноимённые словари, в качестве ключей которого используются имена сенсоров и актуаторов соответственно.

sens = cont.sensors["Keyboard"] # получаем сенсор с именем(!) Keyboard

Учтите, что сенсоры и актуаторы берутся именно по имени, то есть, например, если вы создали сенсор Always (и именем Always) и поменяли его тип на Keyboard, то имя так и останется Always и получать сенсор надо именно через него. Также при добавлении нескольких сенсоров одного типа может добавлять порядковый номер (Keyboard1, Keyboard2 и т.д.), он тоже часть имени, не забывайте его указывать в скрипте. Лучше переименовывайте сенсоры или актуаторы в соответствие с их назначением (Key_Up, Fire и т.д.), чтобы не путаться.

Каждый сенсор имеет переменную positive, которая имеет значение True в случае, когда сенсор сработал, и False в случае, когда не сработал. Сравнение на True и False делать в Python, как и в любом другом языке, не обязательно, достаточно написать так:

if sens.positive:
    print("Сенсор активен")
else:
    print("Сенсор не активен")

При таком раскладе:



Мы в консоли получим:


Теперь мы получим актуатор и повертим объект с помощью него (в моём случае дефолтный кубик). Перепишем часть скрипта с условием:

act = cont.actuators["Motion"]

if sens.positive:
    cont.activate(act) # это включает актуатор
else:
    cont.deactivate(act) # это выключит актуатор

TODO: заменить скриншот



Сделаем вращение кубика ускоряющимся: пока кнопка нажата, куб вращается всё быстрее, когда кнопка отпущена — кубик замедляется и останавливается совсем. Это можно сделать с помощью обычной угловой скорости (Angular Velocity), но мы сделаем через изменение параметра Rot в актуаторе.

Все три значения со строчек Loc и Rot хранятся в массивах dLoc и dRot соответственно. Их, собственно, менять и будем. Кстати, к значениям этих массивов можно получать доступ не только через индексы (0, 1, 2), но и через переменные x, y, z внутри них.

Но нужно учесть, что в скрипте вращение задаётся не в градусах, а в радианах.

Снова перепишем последнюю часть скрипта с условием:

if sens.positive:
    act.dRot = [act.dRot.x, act.dRot.y, act.dRot.z+0.001]
    cont.activate(act)
else:
    if abs(act.dRot.z) < 0.001:
        # останавливаем актуатор только когда скорости нет
        cont.deactivate(act)
        # из-за погрешностей в вычислении дробных чисел
        # «в лоб» через == лучше не сравнивать
    else:
        # скорость ещё есть - уменьшаем
        act.dRot = [act.dRot.x, act.dRot.y, act.dRot.z-0.001]

Функция abs откидывает минус у переданного ей числа.

Но теперь нам надо немного изменить сенсор. Дело в том, что, как было видно через print, скрипт запускается один раз при нажатии клавиши и один раз при отпускании, а нам надо менять скорость в течение всей игры. Для этого мы нажмём две кнопки с тремя «точечками» на сенсоре.

Первая кнопка включает вызов скрипта каждый раз, когда сенсор срабатывает. Вторая кнопка — каждый раз, когда сенсор не срабатывает. То есть скрипт у нас теперь будет работать вообще на каждом игровом кадре.

Кстати, через «Частоту» (Freq) справа от этих кнопочек можно задавать пропуск кадров. Если, например, там написать 1, то скрипт будет вызываться не каждый кадр, а с пропуском через кадр.
TODO: заменить скриншот

Теперь скрипт при нажатии на пробел будет ускоряться и замедляться в противном случае. Конечно, если вы не забыли обнулить все значения в актуаторе Motion. :)

Насчёт погрешности в вычислениях: попробуйте в питоне сложить 0.1 и 0.2, посмотрите на результат и всё поймёте.

Свойства. Объект можно рассматривать как обычный словарь, ключами которого являются имена свойств (Property). Отличие только в том, что для получения списка имеющихся свойств надо использовать не функцию keys(), а функцию getPropertyNames().

Соответственно, для получения свойства из объекта надо указать его имя в квадратных скобках (и кавычках, потому что имя — это строка) после имени переменной с нужным объектом, примерно так: obj["koef"]

Вот мы и вынесем наше число 0.001 в свойство. Создадим его.


Теперь достаточно везде в скрипте поменять 0.001 на obj["speed"]

if sens.positive:
    act.dRot = [act.dRot.x, act.dRot.y, act.dRot.z+obj["speed"]]
    cont.activate(act)
else:
    if abs(act.dRot.z) < obj["speed"]:
        cont.deactivate(act)
    else:
        act.dRot = [act.dRot.x, act.dRot.y, act.dRot.z-obj["speed"]]

Для удобства можно присвоить это свойство какой-нибудь новой переменной и использовать уже эту переменную. Но учтите, что изменение свойства в объекте уже не повлияет на значение переменной до тех пор, пока вы заново не присвоите переменной это свойство.



С помощью списка имеющихся свойств getPropertyNames() мы можем сделать проверку на наличие данного свойства, чтобы избежать ошибки при его отсутствии. Мы можем даже создать это свойство. Заменим строчку с получением свойства speed на следующий код:

if not "speed" in obj.getPropertyNames(): # проверка отсутствия
    obj["speed"] = 0.001 # создаём свойство
speed = obj["speed"] # получаем гарантированно присутствующее свойство

Теперь вы можете удалить свойство из объекта, и скрипт сохранит свою работоспособность.

Но вообще для получения значений у объектов, списка сенсоров (obj.sensors) и актуаторов (obj.atuators) имеется функция get(), первым аргументом для которой нужно указать имя нужного свойства/сенсора/актуатора, а вторым аргументом значение, которое нужно вернуть в случае отсутствия этого свойства (если его не указывать, при отсутствии функция вернёт None). И код сокращается до одной строчки:

speed = obj.get("speed", 0.001)

Скачать blend-файл 1



У сенсоров и актуаторов есть ещё куча своих атрибутов, которые можно читать и изменять, но их тут рассматривать бессмысленно, лучше вооружитесь переводчиком и штурмуйте официальную документацию (раздел Game Engine Modules). Атрибуты, которые имеются у сенсоров, контроллёров, актуаторов, объектов и сцен (о них ниже) расписаны в bge.types. Вот, например, используемый нами dRot.

А теперь мы рассмотри работу со сценами. Получить список всех запущенных сцен можно с помощью функции:

scenes = bge.logic.getSceneList()

Так как это самый обычный массив (нету даже прекрасной функции get), для поиска сцены по имени нам придётся в цикле перебирать все сцены и сравнивать имя.

scene = None
for x in scenes: # перебираем сцены
    if x.name = "Menu": # в name содержится имя сцены
        scene = x
        break # выходим из цикла

if scene: # проверяем, что сцена нашлась
    print("Сцена нашлась, работаю дальше")

Для получения текущей сцены (той, из которой запущен скрипт) достаточно воспользоваться другой функцией:

scene = bge.logic.getCurrentScene()
print("Меня запустили из сцены", scene.name)

Теперь у нас есть полный доступ к сцене. Частично рассмотрим, что у неё есть:

Подробности в официальной документации.

Рассмотрим, что мы можем делать с объектами, помимо работы со свойствами:

Из урока получается справочник, но что поделать ¯\(°_o)/¯

Функции в модуле bge.logic:

А ещё у нас есть модуль bge.render.

Подробности снова в официальной документации. Учите английский язык, пригодится!

В процессе написания скриптов у вас может возникнуть проблема, что вам нужен не вектор и не навороченный список, а просто самый обыкновенный массив Python, без которого скрипт пишет ошибку. Чтобы преобразовать такой объект в обычный массив, воспользуйтесь функцией list(), передав ей проблемный объект:

arr = list(obj.worldPosition)
# arr теперь не вектор
print(arr)

globalDict и сохранение/загрузка игры. Модуль bge.logic также имеет такой интересный нам словарь, именуемый globalDict. Особенность его в том, что всё его содержимое можно сохранить файл с помощью функций bge.logic.saveGlobalDict() и загрузить из файла с помощью bge.logic.loadGlobalDict() (только если вы запихнёте туда то, что сохранить в принципе нельзя, может выскочить ошибка), а также с помощью соответствующих функций в актуаторе Edit Object.

globalDict тоже имеет функцию get(ключ, значение по умолчанию).

Попробуем сделать сохранение положения движущегося кубика. Заодно научимся писать модуль для BGE.



Создадим файл Saver.py и напишем туда следующее:

import bge

print("Loading globalDict...")
bge.logic.loadGlobalDict()

def load(cont):
    if not cont.sensors["Load"].positive:
        # выходим, если кнопка не нажата
        return
    
    # в cont передаётся контроллёр, который вызвал функцию
    # поэтому getCurrentController() запускать не надо
    obj = cont.owner
    
    # получаем положение объекта
    pos = bge.logic.globalDict.get("cube_pos", [0.0, 0.0, 0.0])
    
    # и двигаем
    obj.worldPosition = pos
    
    print("Loaded!")
    
def save(cont):
    if not cont.sensors["Save"].positive:
        return
    
    obj = cont.owner
    pos = list(obj.worldPosition) # через list убираем вектор, нам не надо
    
    # сохраняем
    bge.logic.globalDict["cube_pos"] = pos
    bge.logic.saveGlobalDict()
    
    print("Saved!")

Тогда во время игры мы можем наблюдать следующее:



С помощью print мы видим, что сам модуль выполняется один раз, и только при нажатии клавиш вызываются прописанные в контроллёре функции. За счёт этого модули потенциально более производительны, чем просто скрипты.

Таким образом можно кидать в globalDict всё, что нужно сохранить.

Также globalDict можно использовать для обмена информацией между сценами: для всех сцен он один и тот же. Записываем в одной сцене — читаем в другой.

Скачать blend-файл 2

Предлагаю вам на разбор пример с изменением здоровья героя, в котором с помощью скриптов вычисляется уменьшение здоровья в зависимости от высоты падения (точнее, в зависимости от того, насколько резко меняется скорость: при падении она резко меняется в ноль, этим скрипт и пользуется).

Ошибки и их обработка. Если скрипт пытается что-то неправильно делать, питон обижается, печатает подробную информацию об ошибке в консоль и прерывает работу скрипта. Эту информацию следует научиться читать. Английский пригодится.

Python script error - object 'Cube', controller 'Python':
Traceback (most recent call last):
  File "Text", line 5, in <module>
NameError: name 'что_то' is not defined

Видим, что указаны файл, в котором возникла ошибка, строчка, в которой возникла ошибка, и собственно ошибка.

NameError: name 'что_то' is not defined
Вы пытаетесь обратиться к переменной или функции что_то, которой не существует. Возможно, вы забыли эту переменную создать. Возможно, вы забыли импортировать модуль. Возможно, вы просто опечатались.

SyntaxError: invalid syntax
SyntaxError: unexpected EOF while parsing
Вы где-то опечатались: забыли закрыть скобку, поставили лишний символ. Причём ошибка может быть и не на самой указанной строчке, а где-то на предыдущих. Тут придётся перечитывать скрипт.

IndentationError: unexpected indent
Вы накосячили с отступами и пробелами в скрипте. Проверьте отступы в указанной строчке. Учтите, что отступ вправо означает начало блока кода, отступ влево — конец этого блока. Рекомендуемый отступ — 4 пробела, не рекомендуемый — табуляция (символ такой).

ImportError: No module named 'модуль'
Вы пытаетесь импортировать несуществующий модуль. Проверьте его на опечатки и наличие его у вас в системе.

AttributeError: 'КакойТоТам' object has no attribute 'атрибут'
Вы пытаетесь получить у обекта несуществующий атрибут. Проверьте имя атрибута на опечатки (регистр в том числе) и перепроверьте в документации, существует ли такой атрибут вообще.

AttributeError: attribute 'parent' of 'KX_GameObject' objects is not writable
Вы пытаетесь изменить атрибут, изменять который нельзя. Смиритесь или найдите функцию, которая его меняет (например, для parent из примера есть функция setParent).

IndexError: CList[i]: Python ListIndex out of range in CValueList
IndexError: list index out of range
Вы пытаетесь получить доступ к элементу массива, которого нет. Например, вы указали индекс с числом, равным или больше количеству элементов в массиве (индексы считаются от нуля до количества минус один; последний элемент имеет индекс количество минус один). Добавьте в скрипт проверку размера массива len(arr).

KeyError: 'ключ'
Вы пытаетесь получить элемент из словаря по ключу, которого там нет. Проверьте его наличие с помощью выражения ключ in словарь.keys()


Ошибки можно ловить. Для этого используется конструкция try..except:

try:
    obj = bge.logic.getCurrentScene().objects["Cube"]
except:
    print("Ошибка при получении объекта")

Если возникнет какая-то ошибка (вообще их правильно называть исключениями) между try и catch, будет передано управления блоку после except.

Так будут ловиться вообще все ошибки. Чтобы поймать какую-то конкретную ошибку, нужно указать тип этой ошибки (кстати, типы в Python тоже являются объектами и ими можно манипулировать, как всеми объектами). Так можно указывать несколько блоков except:

try:
    obj = bge.logic.getCurrentScene().objects["Cube"]
except KeyError:
    print("Нет такого объекта")
except AttributeError:
    print("У сцены нет атрибута object? Как так? o_O")

Исключение является таким же объектом, как и все остальные объекты, и оно может содержать информацию об ошибке. Чтобы получить информацию из него, его нужно получить. Делается это следующим образом:

try:
    obj = bge.logic.getCurrentScene().objects["Cube"]
except Exception as exc: # в переменной exc у нас объект-исключение
    print("Ошибка при получении объекта:", str(exc))

Указание типа Exception (или вообще отсутствие указанного типа) позволяет ловить любые исключения. Но так делать не рекомендуется, потому что можно случайно поймать и обработать не то исключение, которое нам надо.

try:
    obj['result'] = 1 / 0
except ZeroDivisionError:
    print("Деление на ноль!")
except:
    print("Какая-то неизвестная ошибка")

Чтобы из пойманной ошибки вывести такую же подробную информацию, какую выводил сам питон, можно воспользоваться модулем traceback. Его функция print_exc() печатает информацию в консоль, функция format_exc() возвращает строку с информацией об ошибке.

Оператор raise в Python позволяет вызвать своё исключение. Его можно использовать, чтобы обработать исключение, «не перехватывая» его, то есть работа скрипта всё равно прекратится:

import traceback

try:
    obj = bge.logic.getCurrentScene().objects["Cube"]
except:
    obj["error"] = traceback.format_exc() # забираем сообщение об ошибке
    raise # и делаем исключение. Скрипт прервёт свою работу и напечатает ошибку в консоль

Можно создавать свои типы исключений. Этим удобно пользоваться в больших скриптах.

class MyScriptError(Exception): pass
# создаём своё исключение на базе Exception (можно на базе любого исключения)

if not bge.logic.getCurrentScene().objects.get("Cube"):
    raise MyScriptError("Нету кубика!")

Такая форма записи: тип(аргументы) — создаёт новый объект с указанным типом. Атрибуты передаются в специальную функцию — конструктор. В случае исключений атрибут может содержать текст ошибки. Тогда в консоли мы увидим свой текст:

Python script error - object 'Cube1', controller 'Python':
Traceback (most recent call last):
  File "Text", line 5, in <module>
__main__.MyScriptError: Нету кубика!

Свои исключения тоже можно ловить.

class MyScriptError(Exception): pass
# создаём своё исключение на базе Exception (можно на базе любого исключения)

try:
    cube = bge.logic.getCurrentScene().objects.get("Cube")
    if not cube:
        raise MyScriptError("Нету кубика!")
    if not cube.get("prop"):
        raise MyScriptError("Нету свойства!")
    print("Проп:", cube["prop"])
except MyScriptError as mse:
    print("Ошибка:", str(mse))

Ну и хватит на этом, наверно.