Sprite类

pygame.sprite.Sprite 可视游戏中的对象的基础类

属性：Sprite(*groups) -> Sprite

使用Sprite类派生新类时需要分配 Sprite.image 和 Sprite.rect 属性并添加 Sprite.update() 方法。初始设定项可以添加任何数量的组（Group）实例。当派生 Sprite类的子类时，请确保在将 Sprite类添加到组群（ Groups）之前已调用基础初始设定项。例如：

class Block(pygame.sprite.Sprite):
 
    # 构造函数。传入图块的颜色和x,y位置。
    def __init__(self, color, width, height):
       # 调用父类 (Sprite) 构造函数
       pygame.sprite.Sprite.__init__(self)
 
       # 创建一个图块并填色，或加载image
       self.image = pygame.Surface([width, height])
       self.image.fill(color)
 
       # 获取有图像尺寸的Rect形对象
       # 通过设定rect.x和rect.y来更新对象的位置
       self.rect = self.image.get_rect()

pygame.sprite.Sprite.update() 控制精灵行为的方法

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

这个方法的默认执行动作为nothing，是一个便于重写的“钩子”。此方法由 Group.update() 调用。【 Group.update() 参数可随意设定】

如果不使用组类中的同名方法，则无需使用此方法。

pygame.sprite.Sprite.add() 将精灵添加到组

add(*groups) -> None

任何数量的组实例都可以作为参数传递。精灵将被添加到它还不是成员的组中。

pygame.sprite.Sprite.remove() 从组中移除精灵

remove(*groups) -> None

任何数量的组实例都可以作为参数传递。精灵将从其当前所属的组中移除。

pygame.sprite.Sprite.kill()从所有组中移除精灵

kill() -> None

精灵将从包含它的所有组中移除。这不会改变精灵的状态。调用此方法后，可以继续使用精灵，包括将其添加到组中。

pygame.sprite.Sprite.alive()判断精灵是否属于任何一个团体

alive() -> bool

当精灵属于一个或多个组时返回True。

pygame.sprite.Sprite.groups() 获取包含此精灵的组列表

groups() -> group_list

返回包含此精灵的所有组的列表。

pygame.sprite.DirtySprite 精灵类的一个子类，具有更多的属性和特性。

DirtySprite(*groups) -> DirtySprite

额外的DirtySprite属性及其默认值：

dirty = 1

如果设置为1，则重新绘制，然后再次设置为0

如果设置为2，则它总是脏的（重新绘制每个帧，flag未重置）

0表示它不脏，因此不会重新喷绘

blendmode = 0 blit，blendmodes的特殊flags参数

source_rect = None

要使用的源rect，相对于self.imaged的topleft（0,0）

visible = 1

通常为1，如果设置为0，则不会重新喷绘（必须将其设置为脏的以便从屏幕上删除）

layer = 0

只读值，将其添加到LayeredDirty时可读（详见LayeredDirty文档）

pygame.sprite.Group 用于保存和管理多重精灵对象的容器类。

Group(*sprites) -> Group

简单的精灵对象的容器。可以继承该类以创建具有更特定行为的容器。构造函数接受任意数量的精灵参数添加到组类中。该组类支持以下标准的Python操作：

in 测试一个精灵是否被包含在内

len 包含的精灵数

bool 测试是否包含任何精灵

iter 遍历所有精灵

组类中的精灵没有顺序，因此绘制和迭代精灵没有特定的顺序。

pygame.sprite.Group.sprites() 此组类包含的精灵列表

sprites() -> sprite_list

返回此组类包含的所有精灵的列表。也可以从组类中获取迭代器，但在修改组类时不能对其进行迭代器操作。

pygame.sprite.Group.copy() 复制组类

copy() -> Group

创建一个与原始组类具有相同精灵的新组类。如果有子类组类，则新对象将具有与原始对象相同的（子）类。仅当派生类的构造函数采用与组类相同的参数时，此操作才有效。

pygame.sprite.Group.add() 将精灵添加到此组类

add(*sprites) -> None

将任意数量的精灵添加到此组。此方法只会将精灵添加进尚未成为成员的组类中。

每个精灵参数也可以是包含精灵的迭代器。

pygame.sprite.Group.remove() 从组类中移除精灵

remove(*sprites) -> None

从组中移除任意数量的精灵，将只删除已经是组类成员的精灵。

每个精灵参数也可以是包含精灵的迭代器。

pygame.sprite.Group.has() 测试组类是否包含精灵

has(*sprites) -> bool

如果组类包含所有给定的精灵，则返回True。这类似于在组类上使用“in”运算符（“if sprite in Group:…”）测试单个sprite是否属于组。

每个精灵参数也可以是包含精灵的迭代器。

pygame.sprite.Group.update() 对包含的精灵调用update方法

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

