Pygame использует объекты Rect для хранения и обработки прямоугольных областей. Rect можно создать на основе значений left, top, width и height. Rects также можно создать из объектов Python, которые уже являются Rect или имеют атрибут с именем "rect".

Любая функция pygame, которая требует аргумента Rect, также принимает любое из этих значений для построения Rect. Это упрощает создание Rect «на лету» в качестве аргументов функций.

Функции Rect, которые изменяют положение или размер Rect, возвращают новую копию Rect с внесёнными изменениями. Исходный Rect не изменяется. Некоторые методы имеют альтернативную «локальную» версию, которая возвращает None, но изменяет исходный Rect. Эти «локальные» методы обозначены суффиксом «ip».

Объект Rect имеет несколько виртуальных атрибутов, которые можно использовать для перемещения и выравнивания Rect:

x,y
top, left, bottom, right
topleft, bottomleft, topright, bottomright
midtop, midleft, midbottom, midright
center, centerx, centery
size, width, height
w,h

Все эти атрибуты можно присваивать:

rect1.right = 10
rect2.center = (20,30)

Присвоение значения size, width или height изменяет размеры прямоугольника; все остальные присваивания перемещают прямоугольник без изменения его размера. Обратите внимание, что некоторые атрибуты являются целыми числами, а другие — парами целых чисел.

Если у Rect ненулевая ширина или высота, он вернёт True для проверки на ненулевое значение. Некоторые методы возвращают Rect с размером 0 для представления недействительного прямоугольника. Rect с размером 0 не будет участвовать в столкновениях при использовании методов обнаружения столкновений (например, collidepoint(), colliderect() и т. д.).

Координаты объектов Rect — целые числа. Значения размера могут быть заданы отрицательными, но такие Rects считаются недопустимыми для большинства операций.

Существует несколько тестов на столкновение между другими прямоугольниками. Большинство контейнеров Python можно перебирать на предмет столкновений с одним Rect.

Область, покрытая Rect, не включает правую и нижнюю границы пикселей. Если нижняя граница одного Rect совпадает с верхней границей другого Rect (т. е., rect1.bottom=rect2.top), они точно соприкасаются на экране, но не перекрываются, и rect1.colliderect(rect2) возвращает false.

Объект Rect также можно итерировать:

r = Rect(0, 1, 2, 3)
x, y, w, h = r

copy()

копирует прямоугольник

copy() -> Rect

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

Введено в pygame 1.9

move()

перемещает прямоугольник

move(x, y) -> Rect

Возвращает новый прямоугольник, смещённый на заданный сдвиг. Аргументы x и y могут быть любыми целыми значениями, положительными или отрицательными.

move_ip()

перемещает прямоугольник, по месту

move_ip(x, y) -> None

Аналогично методу Rect.move(), но работает на месте.

inflate()

увеличивает или уменьшает размер прямоугольника

inflate(x, y) -> Rect

Возвращает новый прямоугольник, размер которого изменён на заданный сдвиг. Прямоугольник остаётся центрированным относительно своего текущего центра. Отрицательные значения уменьшат прямоугольник. Обратите внимание, что используются целые числа; если заданный сдвиг слишком мал (<2>-2), центр может сместиться.

inflate_ip()

увеличивает или уменьшает размер прямоугольника, по месту

inflate_ip(x, y) -> None

Аналогично методу Rect.inflate(), но работает на месте.

scale_by()

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

scale_by(scalar) -> Rect

scale_by(scalex, scaley) -> Rect

Возвращает новый прямоугольник, размеры которого масштабированы на заданные множители. Прямоугольник остаётся центрированным относительно своего текущего центра. Разрешается один скаляр или отдельные скаляры для ширины и высоты. Значения больше единицы увеличат размер прямоугольника, а значения между нулём и единицей уменьшат его.

scale_by_ip()

увеличивает или уменьшает размер прямоугольника, по месту

scale_by_ip(scalar) -> None

scale_by_ip(scalex, scaley) -> None

Аналогично методу Rect.scale_by(), но работает на месте.

update()

устанавливает положение и размеры прямоугольника

update(left, top, width, height) -> None

