Sprite Scenes
- 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
- 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 nameScene.from_tilemap()
, which creates a scene from aTileMap
already loaded from tiled dataFine-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.
- 🧙 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
- 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 withSpriteList
’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 theuse_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 ofuse_spatial_hash
passed to this method, it will use the default arguments for a newSpriteList
.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 ofuse_spatial_hash
passed to this method, it will use the default arguments for a newSpriteList
.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, aKeyError
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 subclassedSpriteList
.- 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 andFalse
for smooth scaling.blend_function – Use the specified OpenGL blend function while drawing the sprite list, such as
arcade.Window.ctx.BLEND_ADDITIVE
orarcade.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 eithername
orafter
contain a name not currently in the scene. This exception can be handled as aKeyError
.- 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 eithername
orbefore
contain a name not currently in the scene. This exception can be handled as aKeyError
.- Parameters:
name – The name of the SpriteList to move.
before – The name of the SpriteList to place it before.
- 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(delta_time: float, names: Iterable[str] | None = None, *args, **kwargs) 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, aKeyError
will be raised.- Parameters:
delta_time – The time step to update by in seconds.
names – Which layers & what order to update them in.
*args – Additional positional arguments propagated down to sprites
**kwargs – Additional keyword arguments propagated down to sprites
- update_animation(delta_time: float, names: Iterable[str] | None = None, *args, **kwargs) 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, aKeyError
will be raised.- Parameters:
delta_time – The time step to update by in seconds.
names – Which layers & what order to update them in.
*args – Additional positional arguments propagated down to sprites
**kwargs – Additional keyword arguments propagated down to sprites