module-sprite — Pygame

pygame.sprite

модуль pygame с базовыми классами объектов игры

Этот модуль содержит несколько простых классов, которые используются в играх. Есть основной класс Sprite и несколько классов Group, которые содержат Sprite. Использование этих классов полностью необязательно при использовании pygame. Классы довольно легкие и предоставляют лишь отправную точку для кода, который является общим для большинства игр.

Класс Sprite предназначен для использования в качестве базового класса для разных типов объектов в игре. Также есть базовый класс Group, который просто хранит спрайты. Игра может создавать новые типы классов Group, которые работают со специально настроенными экземплярами Sprite, которые они содержат.

Базовый класс Group может отрисовывать содержащиеся в нем Sprite на Surface. Метод Group.draw() требует, чтобы каждый Sprite имел атрибут Surface.image и Surface.rect. Метод Group.clear() требует те же атрибуты и может использоваться для удаления всех Sprite с фоном. Также существуют более продвинутые группы: pygame.sprite.RenderUpdates() и pygame.sprite.OrderedUpdates().

Наконец, этот модуль содержит несколько функций столкновений. Они помогают найти спрайты в нескольких группах, у которых пересекаются прямоугольники ограничивающей области. Для поиска столкновений Sprite должны иметь назначенный атрибут Surface.rect.

Группы спроектированы для высокой эффективности при удалении и добавлении Sprite. Они также позволяют быстро проверить, существует ли Sprite в группе. Один Sprite может присутствовать в любом количестве групп. В игре одни группы могут использоваться для управления отрисовкой объектов, а совершенно отдельный набор групп – для управления взаимодействием или перемещением игрока. Вместо добавления атрибутов типа или булевых значений в производный класс Sprite, рассмотрите возможность хранения Sprite в организованных группах. Это позволит проще осуществлять поиск позже в игре.

Sprite и Group управляют своими отношениями с методами add() и remove(). Эти методы могут принимать один или несколько объектов-целей для членства. Также и стандартные инициализаторы этих классов принимают один или список целей для первоначального членства. Безопасно многократно добавлять и удалять один и тот же Sprite из группы.

Хотя возможно разработать классы спрайтов и групп, которые не наследуются от классов Sprite и AbstractGroup ниже, настоятельно рекомендуется расширять их, когда вы добавляете класс Sprite или Group.

Sprite не потокобезопасны. Поэтому защитите их сами при использовании потоков.

pygame.sprite.Sprite

Простой базовый класс для видимых объектов игры.

Sprite(*groups) -> Sprite

Базовый класс для видимых объектов игры. Производные классы должны переопределить Sprite.update() и назначить атрибуты Sprite.image и Sprite.rect. Инициализатор может принимать любое количество экземпляров Group для добавления.

При наследовании от Sprite убедитесь, что вы вызываете базовый инициализатор перед добавлением Sprite в группы. Например:

class Block(pygame.sprite.Sprite):

    # Constructor. Pass in the color of the block,
    # and its x and y position
    def __init__(self, color, width, height):
       # Call the parent class (Sprite) constructor
       pygame.sprite.Sprite.__init__(self)

       # Create an image of the block, and fill it with a color.
       # This could also be an image loaded from the disk.
       self.image = pygame.Surface([width, height])
       self.image.fill(color)

       # Fetch the rectangle object that has the dimensions of the image
       # Update the position of this object by setting the values of rect.x and rect.y
       self.rect = self.image.get_rect()

update()

метод для управления поведением спрайта

update(*args, **kwargs) -> None

По умолчанию этот метод ничего не делает; это просто удобный «крючок», который можно переопределить. Этот метод вызывается Group.update() с любыми аргументами, которые вы передадите.

Этот метод не требуется, если не используется удобный метод с тем же именем в классе Group.

add(): добавить спрайт в группы

add(*groups) -> None

В качестве аргументов можно передать любое количество экземпляров Group. Sprite будет добавлен в те группы, членами которых он ещё не является.

remove(): удалить спрайт из групп

remove(*groups) -> None

В качестве аргументов можно передать любое количество экземпляров Group. Sprite будет удалён из тех групп, членами которых он является.