对组类中的所有精灵调用 update() 方法。基础Sprite类有一个 update() 方法，该方法接收任意数量的参数但不执行任何操作。传递给 Group.update()的参数将传递给每个精灵。

无法从 Sprite.update() 方法获得返回值。

pygame.sprite.Group.draw() 位块传输精灵images

draw(Surface) -> None

将包含的精灵绘制到Surface参数。使用 Sprite.image 属性和 Sprite.rect 属性作为源surface的属性。

组类不按任何顺序保存精灵，因此绘制顺序是任意的。

pygame.sprite.Group.clear() 在精灵上（覆盖）绘制背景

clear(Surface_dest, background) -> None

删除上次使用 Group.draw()绘制的精灵。通过用背景填充绘制的精灵位置来清除目标Surface。

背景通常是与目标Surface尺寸相同的Surface image。但是，它也可以是一个有两个参数【目标Surface和要清除的区域】的回调函数。后台回调函数将在每次清除时调用多次。下面是一个回调示例，它将清除纯红的精灵：

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

pygame.sprite.Group.empty() 移除所有精灵

empty() -> None

从该组中删除所有精灵。

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() 方法，用于跟踪屏幕的更改区域。

pygame.sprite.RenderUpdates.draw() 位块传输精灵images并跟踪更改的区域

draw(surface) -> Rect_list

将所有精灵绘制到Surface，等同于 Group.draw()。此方法还返回屏幕上一个已更改的矩形区域的列表。返回的更改包括受前一个 Group.clear()调用影响的屏幕区域。

返回的Rect列表会传递给pygame.display.update()。 这将有助于提高软件驱动显示模式的性能。这种类型的更新通常只对具有非动画背景的目标有用。

pygame.sprite.OrderedUpdates() RenderUpdates子类，按添加顺序绘制精灵。

属性：OrderedUpdates(*spites) -> OrderedUpdates

这个类派生自 pygame.sprite.RenderUpdates()。它维持将精灵添加到组类中进行渲染的顺序。这使得在组类中添加和移除精灵的速度比常规组类稍慢。

pygame.sprite.LayeredUpdates 图层类

LayeredUpdates是一个精灵组，处理层和绘制【like OrderedUpdates】。

属性：LayeredUpdates(*spites, **kwargs) -> LayeredUpdates

此组可以与pygame.sprite.Sprite完全兼容。

可以使用’default_layer’或一个整数来通过kwargs设置默认图层。默认层为0。

如果添加的精灵有一个属性层，则将使用该层。如果

kwarg包含“layer”，则传递的精灵将添加到该层（重写sprite.layer属性）。如果精灵既没有属性层也没有

kwarg，则使用默认层添加精灵。

New in pygame 1.8.

pygame.sprite.LayeredUpdates.add() 将一个精灵或精灵序列添加到一个组中

属性：add(*sprites, **kwargs) -> None

如果 sprite(s)（精灵）有一个属性层，则该属性层用于该层。如果**kwargs包含“layer”，则 sprite(s) 将被添加到该参数中（重写精灵层属性）。如果两者都不通过，则 sprite(s) 将添加到默认层。

pygame.sprite.LayeredUpdates.sprites() 返回精灵的有序列表（第一个在下，最后一个上）

属性：sprites() -> sprites

pygame.sprite.LayeredUpdates.draw()

功能：按正确顺序将所有精灵绘制到传递的Surface上。

属性：draw(surface) -> Rect_list

pygame.sprite.LayeredUpdates.get_sprites_at()

功能：返回一个包含该位置所有精灵的列表（第一个在下，最后一个上）

属性：get_sprites_at(pos) -> colliding_sprites

pygame.sprite.LayeredUpdates.get_sprite()

功能：从组精灵中返回索引idx处的精灵

属性：get_sprite(idx) -> sprite

如果idx不在范围内，则引发 IndexOutOfBounds 。

pygame.sprite.LayeredUpdates.remove_sprites_of_layer()

功能：从层中移除所有精灵并将其作为列表返回。

属性：remove_sprites_of_layer(layer_nr) -> sprites

pygame.sprite.LayeredUpdates.layers()

功能：返回定义的（唯一的）图层列表，从下到上排序。

属性：layers() -> layers

pygame.sprite.LayeredUpdates.change_layer()

功能：更改精灵的层

属性：change_layer(sprite, new_layer) -> None

必须事先将精灵添加到渲染器中。注意检查。

pygame.sprite.LayeredUpdates.get_layer_of_sprite()

功能：返回精灵当前所在的层。

属性：get_layer_of_sprite(sprite) -> layer

如果找不到精灵，它将返回默认层。

pygame.sprite.LayeredUpdates.get_top_layer()

功能：返回顶层

