Sprite Scenes#

class arcade.Scene[source]#

Bases:

Stores SpriteList instances as named layers, allowing bulk updates & drawing.

In addition to helping you update or draw multiple sprite lists at once, this class also provides the following convenience methods:

  • add_sprite(), which adds sprites to layers by name

  • Scene.from_tilemap(), which creates a scene from a TileMap already loaded from tiled data

  • Fine-grained convenience methods for adding, deleting, and reordering sprite lists

  • Flexible but slow general convenience methods

  • Flexible but slow support for the in & del Python keywords.

For another example of how to use this class, see Step 3 - Many Sprites with SpriteList.

🧙 bool(self) → bool[source]#

Returns whether or not _sprite_lists contains anything

🧙 item: str | SpriteList in self → bool[source]#

True when item is in _sprite_lists or is a value in _name_mapping

🧙 del self[sprite_list: int | str | SpriteList] → None[source]#

Remove a sprite list from this scene by its index, name, or instance value.

Tip

Use a more specific method when speed is important!

This method uses isinstance(), which will slow down your program if used frequently!

Consider the following alternatives:

Parameters:

sprite_list – The index, name, or SpriteList instance to remove from this scene.

🧙 self[key: str] → SpriteList[source]#

Retrieve a sprite list by name.

This is here for ease of use to make sub-scripting the scene object directly to retrieve a SpriteList possible.

Parameters:

key – The name of the sprite list to retrieve

🧙 len(self) → int[source]#

Return the number of sprite lists in this scene.

add_sprite(name: str, sprite: Sprite) → None[source]#

Add a Sprite to the SpriteList with the specified name.

If there is no SpriteList for the given name, one will be created with SpriteList’s default arguments and added to the end (top) of the scene’s current draw order.

To fully customize the SpriteList’s options, you should create it directly and add it to the scene with one of the following:

Parameters:

  • name – The name of the sprite list to add to or create.

  • sprite – The sprite to add.

add_sprite_list(name: str, use_spatial_hash: bool = False, sprite_list: SpriteList | None = None) → None[source]#

Add a SpriteList to the scene with the specified name.

This will add a new SpriteList as a layer above the others in the scene.

If no SpriteList is supplied via the sprite_list parameter then a new one will be created, and the use_spatial_hash parameter will be respected for that creation.

Parameters:

  • name – The name to give the new layer.

  • use_spatial_hash – If creating a new sprite list, whether to enable spatial hashing on it.

  • sprite_list – Use a specific sprite list rather than creating a new one.

add_sprite_list_after(name: str, after: str, use_spatial_hash: bool = False, sprite_list: SpriteList | None = None) → None[source]#

Add a SpriteList to the scene with the specified name after a specific SpriteList.

If no sprite list is supplied via the sprite_list parameter, then a new one will be created. Aside from the value of use_spatial_hash passed to this method, it will use the default arguments for a new SpriteList.

The added sprite list will be drawn above the sprite list named in after.

Parameters:

  • name – The name to give the layer.

  • after – The name of the layer to place the new one after.

  • use_spatial_hash – If creating a new sprite list, selects whether to enable spatial hashing.

  • sprite_list – If a sprite list is passed via this argument, it will be used instead of creating a new one.

add_sprite_list_before(name: str, before: str, use_spatial_hash: bool = False, sprite_list: SpriteList | None = None) → None[source]#

Add a sprite list to the scene with the specified name before another SpriteList.

If no sprite list is supplied via the sprite_list parameter, then a new one will be created. Aside from the value of use_spatial_hash passed to this method, it will use the default arguments for a new SpriteList.

The added sprite list will be drawn under the sprite list named in before.

Parameters:

  • name – The name to give the new layer.

  • before – The name of the layer to place the new one before.

  • use_spatial_hash – If creating a new sprite list, selects whether to enable spatial hashing.

  • sprite_list – If a sprite list is passed via this argument, it will be used instead of creating a new one.

draw(names: Iterable[str] | None = None, filter: Tuple[int, int] | None = None, pixelated: bool = False, blend_function: Tuple[int, int] | Tuple[int, int, int, int] | None = None, **kwargs) → None[source]#

Call draw() on the scene’s sprite lists.

By default, this method calls draw() on each sprite list in the scene in the default draw order.

You can limit and reorder the draw calls with the names argument by passing a list of names in the scene. The sprite lists will be drawn in the order of the passed iterable. If a name is not in the scene, a KeyError will be raised.

The other named keyword arguments are the same as those of SpriteList.draw(). The **kwargs option is for advanced users who have subclassed SpriteList.