kill(): удалить Sprite из всех групп

kill() -> None

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

alive(): принадлежит ли спрайт какой-либо группе

alive() -> bool

Возвращает True, если Sprite принадлежит одной или нескольким группам.

groups(): список групп, которые содержат этот Sprite

groups() -> group_list

Возвращает список всех групп, которые содержат этот Sprite.

pygame.sprite.DirtySprite

Подкласс Sprite с дополнительными атрибутами и функциями.

DirtySprite(*groups) -> DirtySprite

Дополнительные атрибуты DirtySprite со значениями по умолчанию:

dirty = 1

if set to 1, it is repainted and then set to 0 again
if set to 2 then it is always dirty ( repainted each frame,
flag is not reset)
0 means that it is not dirty and therefore not repainted again

blendmode = 0

its the special_flags argument of blit, blendmodes

source_rect = None

source rect to use, remember that it is relative to
topleft (0,0) of self.image

visible = 1

normally 1, if set to 0 it will not be repainted
(you must set it dirty too to be erased from screen)

layer = 0

(READONLY value, it is read when adding it to the
LayeredDirty, for details see doc of LayeredDirty)

pygame.sprite.Group

Класс-контейнер для хранения и управления несколькими объектами Sprite.

Group(*sprites) -> Group

Простой контейнер для объектов Sprite. Этот класс можно наследовать для создания контейнеров со специфическим поведением. Конструктор принимает любое количество аргументов Sprite для добавления в группу. Группа поддерживает стандартные операции Python:

in      test if a Sprite is contained
len     the number of Sprites contained
bool    test if any Sprites are contained
iter    iterate through all the Sprites

Элементы Sprite в группе упорядочены только в Python 3.6 и выше. В Python ниже версии 3.6 отрисовка и итерация по Sprite происходит в произвольном порядке.

sprites(): Список Sprite, содержащихся в этой группе.

sprites() -> sprite_list

Возвращает список всех Sprite, содержащихся в этой группе. Вы также можете получить итератор из группы, но вы не можете итерироваться по группе во время её модификации.

copy(): Создать дубликат группы.

copy() -> Group

Создаёт новую группу со всеми теми же Sprite, что и исходная. Если вы унаследовали от класса Group, новый объект будет иметь тот же (под-)класс, что и исходный. Это работает только если конструктор производного класса принимает те же аргументы, что и класс Group.

add()

Добавить Sprite в эту группу.

add(*sprites) -> None

Добавляет любое количество Sprite в эту группу. Это добавит только Sprite, которые ещё не являются членами группы.

Каждый аргумент sprite также может быть итератором, содержащим Sprite.

remove()

Удалить Sprite из группы.

remove(*sprites) -> None

Удаляет любое количество Sprite из группы. Это удалит только Sprite, которые уже являются членами группы.

Каждый аргумент sprite также может быть итератором, содержащим Sprite.

has()

Проверка наличия Sprite в группе.

has(*sprites) -> bool

Возвращает True, если группа содержит все заданные sprites. Это аналогично использованию оператора "in" для группы ("if sprite in group: ..."), который проверяет, принадлежит ли отдельный Sprite группе.

Каждый аргумент sprite также может быть итератором, содержащим Sprite.

update()

Вызывает метод update для содержащихся Sprite.

update(*args, **kwargs) -> None

Вызывает метод update() для всех Sprite в группе. Базовый класс Sprite имеет метод update, который принимает любое количество аргументов и ничего не делает. Аргументы, переданные Group.update(), будут переданы каждому Sprite.

Нет способа получить возвращаемое значение от методов Sprite.update().

draw()

Отрисовка изображений Sprite.

draw(Surface, bgsurf=None, special_flags=0) -> List[Rect]

Отрисовывает содержащиеся Sprite на Surface. Используется атрибут Sprite.image для исходной поверхности и Sprite.rect для позиции. special_flags передаётся в Surface.blit(). bgsurf не используется в этом методе, но LayeredDirty.draw() его использует.

Группа не сохраняет Sprite в каком-либо порядке, поэтому порядок отрисовки произвольный.

