Sprites¶

Sprites are game objects.

To use a sprite you use BaseScene.add to add it to a scene. When contained in an active scene, the engine will call the various event handlers on the sprite.

When defining your own custom sprites, we suggest you start with Sprite. By subclassing Sprite, you get a number of features automatically. You then define your event handlers as methods on your new class to produce behaviors.

All sprites in ppb are built from composition via mixins or subclassing via traditional Python inheritance.

If you don’t need the built in features of Sprite see BaseSprite.

Concrete Sprites¶

Concrete sprites are a combination of BaseSprite and various mixins. They implement a number of useful features for game development and should be the primary classes you subclass when building game objects.

class ppb.Sprite(**props)[source]¶

The default Sprite class.

Sprite defines no additional methods or attributes, but is made up of BaseSprite with the mixins RotatableMixin, RenderableMixin, and SquareShapeMixin.

For most use cases, this is probably the class you want to subclass to make your game objects.

If you need rectangular sprites instead of squares, see RectangleSprite.

BaseSprite does not accept any positional arguments, and uses keyword arguments to set arbitrary state to the BaseSprite instance. This allows rapid prototyping.

Example:

sprite = BaseSprite(speed=6)
print(sprite.speed)

This sample will print the numeral 6.

You may add any arbitrary data values in this fashion. Alternatively, it is considered best practice to subclass BaseSprite and set the default values of any required attributes as class attributes.

Example:

class Rocket(ppb.sprites.BaseSprite):
   velocity = Vector(0, 1)

   def on_update(self, update_event, signal):
       self.position += self.velocity * update_event.time_delta

add(child: Hashable, tags: Iterable[T_co] = ()) → None¶: Shorthand for Children.add()

bottom¶

The y-axis position of the bottom of the object.

Can be set to a number.

bottom_left¶

The coordinates of the bottom left corner of the object.

Can be set to a ppb_vector.Vector.

bottom_middle¶

The coordinates of the midpoint of the bottom of the object.

Can be set to a ppb_vector.Vector.

center¶

The coordinates of the center point of the object. Equivalent to the position.

Can be set to a ppb_vector.Vector.

facing¶

The direction the “front” is facing.

Can be set to an arbitrary facing by providing a facing vector.

get(*, kind: Type[CT_co] = None, tag: Hashable = None, **kwargs) → Iterator[T_co]¶: Shorthand for Children.get()

height¶

The height of the sprite.

Setting the height of the sprite changes the size and width().

kinds¶: Shorthand for Children.kinds()

Deprecated since version 0.10: Use .children.kinds() instead.

left¶

The x-axis position of the left side of the object.

Can be set to a number.

left_middle¶

The coordinates of the midpoint of the left side of the object.

Can be set to a ppb_vector.Vector.

remove(child: Hashable) → None¶: Shorthand for Children.remove()

right¶

The x-axis position of the right side of the object.

Can be set to a number.

right_middle¶

The coordinates of the midpoint of the right side of the object.

Can be set to a ppb_vector.Vector.

rotate(degrees)¶: Rotate the sprite by a given angle (in degrees).

rotation¶: The amount the sprite is rotated, in degrees

tags¶: Shorthand for Children.tags()

Deprecated since version 0.10: Use .children.tags() instead.

top¶

The y-axis position of the top of the object.

Can be set to a number.

top_left¶

The coordinates of the top left corner of the object.

Can be set to a ppb_vector.Vector.

top_middle¶

The coordinates of the midpoint of the top of the object.

Can be set to a ppb_vector.Vector.

top_right¶

The coordinates of the top right corner of the object.

Can be set to a ppb_vector.Vector.

width¶

The width of the sprite.

Setting the width of the sprite changes size and height().

class ppb.RectangleSprite(**props)[source]¶

A rectangle sprite.

Similarly to Sprite, RectangleSprite does not introduce any new methods or attributes. It’s made up of BaseSprite with the mixins RotatableMixin, RenderableMixin, and RectangleShapeMixin.

BaseSprite does not accept any positional arguments, and uses keyword arguments to set arbitrary state to the BaseSprite instance. This allows rapid prototyping.

Example:

sprite = BaseSprite(speed=6)
print(sprite.speed)

This sample will print the numeral 6.

You may add any arbitrary data values in this fashion. Alternatively, it is considered best practice to subclass BaseSprite and set the default values of any required attributes as class attributes.

Example:

class Rocket(ppb.sprites.BaseSprite):
   velocity = Vector(0, 1)

   def on_update(self, update_event, signal):
       self.position += self.velocity * update_event.time_delta

add(child: Hashable, tags: Iterable[T_co] = ()) → None¶: Shorthand for Children.add()

bottom¶

The y-axis position of the bottom of the object.

Can be set to a number.

bottom_left¶

The coordinates of the bottom left corner of the object.

Can be set to a ppb_vector.Vector.

bottom_middle¶

The coordinates of the midpoint of the bottom of the object.

Can be set to a ppb_vector.Vector.

center¶

The coordinates of the center point of the object. Equivalent to the position.

Can be set to a ppb_vector.Vector.

facing¶

The direction the “front” is facing.

Can be set to an arbitrary facing by providing a facing vector.

get(*, kind: Type[CT_co] = None, tag: Hashable = None, **kwargs) → Iterator[T_co]¶: Shorthand for Children.get()

kinds¶: Shorthand for Children.kinds()

Deprecated since version 0.10: Use .children.kinds() instead.

left¶

The x-axis position of the left side of the object.

Can be set to a number.

left_middle¶

The coordinates of the midpoint of the left side of the object.

Can be set to a ppb_vector.Vector.

remove(child: Hashable) → None¶: Shorthand for Children.remove()

right¶