update((left, top), (width, height)) -> None

update(object) -> None

Устанавливает положение и размеры прямоугольника на месте. См. параметры для pygame.Rect() для параметров этой функции.

Введено в pygame 2.0.1.

clamp()

перемещает прямоугольник внутрь другого

clamp(Rect) -> Rect

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

clamp_ip()

перемещает прямоугольник внутрь другого, по месту

clamp_ip(Rect) -> None

Аналогично методу Rect.clamp(), но работает на месте.

clip()

обрезает прямоугольник внутри другого

clip(Rect) -> Rect

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

clipline()

обрезает линию внутри прямоугольника

clipline(x1, y1, x2, y2) -> ((cx1, cy1), (cx2, cy2))

clipline(x1, y1, x2, y2) -> ()

clipline((x1, y1), (x2, y2)) -> ((cx1, cy1), (cx2, cy2))

clipline((x1, y1), (x2, y2)) -> ()

clipline((x1, y1, x2, y2)) -> ((cx1, cy1), (cx2, cy2))

clipline((x1, y1, x2, y2)) -> ()

clipline(((x1, y1), (x2, y2))) -> ((cx1, cy1), (cx2, cy2))

clipline(((x1, y1), (x2, y2))) -> ()

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

Линия для обрезки может быть в любом из следующих форматов (можно использовать числа с плавающей точкой вместо целых, но они будут усечены):

• четыре целых числа

• 2 списка/кортежей/Vector2 из 2 целых чисел

• список/кортеж из четырёх целых чисел

• список/кортеж из 2 списков/кортежей/Vector2 из 2 целых чисел

Возвращает

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

Тип возвращаемого значения

tuple(tuple(int, int), tuple(int, int)) или ()

Исключения

TypeError — если координаты линии не заданы в одном из описанных выше форматов

Примечание

Этот метод можно использовать для определения столкновений между прямоугольником и линией. Смотрите пример кода ниже.

Примечание

Атрибуты rect.bottom и rect.right объекта pygame.Rect всегда лежат на один пиксель за пределами его фактической границы.

# Example using clipline().
clipped_line = rect.clipline(line)

if clipped_line:
    # If clipped_line is not an empty tuple then the line
    # collides/overlaps with the rect. The returned value contains
    # the endpoints of the clipped line.
    start, end = clipped_line
    x1, y1 = start
    x2, y2 = end
else:
    print("No clipping. The line is fully outside the rect.")

Введено в pygame 2.0.0.

union()

объединяет два прямоугольника в один

union(Rect) -> Rect

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

union_ip()

объединяет два прямоугольника в один, на месте

union_ip(Rect) -> None

То же, что и метод Rect.union(), но работает на месте.

unionall()

объединение нескольких прямоугольников

unionall(Rect_sequence) -> Rect

Возвращает объединение одного прямоугольника с последовательностью других прямоугольников.

unionall_ip()

объединение нескольких прямоугольников, на месте

unionall_ip(Rect_sequence) -> None

То же, что и метод Rect.unionall(), но работает на месте.

fit()

изменение размера и перемещение прямоугольника с сохранением соотношения сторон

fit(Rect) -> Rect

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

normalize()

исправление отрицательных размеров

normalize() -> None

Меняет местами ширину и высоту прямоугольника, если они отрицательны. Прямоугольник остаётся в том же месте, меняются только стороны.

contains()

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

contains(Rect) -> bool

Возвращает True, если аргумент полностью находится внутри прямоугольника.

collidepoint()

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

collidepoint(x, y) -> bool

collidepoint((x,y)) -> bool

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

Примечание

Для определения столкновения между прямоугольником и линией можно использовать метод clipline().

colliderect()

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

colliderect(Rect) -> bool

Возвращает True, если какие-либо части прямоугольников перекрываются (кроме верхнего/нижнего или левого/правого краёв).

Примечание

Для определения столкновения между прямоугольником и линией можно использовать метод clipline().

collidelist()

проверка пересечения одного прямоугольника с прямоугольником в списке

collidelist(list) -> index