clear()

Очистить фон над Sprite.

clear(Surface_dest, background) -> None

Очищает Sprite, использованные в последнем вызове Group.draw(). Поверхность назначения очищается путём заполнения позиций отрисованных Sprite фоном.

Фон обычно представляет собой изображение Surface тех же размеров, что и целевая Surface. Однако он также может быть функцией обратного вызова, которая принимает два аргумента: целевую Surface и область для очистки. Функция обратного вызова фона будет вызываться несколько раз при каждой очистке.

Вот пример функции обратного вызова, который очистит Sprite тёмно-красным цветом:

def clear_callback(surf, rect):
    color = 255, 0, 0
    surf.fill(color, rect)

empty(): Удалить все Sprite.

empty() -> None

Удаляет все Sprite из этой группы.

pygame.sprite.RenderPlain: То же, что и pygame.sprite.Group

Этот класс является псевдонимом для pygame.sprite.Group(). Он не имеет дополнительных функций.

pygame.sprite.RenderClear: То же, что и pygame.sprite.Group

Этот класс является псевдонимом для pygame.sprite.Group(). Он не имеет дополнительных функций.

pygame.sprite.RenderUpdates

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

RenderUpdates(*sprites) -> RenderUpdates

Этот класс унаследован от pygame.sprite.Group(). Он имеет расширенный метод draw(), который отслеживает изменённые области экрана.

draw()

Отрисовка изображений Sprite и отслеживание изменённых областей.

draw(surface, bgsurf=None, special_flags=0) -> Rect_list

Отрисовывает все Sprite на поверхность, аналогично Group.draw(). Этот метод также возвращает список прямоугольных областей на экране, которые были изменены. Возвращённые изменения включают области экрана, затронутые предыдущими вызовами Group.clear(). special_flags передаётся в Surface.blit().

Возвращённый список Rect должен быть передан в pygame.display.update(). Это поможет производительности в режимах отображения, управляемых программным обеспечением. Этот тип обновления обычно полезен только на назначениях с неанимированным фоном.

pygame.sprite.OrderedUpdates(): Подкласс RenderUpdates, отрисовывающий Sprite в порядке добавления.

OrderedUpdates(*sprites) -> OrderedUpdates

Этот класс унаследован от pygame.sprite.RenderUpdates(). Он сохраняет порядок, в котором Sprite были добавлены в группу для отрисовки. Это делает добавление и удаление Sprite из группы немного медленнее, чем в обычных группах.

END_OF_DOCUMENT_MARKER

pygame.sprite.LayeredUpdates

LayeredUpdates — группа спрайтов, обрабатывающая слои и рисующая, как OrderedUpdates.

LayeredUpdates(*sprites, **kwargs) -> LayeredUpdates

Эта группа полностью совместима с pygame.sprite.Sprite.

Вы можете установить значение по умолчанию для слоя через kwargs, используя 'default_layer' и целое число для слоя. Значение по умолчанию для слоя равно 0.

Если добавляемый спрайт имеет атрибут _layer, то используется этот слой. Если **kwarg содержит 'layer', то добавленные спрайты будут размещены в этом слое (переопределяя атрибут sprite.layer). Если ни у спрайта, ни в **kwarg нет атрибута layer, то используются слой по умолчанию для добавления спрайтов.

Новое в pygame 1.8.

add(): добавляет спрайт или последовательность спрайтов в группу

add(*sprites, **kwargs) -> None

Если у sprite(s) есть атрибут layer, то используется этот слой. Если **kwargs содержит 'layer', то sprite(s) будут добавлены в этот слой (переопределяя атрибут слоя спрайта). Если ни то, ни другое не передано, то sprite(s) будут добавлены в слой по умолчанию.

sprites(): возвращает упорядоченный список спрайтов (сначала задний, потом передний).

sprites() -> sprites

draw(): рисует все спрайты в правильном порядке на переданную поверхность.

draw(surface, bgsurf=None, special_flags=0) -> Rect_list

get_sprites_at(): возвращает список со всеми спрайтами в этой позиции.

