Sprites

Sprites are game objects.

To use a sprite you use Scene.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: ppb.gomlib.GameObject, tags: Iterable = ()) None

Shorthand for Children.add()

property bottom: float

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

Can be set to a number.

property bottom_left: ppb_vector.Vector

The coordinates of the bottom left corner of the object.

Can be set to a ppb_vector.Vector.

property bottom_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property center: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

children: Children

The children of this object

property facing

The direction the “front” is facing.

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

get(*, kind: Optional[Type] = None, tag: Optional[Hashable] = None, **kwargs) Iterator

Shorthand for Children.get()

property height

The height of the sprite.

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

property left: float

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

Can be set to a number.

property left_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

remove(child: ppb.gomlib.GameObject) ppb.gomlib.GameObject

Shorthand for Children.remove()

property right: float

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

Can be set to a number.

property right_middle: ppb_vector.Vector

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

property top: float

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

Can be set to a number.

property top_left: ppb_vector.Vector

The coordinates of the top left corner of the object.

Can be set to a ppb_vector.Vector.

property top_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property top_right: ppb_vector.Vector

The coordinates of the top right corner of the object.

Can be set to a ppb_vector.Vector.

property 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: ppb.gomlib.GameObject, tags: Iterable = ()) None

Shorthand for Children.add()

property bottom: float

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

Can be set to a number.

property bottom_left: ppb_vector.Vector

The coordinates of the bottom left corner of the object.

Can be set to a ppb_vector.Vector.

property bottom_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property center: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

children: Children

The children of this object

property facing

The direction the “front” is facing.

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

get(*, kind: Optional[Type] = None, tag: Optional[Hashable] = None, **kwargs) Iterator

Shorthand for Children.get()

property left: float

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

Can be set to a number.

property left_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

remove(child: ppb.gomlib.GameObject) ppb.gomlib.GameObject

Shorthand for Children.remove()

property right: float

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

Can be set to a number.

property right_middle: ppb_vector.Vector

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

property top: float

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

Can be set to a number.

property top_left: ppb_vector.Vector

The coordinates of the top left corner of the object.

Can be set to a ppb_vector.Vector.

property top_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property top_right: ppb_vector.Vector

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

property 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).

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.

property bottom: float

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

Can be set to a number.

property bottom_left: ppb_vector.Vector

The coordinates of the bottom left corner of the object.

Can be set to a ppb_vector.Vector.

property bottom_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property center: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

height: int = 1

The height of the sprite.

property left: float

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

Can be set to a number.

property left_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property right: float

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

Can be set to a number.

property right_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property top: float

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

Can be set to a number.

property top_left: ppb_vector.Vector

The coordinates of the top left corner of the object.

Can be set to a ppb_vector.Vector.

property top_middle: ppb_vector.Vector

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

Can be set to a ppb_vector.Vector.

property top_right: ppb_vector.Vector

The coordinates of the top right corner of the object.

Can be set to a ppb_vector.Vector.

width: int = 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.

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

property 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: ppb.gomlib.GameObject, tags: Iterable = ()) None

Shorthand for Children.add()

children: Children

The children of this object

get(*, kind: Optional[Type] = None, tag: Optional[Hashable] = None, **kwargs) Iterator

Shorthand for Children.get()

layer: int = 0

The layer a sprite exists on.

position: ppb_vector.Vector = Vector(0.0, 0.0)

(ppb.Vector): Location of the sprite

remove(child: ppb.gomlib.GameObject) ppb.gomlib.GameObject

Shorthand for Children.remove()