<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>Pygame Tutorials - Sprite Module Introduction — pygame v2.5.2 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/pygame.css" />
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/pygame.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Pygame Tutorials - Surfarray Introduction" href="SurfarrayIntro.html" />
<link rel="prev" title="Pygame Intro" href="PygameIntro.html" />
</head><body>
<div class="document">
<div class="header">
<div class="flex-container">
<div class="logo">
<a href="https://www.pygame.org/">
<img src="../_static/pygame_tiny.png"/>
</a>
<h5>pygame documentation</h5>
</div>
<div class="pagelinks">
<div class="top">
<a href="https://www.pygame.org/">Pygame Home</a> ||
<a href="../index.html">Help Contents</a> ||
<a href="../genindex.html">Reference Index</a>
<form action="../search.html" method="get" style="display:inline;float:right;">
<input name="q" value="" type="text">
<input value="search" type="submit">
</form>
</div>
<hr style="color:black;border-bottom:none;border-style: dotted;border-bottom-style:none;">
<p class="bottom"><b>Most useful stuff</b>:
<a href="../ref/color.html">Color</a> |
<a href="../ref/display.html">display</a> |
<a href="../ref/draw.html">draw</a> |
<a href="../ref/event.html">event</a> |
<a href="../ref/font.html">font</a> |
<a href="../ref/image.html">image</a> |
<a href="../ref/key.html">key</a> |
<a href="../ref/locals.html">locals</a> |
<a href="../ref/mixer.html">mixer</a> |
<a href="../ref/mouse.html">mouse</a> |
<a href="../ref/rect.html">Rect</a> |
<a href="../ref/surface.html">Surface</a> |
<a href="../ref/time.html">time</a> |
<a href="../ref/music.html">music</a> |
<a href="../ref/pygame.html">pygame</a>
</p>
<p class="bottom"><b>Advanced stuff</b>:
<a href="../ref/cursors.html">cursors</a> |
<a href="../ref/joystick.html">joystick</a> |
<a href="../ref/mask.html">mask</a> |
<a href="../ref/sprite.html">sprite</a> |
<a href="../ref/transform.html">transform</a> |
<a href="../ref/bufferproxy.html">BufferProxy</a> |
<a href="../ref/freetype.html">freetype</a> |
<a href="../ref/gfxdraw.html">gfxdraw</a> |
<a href="../ref/midi.html">midi</a> |
<a href="../ref/pixelarray.html">PixelArray</a> |
<a href="../ref/pixelcopy.html">pixelcopy</a> |
<a href="../ref/sndarray.html">sndarray</a> |
<a href="../ref/surfarray.html">surfarray</a> |
<a href="../ref/math.html">math</a>
</p>
<p class="bottom"><b>Other</b>:
<a href="../ref/camera.html">camera</a> |
<a href="../ref/sdl2_controller.html#module-pygame._sdl2.controller">controller</a> |
<a href="../ref/examples.html">examples</a> |
<a href="../ref/fastevent.html">fastevent</a> |
<a href="../ref/scrap.html">scrap</a> |
<a href="../ref/tests.html">tests</a> |
<a href="../ref/touch.html">touch</a> |
<a href="../ref/pygame.html#module-pygame.version">version</a>
</p>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="body" role="main">
<section id="pygame-tutorials-sprite-module-introduction">
<section id="sprite-module-introduction">
<h2>Sprite Module Introduction<a class="headerlink" href="#sprite-module-introduction" title="Permalink to this headline">¶</a></h2>
<dl class="docinfo field-list simple">
<dt class="field-odd">Author</dt>
<dd class="field-odd"><p>Pete Shinners</p>
</dd>
<dt class="field-even">Contact</dt>
<dd class="field-even"><p><a class="reference external" href="mailto:pete%40shinners.org">pete<span>@</span>shinners<span>.</span>org</a></p>
</dd>
</dl>
<p>Pygame version 1.3 comes with a new module, <code class="docutils literal notranslate"><span class="pre">pygame.sprite</span></code>. This module is
written in Python and includes some higher-level classes to manage your game
objects. By using this module to its full potential, you can easily manage and
draw your game objects. The sprite classes are very optimized, so it's likely
your game will run faster with the sprite module than without.</p>
<p>The sprite module is also meant to be very generic. It turns out you can use it
with nearly any type of gameplay. All this flexibility comes with a slight
penalty, it needs a little understanding to properly use it. The
<a class="reference internal" href="../ref/sprite.html#module-pygame.sprite" title="pygame.sprite: pygame module with basic game object classes"><code class="xref py py-mod docutils literal notranslate"><span class="pre">reference</span> <span class="pre">documentation</span></code></a> for the sprite module can keep
you running, but you'll probably need a bit more explanation of how to use
<code class="docutils literal notranslate"><span class="pre">pygame.sprite</span></code> in your own game.</p>
<p>Several of the pygame examples (like "chimp" and "aliens") have been updated to
use the sprite module. You may want to look into those first to see what this
sprite module is all about. The chimp module even has its own line-by-line
tutorial, which may help get more an understanding of programming with python
and pygame.</p>
<p>Note that this introduction will assume you have a bit of experience
programming with python, and are somewhat familiar with the different parts of
creating a simple game. In this tutorial the word "reference" is occasionally
used. This represents a python variable. Variables in python are references,
so you can have several variables all pointing to the same object.</p>
<section id="history-lesson">
<h3>History Lesson<a class="headerlink" href="#history-lesson" title="Permalink to this headline">¶</a></h3>
<p>The term "sprite" is a holdover from older computer and game machines. These
older boxes were unable to draw and erase normal graphics fast enough for them
to work as games. These machines had special hardware to handle game like
objects that needed to animate very quickly. These objects were called
"sprites" and had special limitations, but could be drawn and updated very
fast. They usually existed in special overlay buffers in the video. These days
computers have become generally fast enough to handle sprite like objects
without dedicated hardware. The term sprite is still used to represent just
about anything in a 2D game that is animated.</p>
</section>
<section id="the-classes">
<h3>The Classes<a class="headerlink" href="#the-classes" title="Permalink to this headline">¶</a></h3>
<p>The sprite module comes with two main classes. The first is <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Sprite" title="pygame.sprite.Sprite"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sprite</span></code></a>, which should be used as a base class for all your game
objects. This class doesn't really do anything on its own, it just includes
several functions to help manage the game object. The other type of class is
<a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group" title="pygame.sprite.Group"><code class="xref py py-class docutils literal notranslate"><span class="pre">Group</span></code></a>. The <code class="docutils literal notranslate"><span class="pre">Group</span></code> class is a container for
different <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> objects. There are actually several different types of
group classes. Some of the <code class="docutils literal notranslate"><span class="pre">Groups</span></code> can draw all the elements they contain,
for example.</p>
<p>This is all there really is to it. We'll start with a description of what each
type of class does, and then discuss the proper ways to use these two classes.</p>
</section>
<section id="the-sprite-class">
<h3>The Sprite Class<a class="headerlink" href="#the-sprite-class" title="Permalink to this headline">¶</a></h3>
<p>As mentioned before, the Sprite class is designed to be a base class for all
your game objects. You cannot really use it on its own, as it only has several
methods to help it work with the different <code class="docutils literal notranslate"><span class="pre">Group</span></code> classes. The sprite keeps
track of which groups it belongs to.
The class constructor (<code class="docutils literal notranslate"><span class="pre">__init__</span></code> method) takes an argument of a
<code class="docutils literal notranslate"><span class="pre">Group</span></code> (or list of <code class="docutils literal notranslate"><span class="pre">Groups</span></code>) the <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> instance should belong to.
You can also change the <code class="docutils literal notranslate"><span class="pre">Group</span></code> membership for the <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> with the
<a class="reference internal" href="../ref/sprite.html#pygame.sprite.Sprite.add" title="pygame.sprite.Sprite.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code></a> and
<a class="reference internal" href="../ref/sprite.html#pygame.sprite.Sprite.remove" title="pygame.sprite.Sprite.remove"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remove()</span></code></a> methods.
There is also a <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Sprite.groups" title="pygame.sprite.Sprite.groups"><code class="xref py py-meth docutils literal notranslate"><span class="pre">groups()</span></code></a> method,
which returns a list of the current groups containing the sprite.</p>
<p>When using the your Sprite classes it's best to think of them as "valid" or
"alive" when they are belonging to one or more <code class="docutils literal notranslate"><span class="pre">Groups</span></code>. When you remove the
instance from all groups pygame will clean up the object. (Unless you have your
own references to the instance somewhere else.) The <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Sprite.kill" title="pygame.sprite.Sprite.kill"><code class="xref py py-meth docutils literal notranslate"><span class="pre">kill()</span></code></a> method removes the sprite from all groups it
belongs to. This will cleanly delete the sprite object. If you've put some
little games together, you'll know sometimes cleanly deleting a game object can
be tricky. The sprite also comes with an <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Sprite.alive" title="pygame.sprite.Sprite.alive"><code class="xref py py-meth docutils literal notranslate"><span class="pre">alive()</span></code></a> method, which returns true if it is still a
member of any groups.</p>
</section>
<section id="the-group-class">
<h3>The Group Class<a class="headerlink" href="#the-group-class" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">Group</span></code> class is just a simple container. Similar to the sprite, it has
an <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group.add" title="pygame.sprite.Group.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code></a> and <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group.remove" title="pygame.sprite.Group.remove"><code class="xref py py-meth docutils literal notranslate"><span class="pre">remove()</span></code></a> method which can change which sprites belong to
the group. You also can pass a sprite or list of sprites to the constructor
(<code class="docutils literal notranslate"><span class="pre">__init__()</span></code> method) to create a <code class="docutils literal notranslate"><span class="pre">Group</span></code> instance that contains some
initial sprites.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Group</span></code> has a few other methods like <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group.empty" title="pygame.sprite.Group.empty"><code class="xref py py-meth docutils literal notranslate"><span class="pre">empty()</span></code></a> to remove all sprites from the group and
<a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group.copy" title="pygame.sprite.Group.copy"><code class="xref py py-meth docutils literal notranslate"><span class="pre">copy()</span></code></a> which will return a copy of the group
with all the same members. Also the <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group.has" title="pygame.sprite.Group.has"><code class="xref py py-meth docutils literal notranslate"><span class="pre">has()</span></code></a>
method will quickly check if the <code class="docutils literal notranslate"><span class="pre">Group</span></code> contains a sprite or list of
sprites.</p>
<p>The other function you will use frequently is the <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group.sprites" title="pygame.sprite.Group.sprites"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sprites()</span></code></a> method. This returns an object that can be
looped on to access every sprite the group contains. Currently this is just a
list of the sprites, but in later version of python this will likely use
iterators for better performance.</p>
<p>As a shortcut, the <code class="docutils literal notranslate"><span class="pre">Group</span></code> also has an <a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group.update" title="pygame.sprite.Group.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code></a> method, which will call an <code class="docutils literal notranslate"><span class="pre">update()</span></code> method on
every sprite in the group. Passing the same arguments to each one. Usually in a
game you need some function that updates the state of a game object. It's very
easy to call your own methods using the <code class="docutils literal notranslate"><span class="pre">Group.sprites()</span></code> method, but this is
a shortcut that's used enough to be included. Also note that the base
<code class="docutils literal notranslate"><span class="pre">Sprite</span></code> class has a "dummy" <code class="docutils literal notranslate"><span class="pre">update()</span></code> method that takes any sort of
arguments and does nothing.</p>
<p>Lastly, the Group has a couple other methods that allow you to use it with
the builtin <code class="docutils literal notranslate"><span class="pre">len()</span></code> function, getting the number of sprites it contains, and
the "truth" operator, which allows you to do "if mygroup:" to check if the
group has any sprites.</p>
</section>
<section id="mixing-them-together">
<h3>Mixing Them Together<a class="headerlink" href="#mixing-them-together" title="Permalink to this headline">¶</a></h3>
<p>At this point the two classes seem pretty basic. Not doing a lot more than you
can do with a simple list and your own class of game objects. But there are
some big advantages to using the <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> and <code class="docutils literal notranslate"><span class="pre">Group</span></code> together. A sprite
can belong to as many groups as you want. Remember as soon as it belongs to no
groups, it will usually be cleared up (unless you have other "non-group"
references to that object).</p>
<p>The first big thing is a fast simple way to categorize sprites. For example,
say we had a Pacman-like game. We could make separate groups for the different
types of objects in the game. Ghosts, Pac, and Pellets. When Pac eats a power
pellet, we can change the state for all ghost objects by effecting everything
in the Ghost group. This is quicker and simpler than looping through a list
of all the game objects and checking which ones are ghosts.</p>
<p>Adding and removing groups and sprites from each other is a very fast
operation, quicker than using lists to store everything. Therefore you can very
efficiently change group memberships. Groups can be used to work like simple
attributes for each game object. Instead of tracking some attribute like
"close_to_player" for a bunch of enemy objects, you could add them to a
separate group. Then when you need to access all the enemies that are near the
player, you already have a list of them, instead of going through a list of all
the enemies, checking for the "close_to_player" flag. Later on your game could
add multiple players, and instead of adding more "close_to_player2",
"close_to_player3" attributes, you can easily add them to different groups for
each player.</p>
<p>Another important benefit of using the <code class="docutils literal notranslate"><span class="pre">Sprites</span></code> and <code class="docutils literal notranslate"><span class="pre">Groups</span></code> is that the groups
cleanly handle the deleting (or killing) of game objects. In a game where many
objects are referencing other objects, sometimes deleting an object can be the
hardest part, since it can't go away until it is not referenced by anyone. Say
we have an object that is "chasing" another object. The chaser can keep a
simple Group that references the object (or objects) it is chasing. If the
object being chased happens to be destroyed, we don't need to worry about
notifying the chaser to stop chasing. The chaser can see for itself that its
group is now empty, and perhaps find a new target.</p>
<p>Again, the thing to remember is that adding and removing sprites from groups is
a very cheap/fast operation. You may be best off by adding many groups to
contain and organize your game objects. Some could even be empty for large
portions of the game, there isn't any penalties for managing your game like
this.</p>
</section>
<section id="the-many-group-types">
<h3>The Many Group Types<a class="headerlink" href="#the-many-group-types" title="Permalink to this headline">¶</a></h3>
<p>The above examples and reasons to use <code class="docutils literal notranslate"><span class="pre">Sprites</span></code> and <code class="docutils literal notranslate"><span class="pre">Groups</span></code> are only a tip
of the iceberg. Another advantage is that the sprite module comes with several
different types of <code class="docutils literal notranslate"><span class="pre">Groups</span></code>. These groups all work just like a regular old
<code class="docutils literal notranslate"><span class="pre">Group</span></code>, but they also have added functionality (or slightly different
functionality). Here's a list of the <code class="docutils literal notranslate"><span class="pre">Group</span></code> classes included with the
sprite module.</p>
<blockquote>
<div><p><a class="reference internal" href="../ref/sprite.html#pygame.sprite.Group" title="pygame.sprite.Group"><code class="xref py py-class docutils literal notranslate"><span class="pre">Group</span></code></a></p>
<blockquote>
<div><p>This is the standard "no frills" group mainly explained above. Most of the
other <code class="docutils literal notranslate"><span class="pre">Groups</span></code> are derived from this one, but not all.</p>
</div></blockquote>
<p><a class="reference internal" href="../ref/sprite.html#pygame.sprite.GroupSingle" title="pygame.sprite.GroupSingle"><code class="xref py py-class docutils literal notranslate"><span class="pre">GroupSingle</span></code></a></p>
<blockquote>
<div><p>This works exactly like the regular <code class="docutils literal notranslate"><span class="pre">Group</span></code> class, but it only contains
the most recently added sprite. Therefore when you add a sprite to this group,
it "forgets" about any previous sprites it had. Therefore it always contains
only one or zero sprites.</p>
</div></blockquote>
<p><a class="reference internal" href="../ref/sprite.html#pygame.sprite.RenderPlain" title="pygame.sprite.RenderPlain"><code class="xref py py-class docutils literal notranslate"><span class="pre">RenderPlain</span></code></a></p>
<blockquote>
<div><p>This is a standard group derived from <code class="docutils literal notranslate"><span class="pre">Group</span></code>. It has a draw() method
that draws all the sprites it contains to the screen (or any <code class="docutils literal notranslate"><span class="pre">Surface</span></code>). For
this to work, it requires all sprites it contains to have a "image" and "rect"
attributes. It uses these to know what to blit, and where to blit it.</p>
</div></blockquote>
<p><a class="reference internal" href="../ref/sprite.html#pygame.sprite.RenderClear" title="pygame.sprite.RenderClear"><code class="xref py py-class docutils literal notranslate"><span class="pre">RenderClear</span></code></a></p>
<blockquote>
<div><p>This is derived from the <code class="docutils literal notranslate"><span class="pre">RenderPlain</span></code> group, and adds a method named
<code class="docutils literal notranslate"><span class="pre">clear()</span></code>. This will erase the previous position of all drawn sprites. It
uses a background image to fill in the areas where the sprite were. It is smart
enough to handle deleted sprites and properly clear them from the screen when
the <code class="docutils literal notranslate"><span class="pre">clear()</span></code> method is called.</p>
</div></blockquote>
<p><a class="reference internal" href="../ref/sprite.html#pygame.sprite.RenderUpdates" title="pygame.sprite.RenderUpdates"><code class="xref py py-class docutils literal notranslate"><span class="pre">RenderUpdates</span></code></a></p>
<blockquote>
<div><p>This is the Cadillac of rendering <code class="docutils literal notranslate"><span class="pre">Groups</span></code>. It is inherited from
<code class="docutils literal notranslate"><span class="pre">RenderClear</span></code>, but changes the <code class="docutils literal notranslate"><span class="pre">draw()</span></code> method to also return a list of
pygame <code class="docutils literal notranslate"><span class="pre">Rects</span></code>, which represent all the areas on screen that have been
changed.</p>
</div></blockquote>
</div></blockquote>
<p>That is the list of different groups available We'll discuss more about these
rendering groups in the next section. There's nothing stopping you from
creating your own Group classes as well. They are just python code, so you can
inherit from one of these and add/change whatever you want. In the future I
hope we can add a couple more <code class="docutils literal notranslate"><span class="pre">Groups</span></code> to this list. A <code class="docutils literal notranslate"><span class="pre">GroupMulti</span></code> which
is like the <code class="docutils literal notranslate"><span class="pre">GroupSingle</span></code>, but can hold up to a given number of sprites (in
some sort of circular buffer?). Also a super-render group that can clear the
position of the old sprites without needing a background image to do it (by
grabbing a copy of the screen before blitting). Who knows really, but in the
future we can add more useful classes to this list.</p>
</section>
<section id="the-rendering-groups">
<h3>The Rendering Groups<a class="headerlink" href="#the-rendering-groups" title="Permalink to this headline">¶</a></h3>
<p>From above we can see there are three different rendering groups. We could
probably just get away with the <code class="docutils literal notranslate"><span class="pre">RenderUpdates</span></code> one, but it adds overhead not
really needed for something like a scrolling game. So we have a couple tools
here, pick the right one for the right job.</p>
<p>For a scrolling type game, where the background completely changes every frame,
we obviously don't need to worry about python's update rectangles in the call
to <code class="docutils literal notranslate"><span class="pre">display.update()</span></code>. You should definitely go with the <code class="docutils literal notranslate"><span class="pre">RenderPlain</span></code>
group here to manage your rendering.</p>
<p>For games where the background is more stationary, you definitely don't want
pygame updating the entire screen (since it doesn't need to). This type of game
usually involves erasing the old position of each object, then drawing it in a
new place for each frame. This way we are only changing what is necessary.
Most of the time you will just want to use the <code class="docutils literal notranslate"><span class="pre">RenderUpdates</span></code> class here.
Since you will also want to pass this list of changes to the
<code class="docutils literal notranslate"><span class="pre">display.update()</span></code> function.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">RenderUpdates</span></code> class also does a good job at minimizing overlapping
areas in the list of updated rectangles. If the previous position and current
position of an object overlap, it will merge them into a single rectangle.
Combined with the fact that it properly handles deleted objects, this is
one powerful <code class="docutils literal notranslate"><span class="pre">Group</span></code> class. If you've written a game that manages the changed
rectangles for the objects in a game, you know this the cause for a lot of
messy code in your game. Especially once you start to throw in objects that can
be deleted at any time. All this work is reduced to a <code class="docutils literal notranslate"><span class="pre">clear()</span></code> and
<code class="docutils literal notranslate"><span class="pre">draw()</span></code> method with this monster class. Plus with the overlap checking, it
is likely faster than when you did it manually.</p>
<p>Also note that there's nothing stopping you from mixing and matching these
render groups in your game. You should definitely use multiple rendering groups
when you want to do layering with your sprites. Also if the screen is split
into multiple sections, perhaps each section of the screen should use an
appropriate render group?</p>
</section>
<section id="collision-detection">
<h3>Collision Detection<a class="headerlink" href="#collision-detection" title="Permalink to this headline">¶</a></h3>
<p>The sprite module also comes with two very generic collision detection
functions. For more complex games, these really won't work for you, but you
can easily grab the source code for them, and modify them as needed.</p>
<p>Here's a summary of what they are, and what they do.</p>
<blockquote>
<div><p><a class="reference internal" href="../ref/sprite.html#pygame.sprite.spritecollide" title="pygame.sprite.spritecollide"><code class="xref py py-func docutils literal notranslate"><span class="pre">spritecollide(sprite,</span> <span class="pre">group,</span> <span class="pre">dokill)</span> <span class="pre">-></span> <span class="pre">list</span></code></a></p>
<blockquote>
<div><p>This checks for collisions between a single sprite and the sprites in a group.
It requires a "rect" attribute for all the sprites used. It returns a list of
all the sprites that overlap with the first sprite. The "dokill" argument is a
boolean argument. If it is true, the function will call the <code class="docutils literal notranslate"><span class="pre">kill()</span></code> method
on all the sprites. This means the last reference to each sprite is probably in
the returned list. Once the list goes away so do the sprites. A quick example
of using this in a loop</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">bomb</span> <span class="ow">in</span> <span class="n">sprite</span><span class="o">.</span><span class="n">spritecollide</span><span class="p">(</span><span class="n">player</span><span class="p">,</span> <span class="n">bombs</span><span class="p">,</span> <span class="mi">1</span><span class="p">):</span>
<span class="gp">... </span> <span class="n">boom_sound</span><span class="o">.</span><span class="n">play</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">Explosion</span><span class="p">(</span><span class="n">bomb</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
</pre></div>
</div>
<p>This finds all the sprites in the "bomb" group that collide with the player.
Because of the "dokill" argument it deletes all the crashed bombs. For each
bomb that did collide, it plays a "boom" sound effect, and creates a new
<code class="docutils literal notranslate"><span class="pre">Explosion</span></code> where the bomb was. (Note, the <code class="docutils literal notranslate"><span class="pre">Explosion</span></code> class here knows to
add each instance to the appropriate class, so we don't need to store it in a
variable, that last line might feel a little "funny" to you python programmers.)</p>
</div></blockquote>
<p><a class="reference internal" href="../ref/sprite.html#pygame.sprite.groupcollide" title="pygame.sprite.groupcollide"><code class="xref py py-func docutils literal notranslate"><span class="pre">groupcollide(group1,</span> <span class="pre">group2,</span> <span class="pre">dokill1,</span> <span class="pre">dokill2)</span> <span class="pre">-></span> <span class="pre">dictionary</span></code></a></p>
<blockquote>
<div><p>This is similar to the <code class="docutils literal notranslate"><span class="pre">spritecollide</span></code> function, but a little more complex.
It checks for collisions for all the sprites in one group, to the sprites in
another. There is a <code class="docutils literal notranslate"><span class="pre">dokill</span></code> argument for the sprites in each list. When
<code class="docutils literal notranslate"><span class="pre">dokill1</span></code> is true, the colliding sprites in <code class="docutils literal notranslate"><span class="pre">group1</span></code> will be <code class="docutils literal notranslate"><span class="pre">kill()``ed.</span>
<span class="pre">When</span> <span class="pre">``dokill2</span></code> is true, we get the same results for <code class="docutils literal notranslate"><span class="pre">group2</span></code>. The
dictionary it returns works like this; each key in the dictionary is a sprite
from <code class="docutils literal notranslate"><span class="pre">group1</span></code> that had a collision. The value for that key is a list of the
sprites that it collided with. Perhaps another quick code sample explains it
best</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">alien</span> <span class="ow">in</span> <span class="n">sprite</span><span class="o">.</span><span class="n">groupcollide</span><span class="p">(</span><span class="n">aliens</span><span class="p">,</span> <span class="n">shots</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">boom_sound</span><span class="o">.</span><span class="n">play</span><span class="p">()</span>
<span class="gp">... </span> <span class="n">Explosion</span><span class="p">(</span><span class="n">alien</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="gp">... </span> <span class="n">kills</span> <span class="o">+=</span> <span class="mi">1</span>
</pre></div>
</div>
<p>This code checks for the collisions between player bullets and all the aliens
they might intersect. In this case we only loop over the dictionary keys, but
we could loop over the <code class="docutils literal notranslate"><span class="pre">values()</span></code> or <code class="docutils literal notranslate"><span class="pre">items()</span></code> if we wanted to do something
to the specific shots that collided with aliens. If we did loop over the
<code class="docutils literal notranslate"><span class="pre">values()</span></code> we would be looping through lists that contain sprites. The same
sprite may even appear more than once in these different loops, since the same
"shot" could have collided against multiple "aliens".</p>
</div></blockquote>
</div></blockquote>
<p>Those are the basic collision functions that come with pygame. It should be
easy to roll your own that perhaps use something different than the "rect"
attribute. Or maybe try to fine-tweak your code a little more by directly
effecting the collision object, instead of building a list of the collision?
The code in the sprite collision functions is very optimized, but you could
speed it up slightly by taking out some functionality you don't need.</p>
</section>
<section id="common-problems">
<h3>Common Problems<a class="headerlink" href="#common-problems" title="Permalink to this headline">¶</a></h3>
<p>Currently there is one main problem that catches new users. When you derive
your new sprite class with the Sprite base, you <strong>must</strong> call the
<code class="docutils literal notranslate"><span class="pre">Sprite.__init__()</span></code> method from your own class <code class="docutils literal notranslate"><span class="pre">__init__()</span></code> method. If you
forget to call the <code class="docutils literal notranslate"><span class="pre">Sprite.__init__()</span></code> method, you get a cryptic error, like
this</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ne">AttributeError</span><span class="p">:</span> <span class="s1">'mysprite'</span> <span class="n">instance</span> <span class="n">has</span> <span class="n">no</span> <span class="n">attribute</span> <span class="s1">'_Sprite__g'</span>
</pre></div>
</div>
</section>
<section id="extending-your-own-classes-advanced">
<h3>Extending Your Own Classes <em>(Advanced)</em><a class="headerlink" href="#extending-your-own-classes-advanced" title="Permalink to this headline">¶</a></h3>
<p>Because of speed concerns, the current <code class="docutils literal notranslate"><span class="pre">Group</span></code> classes try to only do exactly
what they need, and not handle a lot of general situations. If you decide you
need extra features, you may want to create your own <code class="docutils literal notranslate"><span class="pre">Group</span></code> class.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> and <code class="docutils literal notranslate"><span class="pre">Group</span></code> classes were designed to be extended, so feel free
to create your own <code class="docutils literal notranslate"><span class="pre">Group</span></code> classes to do specialized things. The best place
to start is probably the actual python source code for the sprite module.
Looking at the current <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> groups should be enough example on how to
create your own.</p>
<p>For example, here is the source code for a rendering <code class="docutils literal notranslate"><span class="pre">Group</span></code> that calls a
<code class="docutils literal notranslate"><span class="pre">render()</span></code> method for each sprite, instead of just blitting an "image"
variable from it. Since we want it to also handle updated areas, we will start
with a copy of the original <code class="docutils literal notranslate"><span class="pre">RenderUpdates</span></code> group, here is the code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">RenderUpdatesDraw</span><span class="p">(</span><span class="n">RenderClear</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""call sprite.draw(screen) to render sprites"""</span>
<span class="k">def</span> <span class="nf">draw</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">surface</span><span class="p">):</span>
<span class="n">dirty</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lostsprites</span>
<span class="bp">self</span><span class="o">.</span><span class="n">lostsprites</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">s</span><span class="p">,</span> <span class="n">r</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">spritedict</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
<span class="n">newrect</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">draw</span><span class="p">(</span><span class="n">screen</span><span class="p">)</span> <span class="c1">#Here's the big change</span>
<span class="k">if</span> <span class="n">r</span> <span class="ow">is</span> <span class="mi">0</span><span class="p">:</span>
<span class="n">dirty</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">newrect</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">dirty</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">newrect</span><span class="o">.</span><span class="n">union</span><span class="p">(</span><span class="n">r</span><span class="p">))</span>
<span class="bp">self</span><span class="o">.</span><span class="n">spritedict</span><span class="p">[</span><span class="n">s</span><span class="p">]</span> <span class="o">=</span> <span class="n">newrect</span>
<span class="k">return</span> <span class="n">dirty</span>
</pre></div>
</div>
<p>Following is more information on how you could create your own <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> and
<code class="docutils literal notranslate"><span class="pre">Group</span></code> objects from scratch.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> objects only "require" two methods. "add_internal()" and
"remove_internal()". These are called by the <code class="docutils literal notranslate"><span class="pre">Group</span></code> classes when they are
removing a sprite from themselves. The <code class="docutils literal notranslate"><span class="pre">add_internal()</span></code> and
<code class="docutils literal notranslate"><span class="pre">remove_internal()</span></code> have a single argument which is a group. Your <code class="docutils literal notranslate"><span class="pre">Sprite</span></code>
will need some way to also keep track of the <code class="docutils literal notranslate"><span class="pre">Groups</span></code> it belongs to. You will
likely want to try to match the other methods and arguments to the real
<code class="docutils literal notranslate"><span class="pre">Sprite</span></code> class, but if you're not going to use those methods, you sure don't
need them.</p>
<p>It is almost the same requirements for creating your own <code class="docutils literal notranslate"><span class="pre">Group</span></code>. In fact, if
you look at the source you'll see the <code class="docutils literal notranslate"><span class="pre">GroupSingle</span></code> isn't derived from the
<code class="docutils literal notranslate"><span class="pre">Group</span></code> class, it just implements the same methods so you can't really tell
the difference. Again you need an "add_internal()" and "remove_internal()"
method that the sprites call when they want to belong or remove themselves from
the group. The <code class="docutils literal notranslate"><span class="pre">add_internal()</span></code> and <code class="docutils literal notranslate"><span class="pre">remove_internal()</span></code> have a single
argument which is a sprite. The only other requirement for the <code class="docutils literal notranslate"><span class="pre">Group</span></code>
classes is they have a dummy attribute named "_spritegroup". It doesn't matter
what the value is, as long as the attribute is present. The Sprite classes can
look for this attribute to determine the difference between a "group" and any
ordinary python container. (This is important, because several sprite methods
can take an argument of a single group, or a sequence of groups. Since they
both look similar, this is the most flexible way to "see" the difference.)</p>
<p>You should go through the code for the sprite module. While the code is a bit
"tuned", it's got enough comments to help you follow along. There's even a
TODO section in the source if you feel like contributing.</p>
</section>
</section>
</section>
<br /><br />
<hr />
<a href="https://github.com/pygame/pygame/edit/main/docs/reST/tut\SpriteIntro.rst" rel="nofollow">Edit on GitHub</a>
<div class="clearer"></div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="SurfarrayIntro.html" title="Pygame Tutorials - Surfarray Introduction"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="PygameIntro.html" title="Pygame Intro"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">pygame v2.5.2 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Pygame Tutorials - Sprite Module Introduction</a></li>
<script type="text/javascript" src="https://www.pygame.org/comment/jquery.plugin.docscomments.js"></script>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2000-2023, pygame developers.
</div>
</body>
</html>