get_sprites_at(pos) -> colliding_sprites

Сначала спрайты снизу, потом сверху.

get_sprite(): возвращает спрайт с индексом idx из списка спрайтов группы.

get_sprite(idx) -> sprite

Выбрасывает IndexOutOfBounds, если idx не находится в пределах диапазона.

remove_sprites_of_layer(): удаляет все спрайты из слоя и возвращает их в виде списка.

remove_sprites_of_layer(layer_nr) -> sprites

layers(): возвращает список определённых слоёв (уникальные), отсортированные снизу вверх.

layers() -> layers

change_layer(): изменяет слой спрайта

change_layer(sprite, new_layer) -> None

Спрайт должен быть добавлен в рендерер. Проверка не выполняется.

get_layer_of_sprite(): возвращает слой, в котором находится спрайт.

get_layer_of_sprite(sprite) -> layer

Если спрайт не найден, возвращается слой по умолчанию.

get_top_layer(): возвращает верхний слой.

get_top_layer() -> layer

get_bottom_layer(): возвращает нижний слой.

get_bottom_layer() -> layer

move_to_front(): перемещает спрайт на передний слой

move_to_front(sprite) -> None

Перемещает спрайт вперёд, изменяя слой спрайта на самый верхний слой (добавляется в конце этого слоя).

move_to_back(): перемещает спрайт в нижний слой

move_to_back(sprite) -> None

Перемещает спрайт в нижний слой, помещая его позади всех остальных слоёв и добавляя один дополнительный слой.

get_top_sprite(): возвращает самый верхний спрайт

get_top_sprite() -> Sprite

get_sprites_from_layer(): возвращает все спрайты из слоя, отсортированные по порядку добавления

get_sprites_from_layer(layer) -> sprites

Возвращает все спрайты из слоя, отсортированные по порядку добавления. Используется линейный поиск, спрайты не удаляются со слоя.

switch_layer(): переключает спрайты со слоя1 на слой2

switch_layer(layer1_nr, layer2_nr) -> None

Номера слоёв должны существовать, проверка не выполняется.

pygame.sprite.LayeredDirty

Группа LayeredDirty предназначена для объектов DirtySprite. Подклассы LayeredUpdates.

LayeredDirty(*sprites, **kwargs) -> LayeredDirty

Эта группа требует pygame.sprite.DirtySprite или любого спрайта, у которого есть следующие атрибуты:

image, rect, dirty, visible, blendmode (see doc of DirtySprite).

Она использует технику флага dirty и, следовательно, быстрее, чем pygame.sprite.RenderUpdates, если у вас много статических спрайтов. Она также автоматически переключается между обновлением прямоугольника dirty и полным отображением экрана, поэтому вам не нужно беспокоиться о том, что будет быстрее.

Аналогично pygame.sprite.Group. Вы можете указать дополнительные атрибуты через kwargs:

_use_update: True/False   default is False
_default_layer: default layer where sprites without a layer are added.
_time_threshold: threshold time for switching between dirty rect mode
    and fullscreen mode, defaults to 1000./80  == 1000./fps

Новое в pygame 1.8.

draw(): отображает все спрайты в правильном порядке на переданной поверхности.

draw(surface, bgsurf=None, special_flags=None) -> Rect_list

Вы можете передать и фон. Если фон уже установлен, то аргумент bgsurf не оказывает никакого влияния. Если он присутствует, то аргумент special_flags всегда передаётся в Surface.blit(), переопределяя DirtySprite.blendmode. Если special_flags отсутствует, DirtySprite.blendmode передаётся в Surface.blit() вместо него.

clear(): используется для установки фона

clear(surface, bgd) -> None

repaint_rect(): перерисовывает заданную область

repaint_rect(screen_rect) -> None

screen_rect находится в координатах экрана.

set_clip(): обрезает область, где необходимо рисовать. Просто передайте None (по умолчанию), чтобы сбросить обрезку

set_clip(screen_rect=None) -> None

get_clip(): обрезает область, где необходимо рисовать. Просто передайте None (по умолчанию), чтобы сбросить обрезку

get_clip() -> Rect