The x-axis position of the right side of the object.

Can be set to a number.

right_middle¶

The coordinates of the midpoint of the right side of the object.

Can be set to a ppb_vector.Vector.

rotate(degrees)¶: Rotate the sprite by a given angle (in degrees).

rotation¶: The amount the sprite is rotated, in degrees

tags¶: Shorthand for Children.tags()

Deprecated since version 0.10: Use .children.tags() instead.

top¶

The y-axis position of the top of the object.

Can be set to a number.

top_left¶

The coordinates of the top left corner of the object.

Can be set to a ppb_vector.Vector.

top_middle¶

The coordinates of the midpoint of the top of the object.

Can be set to a ppb_vector.Vector.

top_right¶

The coordinates of the top right corner of the object.

Can be set to a ppb_vector.Vector.

Feature Mixins¶

These mixins are the various features already available in Sprite. Here for complete documentation.

class ppb.sprites.RenderableMixin[source]¶

A class implementing the API expected by ppb.systems.renderer.Renderer.

The render expects a width and height (see RectangleMixin) and will skip rendering if a sprite has no shape. You can use RectangleMixin, SquareMixin, or set the values yourself.

Additionally, if image is None, the sprite will not be rendered. If you just want a basic shape to be rendered, see ppb.assets.

image = Ellipsis¶: (ppb.Image): The image asset

class ppb.sprites.RotatableMixin[source]¶

A rotation mixin. Can be included with sprites.

Warning

rotation does not affect underlying shape (the corners are still in the same place), it only rotates the sprites image and provides a facing.

basis = Vector(0.0, -1.0)¶: The baseline vector, representing the “front” of the sprite

facing¶

The direction the “front” is facing.

Can be set to an arbitrary facing by providing a facing vector.

rotate(degrees)[source]¶: Rotate the sprite by a given angle (in degrees).

rotation¶: The amount the sprite is rotated, in degrees

class ppb.sprites.RectangleShapeMixin[source]¶

A Mixin that provides a rectangular area to sprites.

Classes derived from RectangleShapeMixin default to the same size and shape as all ppb Sprites: A 1 game unit by 1 game unit square. Just set the width and height in your constructor (Or as class attributes) to change this default.

Note

The concrete class using RectangleShapeMixin must have a position attribute.

bottom¶

The y-axis position of the bottom of the object.

Can be set to a number.

bottom_left¶

The coordinates of the bottom left corner of the object.

Can be set to a ppb_vector.Vector.

bottom_middle¶

The coordinates of the midpoint of the bottom of the object.

Can be set to a ppb_vector.Vector.

center¶

The coordinates of the center point of the object. Equivalent to the position.

Can be set to a ppb_vector.Vector.

height = 1¶: The height of the sprite.

left¶

The x-axis position of the left side of the object.

Can be set to a number.

left_middle¶

The coordinates of the midpoint of the left side of the object.

Can be set to a ppb_vector.Vector.

right¶

The x-axis position of the right side of the object.

Can be set to a number.

right_middle¶

The coordinates of the midpoint of the right side of the object.

Can be set to a ppb_vector.Vector.

top¶

The y-axis position of the top of the object.

Can be set to a number.

top_left¶

The coordinates of the top left corner of the object.

Can be set to a ppb_vector.Vector.

top_middle¶

The coordinates of the midpoint of the top of the object.

Can be set to a ppb_vector.Vector.

top_right¶

The coordinates of the top right corner of the object.

Can be set to a ppb_vector.Vector.

width = 1¶: The width of the sprite.

class ppb.sprites.SquareShapeMixin[source]¶

A Mixin that provides a square area to sprites.

Extends the interface of RectangleShapeMixin by using the size attribute to determine width() and height(). Setting either width() or height() sets the size and maintains the square shape at the new size.

The default size of SquareShapeMixin is 1 game unit.

Please see RectangleShapeMixin for additional details.

height¶

The height of the sprite.

Setting the height of the sprite changes the size and width().

size = 1¶: The width and height of the object. Setting size changes the height() and width() of the sprite.

width¶

The width of the sprite.

Setting the width of the sprite changes size and height().

Base Classes¶

The base class of Sprite, use this if you need to change the low level expectations.

class ppb.sprites.BaseSprite(**props)[source]¶

The base Sprite class. All sprites should inherit from this (directly or indirectly).

The things that define a BaseSprite:

A position vector
A layer

BaseSprite provides an __init__() method that sets attributes based on kwargs to make rapid prototyping easier.

BaseSprite does not accept any positional arguments, and uses keyword arguments to set arbitrary state to the BaseSprite instance. This allows rapid prototyping.

Example:

sprite = BaseSprite(speed=6)
print(sprite.speed)

This sample will print the numeral 6.

You may add any arbitrary data values in this fashion. Alternatively, it is considered best practice to subclass BaseSprite and set the default values of any required attributes as class attributes.

Example:

class Rocket(ppb.sprites.BaseSprite):
   velocity = Vector(0, 1)

   def on_update(self, update_event, signal):
       self.position += self.velocity * update_event.time_delta

add(child: Hashable, tags: Iterable[T_co] = ()) → None¶: Shorthand for Children.add()

get(*, kind: Type[CT_co] = None, tag: Hashable = None, **kwargs) → Iterator[T_co]¶: Shorthand for Children.get()

kinds¶: Shorthand for Children.kinds()

Deprecated since version 0.10: Use .children.kinds() instead.

layer = 0¶: The layer a sprite exists on.

position = Vector(0.0, 0.0)¶: (ppb.Vector): Location of the sprite

remove(child: Hashable) → None¶: Shorthand for Children.remove()

tags¶: Shorthand for Children.tags()

Deprecated since version 0.10: Use .children.tags() instead.