属性：get_top_layer() -> layer

pygame.sprite.LayeredUpdates.get_bottom_layer()

功能：返回底层

属性：get_bottom_layer() -> layer

pygame.sprite.LayeredUpdates.move_to_front()

功能：把精灵带到顶层

属性：move_to_front(sprite) -> None

将精灵置于最前面，将精灵层更改为最顶层（添加在该层的末尾）。

pygame.sprite.LayeredUpdates.move_to_back()

功能：将精灵移动到底层

属性：move_to_back(sprite) -> None

将精灵移动到底层，将其移到所有其他层的后面并添加一个附加层。

pygame.sprite.LayeredUpdates.get_top_sprite()

功能：返回最上面的精灵

属性：get_top_sprite() -> Sprite

pygame.sprite.LayeredUpdates.get_sprites_from_layer()

返回一个层中的所有精灵，按其添加位置排序：功能

属性：get_sprites_from_layer(layer) -> sprites

返回图层中的所有精灵，按其添加位置排序。它使用线性搜索，精灵不会从层中移除。

pygame.sprite.LayeredUpdates.switch_layer()

功能：将精灵从层1切换到层2

属性：switch_layer(layer1_nr, layer2_nr) -> None

层编号必须存在，注意检查。

pygame.sprite.LayeredDirty

功能：LayeredDirty组类用于DirtySprite对象。子类LayeredUpdates。

属性：LayeredDirty(*spites, **kwargs) -> LayeredDirty

此组类需要 pygame.sprite.DirtySprite 或具有以下属性的任何精灵：image, rect, dirty, visible, blendmode (see doc of DirtySprite).

此组类使用脏标志技术，因此比 pygame.sprite.RenderUpdates更快。如果程序有很多静态精灵，它还可以在脏的rect更新和全屏绘图之间自动切换。

与 pygame.sprite.Group 一样，可以通过kwargs指定一些其他属性：

_use_update True/False 默认是 False

_default_layer 没有图层添加的精灵的默认图层

_time_threshold

脏rect模式之间切换的阈值时间。全屏模式，默认为1000./80==1000./fps

New in pygame 1.8.

pygame.sprite.LayeredDirty.draw()

功能：按正确顺序将所有精灵绘制到被传递surface上。

属性：draw(surface, bgd=None) -> Rect_list

也可以传递背景。如果已设置背景，则bgd参数无效。

pygame.sprite.LayeredDirty.clear()

功能：用于设置背景

属性：clear(surface, bgd) -> None

pygame.sprite.LayeredDirty.repaint_rect()

功能：重新绘制给定区域，screen_rect 在屏幕坐标中。

属性：repaint_rect(screen_rect) -> None

pygame.sprite.LayeredDirty.set_clip()

功能：剪辑要绘制的区域。通过传递 None（默认值）以重置剪辑

属性：set_clip(screen_rect=None) -> None

pygame.sprite.LayeredDirty.get_clip()

功能：剪辑要绘制的区域。通过传递 None（默认值）以重置剪辑

属性：get_clip() -> Rect

pygame.sprite.LayeredDirty.change_layer()

功能：更改精灵的层

属性：change_layer(sprite, new_layer) -> None

必须事先将精灵添加到渲染器中，注意检查。

pygame.sprite.LayeredDirty.set_timing_treshold()

功能：以毫秒为单位设置阈值

属性：set_timing_treshold(time_ms) -> None

默认值是1000/80，其中80是切换到全屏模式的fps。此方法的名称有小错误。

Raises: 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参数是个布尔量。如果设置为True，则所有碰撞的精灵都将从组中移除。

碰撞参数是一个回调函数，用于计算两个精灵是否碰撞。它应该取两个精灵作为值，并返回一个bool值，指示它们是否发生碰撞。如果未碰撞，则所有精灵都必须具有“rect”值【精灵区域的矩形，用于计算碰撞】。collided 可调用参数：collide_rect, collide_rect_ratio, collide_circle,collide_circle_ratio, collide_mask。例如：

查看精灵块是否与组类block_list中的任何内容冲突

True标志将删除block_list中的精灵

blocks_hit_list = pygame.sprite.spritecollide(player, block_list, True)

检查碰撞精灵列表，并计数

for block in blocks_hit_list:

score +=1

​​​​​​​pygame.sprite.collide_rect()

功能：检测两个精灵之间的碰撞，使用rects表示。

属性：collide_rect(left, right) -> bool

测试两个精灵之间的碰撞。使用pygame rect colliderect函数计算碰撞。并作为碰撞回调函数传递给*collide函数。

精灵必须具有“rect”属性。

New in pygame 1.8.

pygame.sprite.collide_rect_ratio()

功能：两个精灵之间的碰撞检测，使用给定比例缩放的rects表示。

