Sprite
========

.. automodule:: sprite

Download the :download:`sprite.py<../src/sprite.py>` file to use the
module.

.. autoclass:: sprite.Sprite

Attributes
----------

.. autoinstanceattribute:: sprite.Sprite.x
   :annotation:

.. autoinstanceattribute:: sprite.Sprite.y
   :annotation:

.. autoinstanceattribute:: sprite.Sprite.image_name
   :annotation:

Read-only Attributes
--------------------

.. autoinstanceattribute:: sprite.Sprite.width
   :annotation:

.. autoinstanceattribute:: sprite.Sprite.height
   :annotation:

Methods
-------

.. automethod:: sprite.Sprite.uncollide

.. automethod:: sprite.Sprite.collides

Examples
--------

Here is an example of using the `collides` and `uncollide` methods to
prevent two sprites from overlapping::

    import graphics
    import sprite

    WINDOW_WIDTH = 640
    WINDOW_HEIGHT = 480
    IMAGE = "rectangle.gif"

    # Initialize window
    graphics.window_size(WINDOW_WIDTH, WINDOW_HEIGHT)
    graphics.window_title("Sprites")
    graphics.window_background_color("white")

    # Initialize player and platform sprites
    sprite_1 = sprite.Sprite(WINDOW_WIDTH / 2, WINDOW_HEIGHT / 2, IMAGE)
    sprite_2 = sprite.Sprite(WINDOW_WIDTH / 2, WINDOW_HEIGHT / 2, IMAGE)

    # Main loop
    while graphics.window_open():
        # Clear the screen
        graphics.clear()

        # Update sprite 1 so it is where the mouse is,
        # unless it overlaps with sprite 2
        if graphics.mouse_moved():
            sprite_1.x = graphics.mouse_x()
            sprite_1.y = graphics.mouse_y()
            if sprite_1.collides(sprite_2):
                sprite_1.uncollide(sprite_2)

        # Draw the scene
        graphics.draw_sprite(sprite_1)
        graphics.draw_sprite(sprite_2)
	
	# Wait 1/30 to slow the animation to 30 frames per second
	graphics.wait(0.033)


Here is an example that adds attributes to sprite objects to create a
platform game::

    import graphics
    import sprite
    import random

    WINDOW_WIDTH = 640
    WINDOW_HEIGHT = 480
    PLAYER_IMAGE = "player.gif"
    PLATFORM_IMAGE = "platform.gif"
    PLAYER_RUN_SPEED = 10
    PLAYER_JUMP_STRENGTH = 20
    GRAVITY_STRENGTH = 2

    # Initialize window
    graphics.window_size(WINDOW_WIDTH, WINDOW_HEIGHT)
    graphics.window_title("Platform Game")
    graphics.window_background_color("white")

    # Initialize player and platform sprites
    platform = sprite.Sprite(WINDOW_WIDTH / 2, WINDOW_HEIGHT, PLATFORM_IMAGE)
    player = sprite.Sprite(WINDOW_WIDTH / 2, 0, PLAYER_IMAGE)
    player.on_ground = False
    player.velocity_y = 0

    # Main loop
    while graphics.window_open():
        # Clear the screen
        graphics.clear()

        # Update the scene
        if graphics.key_down('Right'):
            player.x += PLAYER_RUN_SPEED
        if graphics.key_down('Left'):
            player.x -= PLAYER_RUN_SPEED
        if player.collides(platform) and not player.on_ground:
            player.uncollide(platform)
            player.on_ground = True
            player.velocity_y = 0
        if graphics.key_down('Up') and player.on_ground:
            player.on_ground = False
            player.velocity_y = -PLAYER_JUMP_STRENGTH
        if not player.on_ground:
            player.y += player.velocity_y
            player.velocity_y += GRAVITY_STRENGTH

        # Draw the scene
        graphics.draw_sprite(platform)
        graphics.draw_sprite(player)
	
	# Wait 1/30 to slow the animation to 30 frames per second
	graphics.wait(0.033)

Here is an example of animating many sprites using the sprite module::

    import graphics
    import sprite
    import random

    NUMBER_OF_BALLS = 700
    WINDOW_WIDTH = 640
    WINDOW_HEIGHT = 480
    BALL_IMAGE = "ball.gif"
    BALL_WIDTH, BALL_HEIGHT = graphics.image_size(BALL_IMAGE)
    BALL_RADIUS = BALL_WIDTH / 2
    MAX_Y = WINDOW_HEIGHT - BALL_RADIUS
    MAX_X = WINDOW_WIDTH - BALL_RADIUS
    MIN_Y = BALL_RADIUS
    MIN_X = BALL_RADIUS
    MIN_DELTA_X = -10
    MAX_DELTA_X = 10
    MIN_DELTA_Y = -10
    MAX_DELTA_Y = 10

    # Returns a sprite at a random location
    def init_sprite():
        ball_x = random.randint(MIN_X, MAX_X)
        ball_y = random.randint(MIN_Y, MAX_Y)
        ball_delta_x = random.randint(MIN_DELTA_X, MAX_DELTA_X)
        ball_delta_y = random.randint(MIN_DELTA_Y, MAX_DELTA_Y)
        ball_sprite = sprite.Sprite(ball_x, ball_y, BALL_IMAGE)
        ball_sprite.velocity_x = ball_delta_x
        ball_sprite.velocity_y = ball_delta_y
        return ball_sprite

    # Update the location of the sprite so that bounces around the screen
    def update_sprite(ball_sprite):
        ball_sprite.x += ball_sprite.velocity_x
        ball_sprite.y += ball_sprite.velocity_y
        if ball_sprite.x > WINDOW_WIDTH - BALL_RADIUS:
            ball_sprite.velocity_x *= -1
        if ball_sprite.x < BALL_RADIUS:
            ball_sprite.velocity_x *= -1
        if ball_sprite.y > WINDOW_HEIGHT - BALL_RADIUS:
            ball_sprite.velocity_y *= -1
        if ball_sprite.y < BALL_RADIUS:
            ball_sprite.velocity_y *= -1

    # Animate many sprites bouncing around the screen
    def main_loop():
        balls = [init_sprite() for _ in range(NUMBER_OF_BALLS)]
        graphics.window_size(WINDOW_WIDTH, WINDOW_HEIGHT)
        graphics.window_title("Bouncing Balls")
        graphics.window_background_color("white")
        while graphics.window_open():
            graphics.clear()
            for i in range(len(balls)):
                update_sprite(balls[i])
                graphics.draw_sprite(balls[i])
            graphics.draw_text("Bouncing", WINDOW_WIDTH // 2, WINDOW_HEIGHT // 2,
                               "blue", 42)
	
            # Wait 1/30 to slow the animation to 30 frames per second
	    graphics.wait(0.033)