pygame.sprite
pygame module with basic game object classes

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.
<SECTION>


Sprite
simple base class for visible game objects
pygame.sprite.Sprite(*groups): return Sprite

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.
<SECTION>


update
method to control sprite behavior
Sprite.update(*args):

The default implementation of this method does nothing; it's just a
convenient "hook" that you can override. This method is called by
Group.update() with whatever arguments you give it.

There is no need to use this method if not using the convenience 
method by the same name in the Group class.
<END>



add
add the sprite to groups
Sprite.add(*groups): return None

Any number of Group instances can be passed as arguments. The Sprite will
be added to the Groups it is not already a member of.
<END>



remove
remove the sprite from groups
Sprite.remove(*groups): return None

Any number of Group instances can be passed as arguments. The Sprite will
be removed from the Groups it is currently a member of.
<END>



kill
remove the Sprite from all Groups
Sprite.kill(): return None

The Sprite is removed from all the Groups that contain it. This won't
change anything about the state of the Sprite. It is possible to continue
to use the Sprite after this method has been called, including adding it
to Groups.
<END>



alive
does the sprite belong to any groups
Sprite.alive(): return bool

Returns True when the Sprite belongs to one or more Groups.
<END>



groups
list of Groups that contain this Sprite
Sprite.groups(): return group_list

Return a list of all the Groups that contain this Sprite.
<END>
<END>



DirtySprite
a more featureful subclass of Sprite with more attributes
pygame.sprite.DirtySprite(*groups): return DirtySprite

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 
    LayeredRenderGroup, for details see doc of LayeredRenderGroup)
<SECTION>

<END>
<END>



Group
container class for many Sprites
pygame.sprite.Group(*sprites): return Group

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.
<SECTION>



sprites
list of the Sprites this Group contains
Group.sprites(): return sprite_list

Return a list of all the Sprites this group contains. You can also get an
iterator from the group, but you cannot iterator over a Group while modifying
it.
<END>



copy
duplicate the Group
Group.copy(): return Group

Creates a new Group with all the same Sprites as the original. If you
have subclassed Group, the new object will have the same (sub-)class as
the original. This only works if the derived class's constructor takes
the same arguments as the Group class's.
<END>



add
add Sprites to this Group
Group.add(*sprites): return None

Add any number of Sprites to this Group. This will only add Sprites that are
not already members of the Group.

Each sprite argument can also be a iterator containing Sprites. 
<END>



remove
remove Sprites from the Group
Group.remove(*sprites): return None

Remove any number of Sprites from the Group. This will only remove Sprites
that are already members of the Group.

Each sprite argument can also be a iterator containing Sprites. 
<END>



has
test if a Group contains Sprites
Group.has(*sprites): return None

Return True if the Group contains all of the given sprites. This is similar to
using the "in" operator on the Group ("if sprite in group: ..."), which tests if 
a single Sprite belongs to a Group.

Each sprite argument can also be a iterator containing Sprites. 
<END>



update
call the update method on contained Sprites
Group.update(*args): return None

Calls the update() method on all Sprites in the Group. The base Sprite class
has an update method that takes any number of arguments and does nothing.
The arguments passed to Group.update() will be passed to each Sprite.

There is no way to get the return value from the Sprite.update() methods.
<END>



draw
blit the Sprite images
Group.draw(Surface): return None

Draws the contained Sprites to the Surface argument. This uses the Sprite.image
attribute for the source surface, and Sprite.rect for the position.

The Group does not keep sprites in any order, so the draw order is arbitrary.
<END>



clear
draw a background over the Sprites
Group.clear(Surface_dest, background): return None

Erases the Sprites used in the last Group.draw() call. The destination
Surface is cleared by filling the drawn Sprite positions with the background.

The background is usually a Surface image the same dimensions as the
destination Surface. However, it can also be a callback function that takes
two arguments; the destination Surface and an area to clear. The background
callback function will be called several times each clear.

Here is an example callback that will clear the Sprites with solid red:

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



empty
remove all Sprites
Group.empty(): return None

Removes all Sprites from this Group.
<END>
<END>



RenderUpdates
Group class that tracks dirty updates
pygame.sprite.RenderUpdates(*sprites): return RenderUpdates

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



draw
blit the Sprite images and track changed areas
RenderUpdates.draw(surface): return Rect_list

Draws all the Sprites to the surface, the same as Group.draw(). This method
also returns a list of Rectangular areas on the screen that have been
changed. The returned changes include areas of the screen that have been
affected by previous Group.clear() calls.

The returned Rect list should be passed to pygame.display.update(). This
will help performance on software driven display modes. This type of updating
is usually only helpful on destinations with non-animating backgrounds.
<END>
<END>