change_layer(): изменяет слой спрайта

change_layer(sprite, new_layer) -> None

спрайт должен быть добавлен в рендерер. Проверка не производится.

set_timing_treshold(): устанавливает порог в миллисекундах

set_timing_treshold(time_ms) -> None

УСТАРЕЛО: Используйте set_timing_threshold() вместо этого.

Устарело начиная с pygame 2.1.1.

set_timing_threshold()

устанавливает порог в миллисекундах

set_timing_threshold(time_ms) -> None

По умолчанию 1000.0 / 80.0. Это означает, что экран будет отрисован с помощью метода flip, а не update, если метод update занимает слишком много времени для обновления экрана, так что частота кадров падает ниже 80 кадров в секунду.

Новое в pygame 2.1.1.

Исключения: TypeError -- если time_ms не является int или float

pygame.sprite.GroupSingle()

Контейнер группы, который содержит один спрайт.

GroupSingle(sprite=None) -> GroupSingle

Контейнер GroupSingle содержит только один спрайт. Когда добавляется новый спрайт, старый удаляется.

Есть специальное свойство, GroupSingle.sprite, которое обращается к спрайту, содержащемуся в этой группе. Оно может быть None, когда группа пуста. Свойство также можно присвоить, чтобы добавить спрайт в контейнер GroupSingle.

pygame.sprite.spritecollide()

Находит спрайты в группе, которые пересекают другой спрайт.

spritecollide(sprite, group, dokill, collided = None) -> Sprite_list

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

Аргумент dokill — это bool. Если он установлен в True, все спрайты, которые столкнулись, будут удалены из группы.

Аргумент collided — это функция обратного вызова, используемая для расчета столкновения двух спрайтов. Она должна принимать два спрайта в качестве значений и возвращать булево значение, указывающее, столкнулись ли они. Если collided не передан, все спрайты должны иметь значение "rect", которое является прямоугольником области спрайта, которое будет использоваться для расчета столкновения.

Функции обратного вызова collided:

collide_rect, collide_rect_ratio, collide_circle,
collide_circle_ratio, collide_mask

Пример:

# See if the Sprite block has collided with anything in the Group block_list
# The True flag will remove the sprite in block_list
blocks_hit_list = pygame.sprite.spritecollide(player, block_list, True)

# Check the list of colliding sprites, and add one to the score for each one
for block in blocks_hit_list:
    score +=1

pygame.sprite.collide_rect(): Обнаружение столкновений между двумя спрайтами, используя прямоугольники.

collide_rect(left, right) -> bool

Проверяет столкновение между двумя спрайтами. Использует функцию pygame rect colliderect для расчета столкновения. Предназначен для передачи в качестве функции обратного вызова collided для функций *collide. Спрайты должны иметь атрибут "rect".

Новое в pygame 1.8.

pygame.sprite.collide_rect_ratio()

Обнаружение столкновений между двумя спрайтами, используя прямоугольники, масштабированные до отношения.

collide_rect_ratio(ratio) -> collided_callable

Класс вызываемой функции, проверяющей столкновения между двумя спрайтами, используя масштабированную версию прямоугольников спрайтов.

Создаётся с отношением, экземпляр затем предназначен для передачи в качестве функции обратного вызова collided к функциям *collide.

Отношение — число с плавающей точкой. 1.0 — такой же размер, 2.0 — вдвое больше, а 0.5 — вдвое меньше.

Новое в pygame 1.8.1.

pygame.sprite.collide_circle(): Обнаружение столкновений между двумя спрайтами, используя окружности.

collide_circle(left, right) -> bool

Проверяет столкновение между двумя спрайтами, проверяя, перекрываются ли две окружности, центрированные на спрайтах. Если спрайты имеют атрибут "radius", он используется для создания окружности, иначе окружность создаётся достаточно большой, чтобы полностью охватить прямоугольник спрайта, заданный атрибутом "rect". Предназначен для передачи в качестве функции обратного вызова collided к функциям *collide. Спрайты должны иметь атрибут "rect" и необязательный атрибут "radius".

Новое в pygame 1.8.1.