属性：collide_rect_ratio(ratio) -> collided_callable

一个检查两个精灵之间碰撞的可调用的类，使用精灵rects的缩放版本表示。

使用比率创建，然后将实例作为冲突回调函数传递给*collide函数。

比率是一个浮点数 – 1.0是相同的大小，2.0是两倍大，0.5是一半大

New in pygame 1.8.1.

pygame.sprite.collide_circle()

功能：检测两个精灵之间的碰撞，使用圆表示。

属性：collide_circle(left, right) -> bool

测试两个精灵之间的碰撞，方法是测试以精灵为中心的两个圆是否重叠。如果精灵有一个“radius”属性，该属性用于创建圆，否则将创建一个大到足以完全包围精灵“rect”属性的圆。并作为冲突回调函数传递给*collide函数。

精灵必须有一个“rect”和一个可选的“radius”属性。

New in pygame 1.8.1.

pygame.sprite.collide_circle_ratio()

功能：两个精灵之间的碰撞检测，使用给定比例缩放的圆表示。

属性：collide_circle_ratio(ratio) -> collided_callable

一个检查两个精灵之间碰撞的可调用的类，使用精灵radius的缩放版本表示。

使用浮点比率创建，然后将实例作为冲突回调函数传递给

collide函数。

比率是一个浮点数 – 1.0是相同的大小，2.0是两倍大，0.5是一半大。

创建的两个精灵之间碰撞的可调用测试，方法是在按存储的比率缩放圆半径后，测试以精灵为中心的两个圆是否重叠。如果精灵有一个“radius”属性，该属性用于创建圆，否则将创建一个大到足以完全包围精灵rect”属性的圆。并作为冲突回调函数传递给

collide函数。

精灵必须有一个“rect”和一个可选的“radius”属性。

New in pygame 1.8.1.

pygame.sprite.collide_mask()

功能：两个精灵之间的碰撞检测，使用mask表示。

属性：

collide_mask(sprite1, sprite2) -> (int, int)

collide_mask(sprite1, sprite2) -> None

通过测试两个精灵的位掩码是否重叠（使用 pygame.mask.Mask.overlap()）检测碰撞。如果精灵具有 mask 属性，则将其用作掩码，否则将从精灵的 image属性创建掩码（使用 pygame.mask.from_surface()）。精灵必须具有 rect 属性； mask 属性是可选的。

返回掩码之间的第一个碰撞点。碰撞点的坐标原点是精灵1的掩码左上角【始终视为(0，0)】。碰撞点是掩码内的一个位置，与精灵1的实际屏幕位置无关。

此函数将作为碰撞回调函数传递给组类碰撞函数（请参见spritecollide()、group collide()、spritecollideany()）。

注意：

若要提高性能，请为将使用此函数检查碰撞的所有精灵创建并设置 mask 属性。否则，每次调用此函数时，它都将创建新的掩码。

每次更改精灵的图像时（例如，如果使用新图像或旋转现有图像），都需要重新创建一个新的掩码。

为精灵创建掩码的示例。

sprite.mask = pygame.mask.from_surface(sprite.image)

Returns: 掩码之间的第一个冲突点；如果没有冲突，则返回 None

Return type: tuple(int, int) 或 NoneType

New in pygame 1.8.0.

pygame.sprite.groupcollide()

功能：查找两个组之间碰撞的所有精灵

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

此方法将查找两个组中所有精灵之间的碰撞。碰撞是通过比较每个精灵的 Sprite.rect 属性，如果，或者使用collided函数【其参数不是None时】。

group1中的每个精灵都会被添加到返回字典中。每个项的值是group2中相交的精灵列表。

如果dokill参数为真，碰撞的精灵将从各自的组类中移除。

碰撞参数是一个回调函数，用于计算两个精灵是否碰撞。它应该取两个精灵作为值，并返回一个bool值，指示它们是否发生碰撞。如果未发生碰撞，则所有精灵都必须具有一个“rect”值【精灵区域的矩形，用于计算碰撞】。

pygame.sprite.spritecollideany()

功能：简单测试一个精灵是否与一组中的 anything 相交。

属性：

spritecollideany(sprite, group, collided = None) -> Sprite Collision with the returned sprite.

spritecollideany(sprite, group, collided = None) -> None No collision

如果精灵与组中的任何单个精灵碰撞，则返回组中的单个精灵。无碰撞时返回None。

如果你不需要pygame.sprite.spritecollide() 函数的所有特征，此函数将快一点。

碰撞参数是一个回调函数，用于计算两个精灵是否碰撞。它应该取两个精灵作为值，并返回一个bool值，指示它们是否发生碰撞。如果未发生碰撞，则所有精灵都必须具有一个“rect”值【精灵区域的矩形，用于计算碰撞】。