OrderedUpdates
RenderUpdates class that draws Sprites in order of addition
pygame.sprite.OrderedUpdates(*spites): return OrderedUpdates

This class derives from pygame.sprite.RenderUpdates(). It maintains 
the order in which the Sprites were added to the Group for rendering. 
This makes adding and removing Sprites from the Group a little slower 
than regular Groups.
<END>



LayeredUpdates
LayeredUpdates Group handles layers, that draws like OrderedUpdates.
pygame.sprite.LayeredUpdates(*spites, **kwargs): return LayeredUpdates
    
This group is fully compatible with 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
<SECTION>



add
add a sprite or sequence of sprites to a group
LayeredUpdates.add(*sprites, **kwargs): return None

If the sprite(s) have an attribute layer then that is used 
for the layer. If **kwargs contains 'layer' then the sprite(s) 
will be added to that argument (overriding the sprite layer 
attribute). If neither is passed then the sprite(s) will be
added to the default layer.
<END>



sprites
returns a ordered list of sprites (first back, last top).
LayeredUpdates.sprites(): return sprites
<END>



draw
draw all sprites in the right order onto the passed surface.
LayeredUpdates.draw(surface): return Rect_list
<END>



get_sprites_at
returns a list with all sprites at that position.
LayeredUpdates.get_sprites_at(pos): return colliding_sprites

Bottom sprites first, top last.
<END>



get_sprite
returns the sprite at the index idx from the groups sprites
LayeredUpdates.get_sprite(idx): return sprite

Raises IndexOutOfBounds if the idx is not within range.
<END>



remove_sprites_of_layer
removes all sprites from a layer and returns them as a list.
LayeredUpdates.remove_sprites_of_layer(layer_nr): return sprites
<END>



layers
returns a list of layers defined (unique), sorted from botton up.
LayeredUpdates.layers(): return layers
<END>



change_layer
changes the layer of the sprite
LayeredUpdates.change_layer(sprite, new_layer): return None

sprite must have been added to the renderer. It is not checked.
<END>



get_layer_of_sprite
returns the layer that sprite is currently in. 
LayeredUpdates.get_layer_of_sprite(sprite): return layer

If the sprite is not found then it will return the default layer.
<END>



get_top_layer
returns the top layer
LayeredUpdates.get_top_layer(): return layer
<END>



get_bottom_layer
returns the bottom layer
LayeredUpdates.get_bottom_layer(): return layer
<END>



move_to_front
brings the sprite to front layer
LayeredUpdates.move_to_front(sprite): return None

Brings the sprite to front, changing sprite layer to topmost layer
(added at the end of that layer).
<END>



move_to_back
moves the sprite to the bottom layer
LayeredUpdates.move_to_back(sprite): return None

Moves the sprite to the bottom layer, moving it behind
all other layers and adding one additional layer.
<END>



get_top_sprite
returns the topmost sprite
LayeredUpdates.get_top_sprite(): return Sprite
<END>



get_sprites_from_layer
returns all sprites from a layer, ordered by how they where added
LayeredUpdates.get_sprites_from_layer(layer): return sprites

Returns all sprites from a layer, ordered by how they where added.
It uses linear search and the sprites are not removed from layer.
<END>


 
switch_layer
switches the sprites from layer1 to layer2
LayeredUpdates.switch_layer(layer1_nr, layer2_nr): return None

The layers number must exist, it is not checked.
<END>
<END>



LayeredDirty
LayeredDirty Group is for DirtySprites.  Subclasses LayeredUpdates.
pygame.sprite.LayeredDirty(*spites, **kwargs): return LayeredDirty
    
This group requires 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 
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 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
<SECTION>



draw
draw all sprites in the right order onto the passed surface.
LayeredDirty.draw(surface, bgd=None): return Rect_list

You can pass the background too. If a background is already set, 
then the bgd argument has no effect.
<END>



clear
used to set background
LayeredDirty.clear(surface, bgd): return None
<END>



repaint_rect
repaints the given area
LayeredDirty.repaint_rect(screen_rect): return None

screen_rect is in screencoordinates.
<END>



set_clip
clip the area where to draw. Just pass None (default) to reset the clip
LayeredDirty.set_clip(screen_rect=None): return None
<END>



get_clip
clip the area where to draw. Just pass None (default) to reset the clip
LayeredDirty.get_clip(): return Rect
<END>



change_layer
changes the layer of the sprite
change_layer(sprite, new_layer): return None

sprite must have been added to the renderer. It is not checked.
<END>



set_timing_treshold
sets the treshold in milliseconds
set_timing_treshold(time_ms): return None

Default is 1000./80 where 80 is the fps I want to switch to full screen mode.
<END>
<END>



GroupSingle
Group container that holds a single Sprite
pygame.sprite.GroupSingle(sprite=None): return GroupSingle