pygame.sprite.collide_circle_ratio()

Обнаружение столкновений между двумя спрайтами, используя окружности, масштабированные до отношения.

collide_circle_ratio(ratio) -> collided_callable

Класс вызываемой функции, проверяющей столкновения между двумя спрайтами, используя масштабированную версию радиуса спрайтов.

Создаётся с отношением с плавающей точкой, экземпляр затем предназначен для передачи в качестве функции обратного вызова collided к функциям *collide.

Отношение — число с плавающей точкой. 1.0 — такой же размер, 2.0 — вдвое больше, а 0.5 — вдвое меньше.

Создаваемая вызываемая функция проверяет столкновения между двумя спрайтами, проверяя, перекрываются ли две окружности, центрированные на спрайтах, после масштабирования радиуса окружностей на хранимое отношение. Если спрайты имеют атрибут "radius", он используется для создания окружности, иначе окружность создаётся достаточно большой, чтобы полностью охватить прямоугольник спрайта, заданный атрибутом "rect". Предназначен для передачи в качестве функции обратного вызова collided к функциям *collide. Спрайты должны иметь атрибут "rect" и необязательный атрибут "radius".

Новое в pygame 1.8.1.

END_OF_DOCUMENT_MARKER

pygame.sprite.collide_mask()

Обнаружение столкновения между двумя спрайтами, используя маски.
collide_mask(sprite1, sprite2) -> (int, int)
collide_mask(sprite1, sprite2) -> None

Проверяет столкновение между двумя спрайтами, проверяя, перекрываются ли их битовые маски (использует pygame.mask.Mask.overlap()). Если у спрайтов есть атрибут mask, он используется в качестве маски, в противном случае маска создается из image спрайта (используется pygame.mask.from_surface()). У спрайтов должен быть атрибут rect; атрибут mask является необязательным.

Возвращается первая точка столкновения между масками. Точка столкновения смещена от левого верхнего угла маски sprite1 (который всегда (0, 0)). Точка столкновения представляет позицию внутри маски и не связана с фактическим экранным положением sprite1.

Эта функция предназначена для использования в качестве функции обратного вызова collided для функций столкновения групп (см. spritecollide(), groupcollide(), spritecollideany()).

Примечание

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

Примечание

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

# Example of mask creation for a sprite.
sprite.mask = pygame.mask.from_surface(sprite.image)

Возвращает: первую точку столкновения между масками или None в случае отсутствия столкновения
Тип возвращаемого значения: tuple(int, int) или NoneType

Добавлена в pygame 1.8.0.

pygame.sprite.groupcollide()

Найти все спрайты, которые сталкиваются между двумя группами.

groupcollide(group1, group2, dokill1, dokill2, collided = None) -> Sprite_dict

Это позволит найти столкновения между всеми спрайтами в двух группах. Столкновение определяется путем сравнения атрибута Sprite.rect каждого спрайта или с использованием функции collided, если она не равна None.

Каждый спрайт внутри group1 добавляется в возвращаемый словарь. Значением для каждого элемента является список спрайтов в group2, которые пересекаются.

Если любой из аргументов dokill равен True, то сталкивающиеся спрайты будут удалены из их соответствующих групп.

Аргумент collided — это функция обратного вызова, используемая для вычисления столкновения между двумя спрайтами. Она должна принимать два спрайта в качестве значений и возвращать булевое значение, указывающее, сталкиваются ли они. Если collided не передается, все спрайты должны иметь значение «rect», которое представляет прямоугольник области спрайта, используемое для вычисления столкновения.

pygame.sprite.spritecollideany()

Простая проверка, пересекает ли спрайт что-либо в группе.

spritecollideany(sprite, group, collided = None) -> Sprite Столкновение с возвращаемым спрайтом.

spritecollideany(sprite, group, collided = None) -> None Столкновения нет.

Если спрайт сталкивается с любым одним спрайтом в группе, возвращается один спрайт из группы. В случае отсутствия столкновения возвращается None.

Если вам не нужны все возможности функции pygame.sprite.spritecollide(), эта функция будет немного быстрее.

Редактировать на GitHub