pygame / docs / reST / ref / sprite.rst

Full commit


This module contains several simple classes to be used within games. There is the main Sprite class and several Group classes that contain Sprites. The use of these classes is entirely optional when using Pygame. The classes are fairly lightweight and only provide a starting place for the code that is common to most games.

The Sprite class is intended to be used as a base class for the different types of objects in the game. There is also a base Group class that simply stores sprites. A game could create new types of Group classes that operate on specially customized Sprite instances they contain.

The basic Sprite class can draw the Sprites it contains to a Surface. The Group.draw() method requires that each Sprite have a Surface.image attribute and a Surface.rect. The Group.clear() method requires these same attributes, and can be used to erase all the Sprites with background. There are also more advanced Groups: pygame.sprite.RenderUpdates() and pygame.sprite.OrderedUpdates().

Lastly, this module contains several collision functions. These help find sprites inside multiple groups that have intersecting bounding rectangles. To find the collisions, the Sprites are required to have a Surface.rect attribute assigned.

The groups are designed for high efficiency in removing and adding Sprites to them. They also allow cheap testing to see if a Sprite already exists in a Group. A given Sprite can exist in any number of groups. A game could use some groups to control object rendering, and a completely separate set of groups to control interaction or player movement. Instead of adding type attributes or bools to a derived Sprite class, consider keeping the Sprites inside organized Groups. This will allow for easier lookup later in the game.

Sprites and Groups manage their relationships with the add() and remove() methods. These methods can accept a single or multiple targets for membership. The default initializers for these classes also takes a single or list of targets for initial membership. It is safe to repeatedly add and remove the same Sprite from a Group.

While it is possible to design sprite and group classes that don't derive from the Sprite and AbstractGroup classes below, it is strongly recommended that you extend those when you add a Sprite or Group class.

Sprites are not thread safe. So lock them yourself if using threads.

The base class for visible game objects. Derived classes will want to override the Sprite.update() and assign a Sprite.image and Sprite.rect attributes. The initializer can accept any number of Group instances to be added to.

When subclassing the Sprite, be sure to call the base initializer before adding the Sprite to Groups. For example:

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

       # 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])

       # 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()

Extra DirtySprite attributes with their default values:

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 therefor 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)

A simple container for Sprite objects. This class can be inherited to create containers with more specific behaviors. The constructor takes any number of Sprite arguments to add to the Group. The group supports the following standard Python operations:

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

The Sprites in the Group are not ordered, so drawing and iterating the Sprites is in no particular order.

This class is an alias to pygame.sprite.Group(). It has no additional functionality.

This class is an alias to pygame.sprite.Group(). It has no additional functionality.

This class is derived from pygame.sprite.Group(). It has an extended draw() method that tracks the changed areas of the screen.

This group is fully compatible with :class:`pygame.sprite.Sprite`.

You can set the default layer through kwargs using 'default_layer' and an integer for the layer. The default layer is 0.

If the sprite you add has an attribute layer then that layer will be used. If the **kwarg contains 'layer' then the sprites passed will be added to that layer (overriding the sprite.layer attribute). If neither sprite has attribute layer nor **kwarg then the default layer is used to add the sprites.

New in pygame 1.8.0

This group requires :class:`pygame.sprite.DirtySprite` or any sprite that has the following attributes:

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

It uses the dirty flag technique and is therefore faster than the :class:`pygame.sprite.RenderUpdates` if you have many static sprites. It also switches automatically between dirty rect update and full screen drawing, so you do no have to worry what would be faster.

Same as for the :class:`pygame.sprite.Group`. You can specify some additional attributes through kwargs:

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

New in pygame 1.8.0