The GroupSingle container only holds a single Sprite. When a new Sprite is
added, the old one is removed.

There is a special property, GroupSingle.sprite, that accesses the Sprite that
this Group contains. It can be None when the Group is empty. The property can
also be assigned to add a Sprite into the GroupSingle container.
<END>



spritecollide
find Sprites in a Group that intersect another Sprite
pygame.sprite.spritecollide(sprite, group, dokill, collided = None): return Sprite_list

Return a list containing all Sprites in a Group that intersect with another
Sprite. Intersection is determined by comparing the Sprite.rect attribute
of each Sprite.

The dokill argument is a bool. If set to True, all Sprites that collide
will be removed from the Group.

The collided argument is a callback function used to calculate if two sprites 
are colliding. it should take two sprites as values, and return a bool 
value indicating if they are colliding. If collided is not passed, all sprites 
must have a "rect" value, which is a rectangle of the sprite area, which will 
be used to calculate the collision. 

collided callables: 
    collide_rect, collide_rect_ratio, collide_circle, 
    collide_circle_ratio, collide_mask 
<END>



collide_rect
collision detection between two sprites, using rects.
pygame.sprite.collide_rect(left, right): return bool

Tests for collision between two sprites. Uses the
pygame rect colliderect function to calculate the
collision. Intended to be passed as a collided
callback function to the *collide functions.
Sprites must have a "rect" attributes.

New in pygame 1.8.0
<END>



collide_rect_ratio
collision detection between two sprites, using rects scaled to a ratio.
pygame.sprite.collide_rect_ratio(ratio): return collided_callable

A callable class that checks for collisions between two sprites, 
using a scaled version of the sprites rects.

Is created with a ratio, the instance is then intended to be passed 
as a collided callback function to the *collide functions.

A ratio is a floating point number - 1.0 is the same size, 2.0 is twice as
big, and 0.5 is half the size.

New in pygame 1.8.1
<END>



collide_circle
collision detection between two sprites, using circles.
pygame.sprite.collide_circle(left, right): return bool

Tests for collision between two sprites, by testing to
see if two circles centered on the sprites overlap. If
the sprites have a "radius" attribute, that is used to
create the circle, otherwise a circle is created that
is big enough to completely enclose the sprites rect as
given by the "rect" attribute. Intended to be passed as
a collided callback function to the *collide functions.
Sprites must have a "rect" and an optional "radius"
attribute.

New in pygame 1.8.1
<END>



collide_circle_ratio
collision detection between two sprites, using circles scaled to a ratio.
pygame.sprite.collide_circle_ratio(ratio): return collided_callable

A callable class that checks for collisions between two sprites, 
using a scaled version of the sprites radius.

Is created with a floating point ratio, the instance is then intended 
to be passed as a collided callback function to the *collide functions.

A ratio is a floating point number - 1.0 is the same size, 2.0 is twice as
big, and 0.5 is half the size.

The created callable tests for collision between two sprites, by testing to
see if two circles centered on the sprites overlap, after
scaling the circles radius by the stored ratio. If
the sprites have a "radius" attribute, that is used to
create the circle, otherwise a circle is created that
is big enough to completely enclose the sprites rect as
given by the "rect" attribute. Intended to be passed as
a collided callback function to the *collide functions.
Sprites must have a "rect" and an optional "radius"
attribute.

New in pygame 1.8.1
<END>



collide_mask
collision detection between two sprites, using masks.
pygame.sprite.collide_mask(SpriteLeft, SpriteRight): return bool

Tests for collision between two sprites, by testing if
thier bitmasks overlap. If the sprites have a "mask"
attribute, that is used as the mask, otherwise a mask is
created from the sprite image. Intended to be passed as
a collided callback function to the *collide functions.
Sprites must have a "rect" and an optional "mask"
attribute.

New in pygame 1.8.0
<END>



groupcollide
find all Sprites that collide between two Groups
pygame.sprite.groupcollide(group1, group2, dokill1, dokill2): return Sprite_dict

This will find intersections between all the Sprites in two groups.
Intersection is determined by comparing the Sprite.rect attribute of
each Sprite.

Every Sprite inside group1 is added to the return dictionary. The value
for each item is the list of Sprites in group2 that intersect.

If either dokill argument is True, the intersecting Sprites will be removed
from their respective Group.
<END>



spritecollideany
simple test if a Sprite intersects anything in a Group
pygame.sprite.spritecollideany(sprite, group): return bool

Test if the given Sprite intersects with any Sprites in a Group. Intersection
is determined by comparing of the Sprite.rect attribute of each Sprite.

This collision test can be faster than pygame.sprite.spritecollide() since
it has less work to do.
<END>






<END>