Sprite Lists
Contents
arcade.SpriteList
- class arcade.SpriteList(use_spatial_hash=None, spatial_hash_cell_size=128, is_static=False, atlas: TextureAtlas = None, capacity: int = 100, lazy: bool = False, visible: bool = True)[source]
The purpose of the spriteList is to batch draw a list of sprites. Drawing single sprites will not get you anywhere performance wise as the number of sprites in your project increases. The spritelist contains many low level optimizations taking advantage of your graphics processor. To put things into perspective, a spritelist can contain tens of thousands of sprites without any issues. Sprites outside the viewport/window will not be rendered.
If the spriteslist are going to be used for collision it’s a good idea to enable spatial hashing. Especially if no sprites are moving. This will make collision checking a lot faster. In technical terms collision checking is
O(1)
with spatial hashing enabled andO(N)
without. However, if you have a list of moving sprites the cost of updating the spatial hash when they are moved can be greater than what you save with spatial collision checks. This needs to be profiled on a case by case basis.For the advanced options check the advanced section in the arcade documentation.
- Parameters
use_spatial_hash (bool) – If set to True, this will make moving a sprite in the SpriteList slower, but it will speed up collision detection with items in the SpriteList. Great for doing collision detection with static walls/platforms.
spatial_hash_cell_size (int) – The cell size of the spatial hash (default: 128)
is_static (bool) – DEPRECATED. This parameter has no effect.
atlas (TextureAtlas) – (Advanced) The texture atlas for this sprite list. If no atlas is supplied the global/default one will be used.
capacity (int) – (Advanced) The initial capacity of the internal buffer. It’s a suggestion for the maximum amount of sprites this list can hold. Can normally be left with default value.
lazy (bool) – (Advanced) Enabling lazy spritelists ensures no internal OpenGL resources are created until the first draw call or
initialize()
is called. This can be useful when making spritelists in threads because only the main thread is allowed to interact with OpenGL.visible (bool) – Setting this to False will cause the SpriteList to not be drawn. When draw is called, the method will just return without drawing.
- append(sprite: arcade.sprite_list.sprite_list._SpriteType)[source]
Add a new sprite to the list.
- Parameters
sprite (Sprite) – Sprite to add to the list.
- property atlas: TextureAtlas
Get the texture atlas for this sprite list
- draw(*, filter=None, pixelated=None, blend_function=None)[source]
Draw this list of sprites.
- Parameters
filter – Optional parameter to set OpenGL filter, such as gl.GL_NEAREST to avoid smoothing.
pixelated –
True
for pixelated andFalse
for smooth interpolation. Shortcut for setting filter=GL_NEAREST.blend_function – Optional parameter to set the OpenGL blend function used for drawing the sprite list, such as ‘arcade.Window.ctx.BLEND_ADDITIVE’ or ‘arcade.Window.ctx.BLEND_DEFAULT’
- draw_hit_boxes(color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]] = (0, 0, 0, 255), line_thickness: float = 1)[source]
Draw all the hit boxes in this list
- extend(sprites: Union[list, arcade.sprite_list.sprite_list.SpriteList])[source]
Extends the current list with the given list
- Parameters
sprites (list) – list of Sprites to add to the list
- index(sprite: arcade.sprite.Sprite) int [source]
Return the index of a sprite in the spritelist
- initialize()[source]
Create the internal OpenGL resources. This can be done if the sprite list is lazy or was created before the window / context. The initialization will happen on the first draw if this method is not called. This is acceptable for most people, but this method gives you the ability to pre-initialize to potentially void initial stalls during rendering.
Calling this otherwise will have no effect. Calling this method in another thread will result in an OpenGL error.
- insert(index: int, sprite: arcade.sprite_list.sprite_list._SpriteType)[source]
Inserts a sprite at a given index.
- move(change_x: float, change_y: float) None [source]
Moves all Sprites in the list by the same amount. This can be a very expensive operation depending on the size of the sprite list.
- on_update(delta_time: float = 0.016666666666666666)[source]
Update the sprite. Similar to update, but also takes a delta-time.
- property percent_sprites_moved
Property to estimate what percent of the sprites moved. Use internally to guess if spatial hashing should be turned on or off if the user didn’t specify.
- pop(index: int = - 1) arcade.sprite.Sprite [source]
Pop off the last sprite, or the given index, from the list
- Parameters
index (int) – Index of sprite to remove, defaults to -1 for the last item.
- preload_textures(texture_list: List[Texture]) None [source]
Preload a set of textures that will be used for sprites in this sprite list.
- Parameters
texture_list (array) – List of textures.
- remove(sprite: arcade.sprite_list.sprite_list._SpriteType)[source]
Remove a specific sprite from the list. :param Sprite sprite: Item to remove from the list
- rescale(factor: float) None [source]
Rescale all sprites in the list relative to the spritelists center.
- sort(*, key=None, reverse: bool = False)[source]
Sort the spritelist in place using
<
comparison between sprites. This function is similar to python’slist.sort
.Example sorting sprites based on y axis position using a lambda:
# Normal order spritelist.sort(key=lambda x: x.position[1]) # Reversed order spritelist.sort(key=lambda x: x.position[1], reverse=True)
Example sorting sprites using a function:
# More complex sorting logic can be applied, but let's just stick to y position def create_y_pos_comparison(sprite): return sprite.position[1] spritelist.sort(key=create_y_pos_comparison)
- Parameters
key – A function taking a sprite as an argument returning a comparison key
reverse (bool) – If set to
True
the sprites will be sorted in reverse
- swap(index_1: int, index_2: int)[source]
Swap two sprites by index :param int index_1: Item index to swap :param int index_2: Item index to swap
- update_angle(sprite: arcade.sprite.Sprite)[source]
Called by the Sprite class to update the angle in this sprite. Necessary for batch drawing of items.
- Parameters
sprite (Sprite) – Sprite to update.
- update_animation(delta_time: float = 0.016666666666666666)[source]
Call the update_animation in every sprite in the sprite list.
- update_color(sprite: arcade.sprite.Sprite) None [source]
Called by the Sprite class to update position, angle, size and color of the specified sprite. Necessary for batch drawing of items.
- Parameters
sprite (Sprite) – Sprite to update.
- update_height(sprite: arcade.sprite.Sprite)[source]
Called by the Sprite class to update the size/scale in this sprite. Necessary for batch drawing of items.
- Parameters
sprite (Sprite) – Sprite to update.
- update_location(sprite: arcade.sprite.Sprite)[source]
Called by the Sprite class to update the location in this sprite. Necessary for batch drawing of items.
- Parameters
sprite (Sprite) – Sprite to update.
- update_position(sprite: arcade.sprite.Sprite) None [source]
Called when setting initial position of a sprite when added or inserted into the SpriteList.
update_location
should be called to move them once the sprites are in the list.- Parameters
sprite (Sprite) – Sprite to update.
- update_size(sprite: arcade.sprite.Sprite) None [source]
Called by the Sprite class to update the size/scale in this sprite. Necessary for batch drawing of items.
- Parameters
sprite (Sprite) – Sprite to update.
- update_texture(sprite) None [source]
Make sure we update the texture for this sprite for the next batch drawing
- update_width(sprite: arcade.sprite.Sprite)[source]
Called by the Sprite class to update the size/scale in this sprite. Necessary for batch drawing of items.
- Parameters
sprite (Sprite) – Sprite to update.
arcade.check_for_collision
- arcade.check_for_collision(sprite1: arcade.sprite.Sprite, sprite2: arcade.sprite.Sprite) bool [source]
Check for a collision between two sprites.
- Parameters
sprite1 – First sprite
sprite2 – Second sprite
- Returns
True or False depending if the sprites intersect.
- Return type
arcade.check_for_collision_with_list
- arcade.check_for_collision_with_list(sprite: arcade.sprite.Sprite, sprite_list: arcade.sprite_list.sprite_list.SpriteList) List[arcade.sprite.Sprite] [source]
Check for a collision between a sprite, and a list of sprites.
- Parameters
sprite (Sprite) – Sprite to check
sprite_list (SpriteList) – SpriteList to check against
- Returns
List of sprites colliding, or an empty list.
- Return type
arcade.check_for_collision_with_lists
- arcade.check_for_collision_with_lists(sprite: arcade.sprite.Sprite, sprite_lists: Iterable[arcade.sprite_list.sprite_list.SpriteList]) List[arcade.sprite.Sprite] [source]
Check for a collision between a Sprite, and a list of SpriteLists. :param Sprite sprite: Sprite to check :param List[SpriteList] sprite_list: SpriteLists to check against :returns: List of sprites colliding, or an empty list. :rtype: list
arcade.get_closest_sprite
- arcade.get_closest_sprite(sprite: arcade.sprite.Sprite, sprite_list: arcade.sprite_list.sprite_list.SpriteList) Optional[Tuple[arcade.sprite.Sprite, float]] [source]
Given a Sprite and SpriteList, returns the closest sprite, and its distance.
- Parameters
sprite (Sprite) – Target sprite
sprite_list (SpriteList) – List to search for closest sprite.
- Returns
Closest sprite.
- Return type
arcade.get_sprites_at_exact_point
- arcade.get_sprites_at_exact_point(point: Union[Tuple[float, float], List[float]], sprite_list: arcade.sprite_list.sprite_list.SpriteList) List[arcade.sprite.Sprite] [source]
Get a list of sprites whose center_x, center_y match the given point. This does NOT return sprites that overlap the point, the center has to be an exact match.
- Parameters
point (Point) – Point to check
sprite_list (SpriteList) – SpriteList to check against
- Returns
List of sprites colliding, or an empty list.
- Return type
arcade.get_sprites_at_point
- arcade.get_sprites_at_point(point: Union[Tuple[float, float], List[float]], sprite_list: arcade.sprite_list.sprite_list.SpriteList) List[arcade.sprite.Sprite] [source]
Get a list of sprites at a particular point. This function sees if any sprite overlaps the specified point. If a sprite has a different center_x/center_y but touches the point, this will return that sprite.
- Parameters
point (Point) – Point to check
sprite_list (SpriteList) – SpriteList to check against
- Returns
List of sprites colliding, or an empty list.
- Return type