Проверяет, сталкивается ли прямоугольник с каким-либо прямоугольником в последовательности прямоугольников. Возвращает индекс первого найденного столкновения. Если столкновений нет, возвращает -1.

collidelistall()

проверка пересечения всех прямоугольников в списке

collidelistall(list) -> indices

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

В качестве аргументов допустимы не только прямоугольники, но и:

 1Rect = pygame.Rect
 2r = Rect(0, 0, 10, 10)
 3
 4list_of_rects = [Rect(1, 1, 1, 1), Rect(2, 2, 2, 2)]
 5indices0 = r.collidelistall(list_of_rects)
 6
 7list_of_lists = [[1, 1, 1, 1], [2, 2, 2, 2]]
 8indices1 = r.collidelistall(list_of_lists)
 9
10list_of_tuples = [(1, 1, 1, 1), (2, 2, 2, 2)]
11indices2 = r.collidelistall(list_of_tuples)
12
13list_of_double_tuples = [((1, 1), (1, 1)), ((2, 2), (2, 2))]
14indices3 = r.collidelistall(list_of_double_tuples)
15
16class ObjectWithRectAttribute(object):
17    def __init__(self, r):
18        self.rect = r
19
20list_of_object_with_rect_attribute = [
21    ObjectWithRectAttribute(Rect(1, 1, 1, 1)),
22    ObjectWithRectAttribute(Rect(2, 2, 2, 2)),
23]
24indices4 = r.collidelistall(list_of_object_with_rect_attribute)
25
26class ObjectWithCallableRectAttribute(object):
27    def __init__(self, r):
28        self._rect = r
29
30    def rect(self):
31        return self._rect
32
33list_of_object_with_callable_rect = [
34    ObjectWithCallableRectAttribute(Rect(1, 1, 1, 1)),
35    ObjectWithCallableRectAttribute(Rect(2, 2, 2, 2)),
36]
37indices5 = r.collidelistall(list_of_object_with_callable_rect)

collideobjects()

проверка пересечения с объектом в списке

collideobjects(rect_list) -> object

collideobjects(obj_list, key=func) -> object

Экспериментальная функция: функция всё ещё находится в разработке, доступна для тестирования и отзывов. Она может измениться. Пожалуйста, оставьте отзывы по collideobjects авторам.

Проверяет, сталкивается ли прямоугольник с каким-либо объектом в последовательности. Возвращает объект первого обнаруженного столкновения. Если столкновений нет, то возвращается None

Если key задан, он должен быть методом, принимающим объект из списка в качестве входных данных и возвращающим прямоугольник, например lambda obj: obj.rectangle. Если у объекта есть несколько атрибутов типа Rect, key может вернуть один из них.

 1r = Rect(1, 1, 10, 10)
 2
 3rects = [
 4    Rect(1, 1, 10, 10),
 5    Rect(5, 5, 10, 10),
 6    Rect(15, 15, 1, 1),
 7    Rect(2, 2, 1, 1),
 8]
 9
10result = r.collideobjects(rects)  # -> <rect(1, 1, 10, 10)>
11print(result)
12
13class ObjectWithSomRectAttribute:
14    def __init__(self, name, collision_box, draw_rect):
15        self.name = name
16        self.draw_rect = draw_rect
17        self.collision_box = collision_box
18
19    def __repr__(self):
20        return f'<{self.__class__.__name__}("{self.name}", {list(self.collision_box)}, {list(self.draw_rect)})>'
21
22objects = [
23    ObjectWithSomRectAttribute("A", Rect(15, 15, 1, 1), Rect(150, 150, 50, 50)),
24    ObjectWithSomRectAttribute("B", Rect(1, 1, 10, 10), Rect(300, 300, 50, 50)),
25    ObjectWithSomRectAttribute("C", Rect(5, 5, 10, 10), Rect(200, 500, 50, 50)),
26]
27
28# collision = r.collideobjects(objects) # this does not work because the items in the list are no Rect like object
29collision = r.collideobjects(
30    objects, key=lambda o: o.collision_box
31)  # -> <ObjectWithSomRectAttribute("B", [1, 1, 10, 10], [300, 300, 50, 50])>
32print(collision)
33
34screen_rect = r.collideobjects(objects, key=lambda o: o.draw_rect)  # -> None
35print(screen_rect)