Parameters:

  • names – Which layers to draw & what order to draw them in.

  • filter – Optional parameter to set OpenGL filter, such as gl.GL_NEAREST to avoid smoothing.

  • pixelated – True for pixel art and False for smooth scaling.

  • blend_function – Use the specified OpenGL blend function while drawing the sprite list, such as arcade.Window.ctx.BLEND_ADDITIVE or arcade.Window.ctx.BLEND_DEFAULT.

draw_hit_boxes(color: Tuple[int, int, int, int] = (0, 0, 0, 255), line_thickness: float = 1.0, names: Iterable[str] | None = None) → None[source]#

Draw debug hit box outlines for sprites in the scene’s layers.

If names is a valid iterable of layer names in the scene, then hit boxes will be drawn for the specified layers in the order of the passed iterable.

If names is not provided, then every layer’s hit boxes will be drawn in the order specified.

Parameters:

  • color – The RGBA color to use to draw the hit boxes with.

  • line_thickness – How many pixels thick the hit box outlines should be

  • names – Which layers & what order to draw their hit boxes in.

classmethod from_tilemap(tilemap: TileMap) → Scene[source]#

Create a new Scene from a TileMap object.

The SpriteLists will use the layer names and ordering as defined in the Tiled file.

Parameters:

tilemap – The TileMap object to create the scene from.

get_sprite_list(name: str) → SpriteList[source]#

Retrieve a sprite list by name.

It is also possible to access sprite lists the following ways:

  • scene_instance[name]

  • directly accessing scene_instance._name_mapping, although this will get flagged by linters as bad style.

Parameters:

name – The name of the sprite list to retrieve.

move_sprite_list_after(name: str, after: str) → None[source]#

Move a named SpriteList in the scene to be after another SpriteList in the scene.

A SceneKeyError will be raised if either name or after contain a name not currently in the scene. This exception can be handled as a KeyError.

Parameters:

  • name – The name of the SpriteList to move.

  • after – The name of the SpriteList to place it after.

move_sprite_list_before(name: str, before: str) → None[source]#

Move a named SpriteList in the scene to be before another SpriteList in the scene.

A SceneKeyError will be raised if either name or before contain a name not currently in the scene. This exception can be handled as a KeyError.

Parameters:

  • name – The name of the SpriteList to move.

  • before – The name of the SpriteList to place it before.

on_update(delta_time: float = 0.016666666666666666, names: Iterable[str] | None = None) → None[source]#

Call on_update() on the scene’s sprite lists.

By default, this method calls on_update() on the scene’s sprite lists in the default draw order.

You can limit and reorder the updates with the names argument by passing a list of names in the scene. The sprite lists will be drawn in the order of the passed iterable. If a name is not in the scene, a KeyError will be raised.

Parameters:

  • delta_time – The time step to update by in seconds.

  • names – Which layers & what order to update them in.

remove_sprite_list_by_index(index: int) → None[source]#

Remove a layer from the scene by its index in the draw order.

Parameters:

index – The index of the sprite list to remove.

remove_sprite_list_by_name(name: str) → None[source]#

Remove a layer from the scene by its name.

A KeyError will be raised if the SpriteList is not in the scene.

Parameters:

name – The name of the sprite list to remove.

remove_sprite_list_by_object(sprite_list: SpriteList) → None[source]#

Remove the passed SpriteList instance from the Scene.

A ValueError will be raised if the passed sprite list is not in the scene.

Parameters:

sprite_list – The sprite list to remove.

update(names: Iterable[str] | None = None) → None[source]#

Call update() on the scene’s sprite lists.

By default, this method calls update() on the scene’s sprite lists in the default draw order.

You can limit and reorder the updates with the names argument by passing a list of names in the scene. The sprite lists will be drawn in the order of the passed iterable. If a name is not in the scene, a KeyError will be raised.

Parameters:

names – Which layers & what order to update them in.

update_animation(delta_time: float, names: Iterable[str] | None = None) → None[source]#

Call update_animation() on the scene’s sprite lists.

By default, this method calls update_animation() on each sprite list in the scene in the default draw order.

You can limit and reorder the updates with the names argument by passing a list of names in the scene. The sprite lists will be drawn in the order of the passed iterable. If a name is not in the scene, a KeyError will be raised.

Parameters:

  • delta_time – The time step to update by in seconds.

  • names – Which layers & what order to update them in.

class arcade.SceneKeyError(name: str)[source]#

Bases: KeyError

Raised when a py:class:.Scene cannot find a layer for a specified name.

It is a subclass of KeyError, and you can handle it as one if you wish:

try:
    # this will raise a SceneKeyError
    scene_instance.add_sprite("missing_layer_name", arcade.SpriteSolidColor(10,10))

# We can handle it as a KeyError because it is a subclass of it
except KeyError as e:
    print("Your error handling should go here")

The main purpose of this class is to help arcade’s developers keep error messages consistent.

Parameters:

name – the name of the missing SpriteList