Новая в pygame 2.1.3.

collideobjectsall()

проверка пересечения со всеми объектами в списке

collideobjectsall(rect_list) -> objects

collideobjectsall(obj_list, key=func) -> objects

Экспериментальная функция: функция всё ещё находится в разработке, доступна для тестирования и отзывов. Она может измениться. Пожалуйста, оставьте отзывы по collideobjectsall авторам.

Возвращает список всех объектов, содержащих прямоугольники, пересекающиеся с прямоугольником. Если пересекающихся объектов нет, возвращается пустой список.

Если key задан, он должен быть методом, принимающим объект из списка в качестве входных данных и возвращающим прямоугольник, например lambda obj: obj.rectangle. Если у объекта есть несколько атрибутов типа Rect, key может вернуть один из них.

 1r = Rect(1, 1, 10, 10)
 2
 3rects = [
 4    Rect(1, 1, 10, 10),
 5    Rect(5, 5, 10, 10),
 6    Rect(15, 15, 1, 1),
 7    Rect(2, 2, 1, 1),
 8]
 9
10result = r.collideobjectsall(
11    rects
12)  # -> [<rect(1, 1, 10, 10)>, <rect(5, 5, 10, 10)>, <rect(2, 2, 1, 1)>]
13print(result)
14
15class ObjectWithSomRectAttribute:
16    def __init__(self, name, collision_box, draw_rect):
17        self.name = name
18        self.draw_rect = draw_rect
19        self.collision_box = collision_box
20
21    def __repr__(self):
22        return f'<{self.__class__.__name__}("{self.name}", {list(self.collision_box)}, {list(self.draw_rect)})>'
23
24objects = [
25    ObjectWithSomRectAttribute("A", Rect(1, 1, 10, 10), Rect(300, 300, 50, 50)),
26    ObjectWithSomRectAttribute("B", Rect(5, 5, 10, 10), Rect(200, 500, 50, 50)),
27    ObjectWithSomRectAttribute("C", Rect(15, 15, 1, 1), Rect(150, 150, 50, 50)),
28]
29
30# collisions = r.collideobjectsall(objects) # this does not work because ObjectWithSomRectAttribute is not a Rect like object
31collisions = r.collideobjectsall(
32    objects, key=lambda o: o.collision_box
33)  # -> [<ObjectWithSomRectAttribute("A", [1, 1, 10, 10], [300, 300, 50, 50])>, <ObjectWithSomRectAttribute("B", [5, 5, 10, 10], [200, 500, 50, 50])>]
34print(collisions)
35
36screen_rects = r.collideobjectsall(objects, key=lambda o: o.draw_rect)  # -> []
37print(screen_rects)

Новая в pygame 2.1.3.

collidedict()

проверка пересечения одного прямоугольника в словаре

collidedict(dict) -> (key, value)

collidedict(dict) -> None

collidedict(dict, use_values=0) -> (key, value)

collidedict(dict, use_values=0) -> None

Возвращает первую пару ключ-значение, которая пересекается с вызывающим объектом Rect. Если столкновений нет, возвращается None. Если use_values равно 0 (по умолчанию), используются ключи словаря для определения столкновений, в противном случае - значения.

Примечание

Объекты Rect не могут использоваться в качестве ключей в словаре (они не хешируемы), поэтому их нужно преобразовать в кортеж. Например, rect.collidedict({tuple(key_rect) : value})

collidedictall()

проверка пересечения всех прямоугольников в словаре

collidedictall(dict) -> [(key, value), ...]

collidedictall(dict, use_values=0) -> [(key, value), ...]

Возвращает список всех пар ключ-значение, которые пересекаются с вызывающим объектом Rect. Если столкновений нет, возвращается пустой список. Если use_values равно 0 (по умолчанию), используются ключи словаря для определения столкновений, в противном случае - значения.

Примечание

Объекты Rect не могут использоваться в качестве ключей в словаре (они не хешируемы), поэтому их нужно преобразовать в кортеж. Например, rect.collidedictall({tuple(key_rect) : value})