Sprites

arcade.load_animated_gif(resource_name: str | Path) → TextureAnimationSprite[source]

Attempt to load an animated GIF as a TextureAnimationSprite.

Note

Many older GIFs will load with incorrect transparency for every frame but the first. Until the Pillow library handles the quirks of the format better, loading animated GIFs will be pretty buggy. A good workaround is loading GIFs in another program and exporting them as PNGs, either as sprite sheets or a frame per file.

Parameters:

resource_name – A path to a GIF as either a pathlib.Path or a str which may include a resource handle.

class arcade.BasicSprite(texture: Texture, scale: float | tuple[float | int, float | int] | Vec2 = 1.0, center_x: float = 0, center_y: float = 0, visible: bool = True, **kwargs: Any)[source]

Bases:

The absolute minimum needed for a sprite.

It does not support features like rotation or changing the hitbox after creation. For more built-in features, please see Sprite.

Parameters:

  • texture – The texture data to use for this sprite.

  • scale – The scaling factor for drawing the texture.

  • center_x – Location of the sprite along the X axis in pixels.

  • center_y – Location of the sprite along the Y axis in pixels.

add_scale(factor: float | int) → None[source]

Add to the sprite’s scale by the factor. This adds the factor to both the x and y scale values.

Parameters:

factor – The factor to add to the sprite’s scale.

property alpha: int

Get or set the alpha value of the sprite.

Will be clamped to the range 0-255.

property bottom: float

The lowest y coordinate in the hit box.

When setting this property the sprite is positioned relative to the lowest y coordinate in the hit box.

property center_x: float

Get or set the center x position of the sprite.

property center_y: float

Get or set the center y position of the sprite.

collides_with_list(sprite_list: SpriteList) → list[SpriteType][source]

Check if current sprite is overlapping with any other sprite in a list

Parameters:

sprite_list – SpriteList to check against

Returns:

List of all overlapping Sprites from the original SpriteList

collides_with_point(point: tuple[float | int, float | int] | Vec2) → bool[source]

Check if point is within the current sprite.

Parameters:

point – Point to check.

Returns:

True if the point is contained within the sprite’s boundary.

collides_with_sprite(other: SpriteType) → bool[source]

Will check if a sprite is overlapping (colliding) another Sprite.

Parameters:

other – the other sprite to check against.

Returns:

True or False, whether or not they are overlapping.

property color: Color

Get or set the RGBA multiply color for the sprite.

When setting the color, it may be specified as any of the following:

  • an RGBA tuple with each channel value between 0 and 255

  • an instance of Color

  • an RGB tuple, in which case the color will be treated as opaque

Example usage:

>>> print(sprite.color)
Color(255, 255, 255, 255)

>>> sprite.color = arcade.color.RED

>>> sprite.color = 255, 0, 0

>>> sprite.color = 255, 0, 0, 128
property depth: float

Get or set the depth of the sprite.

This is really the z coordinate of the sprite and can be used with OpenGL depth testing with opaque sprites.

draw_hit_box(color: tuple[int, int, int, int] = (0, 0, 0, 255), line_thickness: float = 2.0) → None[source]

Draw a sprite’s hit-box. This is useful for debugging.

Parameters:

  • color – Color of box

  • line_thickness – How thick the box should be

property height: float

Get or set the height of the sprite in pixels.

property hit_box: HitBox

The hit box for this sprite.

kill() → None[source]

Alias of remove_from_sprite_lists().

property left: float

The leftmost x coordinate in the hit box.

When setting this property the sprite is positioned relative to the leftmost x coordinate in the hit box.

multiply_scale(factor: float | int) → None[source]

multiply the sprite’s scale by the factor. This multiplies both the x and y scale values by the factor.

Parameters:

factor – The factor to scale up the sprite by.

property position: tuple[float | int, float | int] | Vec2

Get or set the center x and y position of the sprite.

property rect: Rect

A rectangle with with the sprites left, right, bottom, and top values.

register_sprite_list(new_list: SpriteList) → None[source]

Register this sprite as belonging to a list.

We will automatically remove ourselves from the list when kill() is called.

remove_from_sprite_lists() → None[source]

Remove the sprite from all sprite lists.

rescale_relative_to_point(point: tuple[float | int, float | int] | Vec2, scale_by: float | int | tuple[float | int, float | int] | Vec2) → None[source]

Rescale the sprite and its distance from the passed point.

This function does two things:

  1. Multiply both values in the sprite’s scale value by the values in scale_by:

    • If scale_by is an int or float, use it for both the x and y axes

    • If scale_by is a tuple-like object which unpacks to two numbers, then use

    • Otherwise, raise an exception

  2. Scale the distance between the sprite and point by factor.

Note

If point equals the sprite’s position the distance will be zero and the sprite won’t move.

Parameters:

  • point – The point to scale relative to.

  • scale_by – A multiplier for both the sprite scale and its distance from the point. Note that although factor may be negative, it may have unexpected effects.

rescale_xy_relative_to_point(point: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3, factors_xy: Iterable[float]) → None[source]

Rescale the sprite and its distance from the passed point.

Deprecated since version 3.0: Use rescale_relative_to_point() instead.

This was added during the 3.0 development cycle before scale was made into a vector quantity.

This method can scale by different amounts on each axis. To scale along only one axis, set the other axis to 1.0 in factors_xy.

Internally, this function does the following:

  1. Multiply the x & y of the sprite’s scale_xy attribute by the corresponding part from factors_xy.

  2. Scale the x & y of the difference between the sprite’s position and point by the corresponding component from factors_xy.

If point equals the sprite’s position, the distance will be zero and the sprite will not move.

Parameters:

  • point – The reference point for rescaling.

  • factors_xy – A 2-length iterable containing x and y multipliers for scale & distance to point.

property rgb: tuple[int, int, int]

Get or set only the sprite’s RGB color components.

If a 4-color RGBA tuple is passed:

  • The new color’s alpha value will be ignored

  • The old alpha value will be preserved

property right: float

The rightmost x coordinate in the hit box.

When setting this property the sprite is positioned relative to the rightmost x coordinate in the hit box.

property scale: tuple[float | int, float | int] | Vec2

Get or set the x & y scale of the sprite as a pair of values. You may set both the x & y with a single scalar, but scale will always return a length 2 tuple of the x & y scale

See scale_x and scale_y for individual access.

See scale_multiply_uniform() for uniform scaling.

Note

Negative scale values are supported.

This applies to both single-axis and dual-axis. Negatives will flip & mirror the sprite, but the with will use abs() to report total width and height instead of negatives.

property scale_x: float

Get or set the sprite’s x scale value.

Note

Negative values are supported. They will flip & mirror the sprite.

property scale_y: float

Get or set the sprite’s y scale value.

Note

Negative values are supported. They will flip & mirror the sprite.

property size: tuple[float | int, float | int] | Vec2 | tuple[float | int, float | int, float | int] | Vec3

Get or set the size of the sprite as a pair of values.

This is faster than getting or setting width and height separately.

sprite_lists: list[SpriteList]

The sprite lists this sprite is a member of

property texture: Texture

Get or set the visible texture for this sprite This property can be changed over time to animate a sprite.

Note that this doesn’t change the hit box of the sprite.

property top: float

The highest y coordinate in the hit box.

When setting this property the sprite is positioned relative to the highest y coordinate in the hit box.

update(delta_time: float = 0.016666666666666666, *args, **kwargs) → None[source]

Generic update method. It can be called manually or by the SpriteList’s update method.

Parameters:

  • delta_time – Time since last update in seconds

  • *args – Additional positional arguments

  • **kwargs – Additional keyword arguments

update_animation(delta_time: float = 0.016666666666666666, *args, **kwargs) → None[source]

Generic update animation method. Usually involves changing the active texture on the sprite.

This can be called manually or by the SpriteList’s update_animation method.

Parameters:

  • delta_time – Time since last update in seconds

  • *args – Additional positional arguments

  • **kwargs – Additional keyword arguments

update_spatial_hash() → None[source]

Update the sprites location in the spatial hash if present.

property visible: bool

Get or set the visibility of this sprite.

When set to False, each SpriteList and its attached shaders will treat the sprite as if has an alpha of 0. However, the sprite’s actual values for alpha and color will not change.

# The initial color of the sprite
>>> sprite.color
Color(255, 255, 255, 255)

# Make the sprite invisible
>>> sprite.visible = False
# The sprite's color value has not changed
>>> sprite.color
Color(255, 255, 255, 255)
# The sprite's alpha value hasn't either
>>> sprite.alpha
255

# Restore visibility
>>> sprite.visible = True
# Shorthand to toggle visible
>>> sprite.visible = not sprite.visible
property width: float

Get or set width or the sprite in pixels

class arcade.Sprite(path_or_texture: str | Path | bytes | Texture | None = None, scale: float | tuple[float | int, float | int] | Vec2 = 1.0, center_x: float = 0.0, center_y: float = 0.0, angle: float = 0.0, **kwargs: Any)[source]

Bases: BasicSprite, PymunkMixin

Sprites are used to render image data to the screen & perform collisions.

Most games center around sprites. They are most frequently used as follows:

  1. Create Sprite instances from image data

  2. Add the sprites to a SpriteList instance

  3. Call SpriteList.draw() on the instance inside your on_draw method.

For runnable examples of how to do this, please see Arcade’s built-in Sprite examples.

Tip

Advanced users should see BasicSprite

It uses fewer resources at the cost of having fewer features.

Parameters:

  • path_or_texture – Path to an image file, or a texture object.

  • center_x – Location of the sprite in pixels.

  • center_y – Location of the sprite in pixels.

  • scale – Show the image at this many times its original size.

  • angle – The initial rotation of the sprite in degrees

property angle: float

Get or set the rotation or the sprite.

The value is in degrees and is clockwise.

append_texture(texture: Texture) → None[source]

Appends a new texture to the list of textures that can be applied to this sprite.

Parameters:

texture – Texture to add to the list of available textures

boundary_bottom: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

boundary_left: float | None

PhysicsEnginePlatformer uses this as the left boundary for moving platforms.

boundary_right: float | None

PhysicsEnginePlatformer uses this as the right boundary for moving platforms.

boundary_top: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

change_angle: float

Change in angle per 1/60th of a second.

property change_x: float

Get or set the velocity in the x plane of the sprite.

property change_y: float

Get or set the velocity in the y plane of the sprite.

cur_texture_index: int

Current texture index for sprite animation.

force

force vector used by pymunk

forward(speed: float = 1.0) → None[source]

Adjusts a Sprites forward.

Parameters:

speed – The speed at which the sprite moves.

guid: str | None

A unique id for debugging purposes.

property hit_box: HitBox

Get or set the hit box for this sprite.

physics_engines: list[Any]

List of physics engines that have registered this sprite.

property properties: dict[str, Any]

Get or set custom sprite properties.

property radians: float

Get or set the rotation of the sprite in radians.

The value is in radians and is clockwise.

register_physics_engine(physics_engine: Any) → None[source]

Register a physics engine on the sprite. This is only needed if you actually need a reference to your physics engine in the sprite itself. It has no other purposes.

The registered physics engines can be accessed through the physics_engines attribute.

It can for example be the pymunk physics engine or a custom one you made.

Parameters:

physics_engine – The physics engine to register

remove_from_sprite_lists() → None[source]

Remove this sprite from all sprite lists it is in including registered physics engines.

reverse(speed: float = 1.0) → None[source]

Adjusts a Sprite backwards.

Parameters:

speed – The speed at which the sprite moves.

set_texture(texture_no: int) → None[source]

Set the current texture by texture number. The number is the index into self.textures.

Parameters:

texture_no – Index into self.textures

stop() → None[source]

Stop the Sprite’s motion by setting the velocity and angle change to 0.

strafe(speed: float = 1.0) → None[source]

Adjusts a Sprite sideways.

Parameters:

speed – The speed at which the sprite moves.

sync_hit_box_to_texture() → None[source]

Update the sprite’s hit box to match the current texture’s hit box.

property texture: Texture

Get or set the active texture for this sprite

textures: list[Texture]

List of textures stored in the sprite.

turn_left(theta: float = 90.0) → None[source]

Rotate the sprite left by the passed number of degrees.

Parameters:

theta – Change in angle, in degrees

turn_right(theta: float = 90.0) → None[source]

Rotate the sprite right by the passed number of degrees.

Parameters:

theta – Change in angle, in degrees

update(delta_time: float = 0.016666666666666666, *args, **kwargs) → None[source]

The default update method for a Sprite. Can be overridden by a subclass.

This method moves the sprite based on its velocity and angle change.

Parameters:

  • delta_time – Time since last update in seconds

  • *args – Additional positional arguments

  • **kwargs – Additional keyword arguments

update_spatial_hash() → None[source]

Update the sprites location in the spatial hash.

property velocity: tuple[float | int, float | int] | Vec2

Get or set the velocity of the sprite.

The x and y velocity can also be set separately using the sprite.change_x and sprite.change_y properties.

Example:

sprite.velocity = 1.0, 0.0
class arcade.SpriteSolidColor(width: int, height: int, center_x: float = 0, center_y: float = 0, color: tuple[int, int, int, int] = (255, 255, 255, 255), angle: float = 0, **kwargs)[source]

Bases: Sprite

A rectangular sprite of the given width, height, and color.

The texture is automatically generated instead of loaded from a file. Internally only a single global image is used for this sprite type so concerns about memory usage non-existent regardless of size or number of sprite variations.

Different texture configurations (width, height) are weakly cached internally to avoid creating multiple textures with the same configuration.

Parameters:

  • width – Width of the sprite in pixels

  • height – Height of the sprite in pixels

  • center_x – Initial x position of the sprite

  • center_y – Initial y position of the sprite

  • color – The color of the sprite as a Color, an RGBA tuple, or an RGB tuple.

  • angle – Initial angle of the sprite in degrees

classmethod from_rect(rect: Rect, color: Color, angle: float = 0.0) → SpriteSolidColor[source]

Construct a new SpriteSolidColor from a Rect.

Parameters:

  • rect – The rectangle to use for the sprite’s dimensions and position.

  • color – The color of the sprite as a Color, an RGBA tuple, or an RGB tuple.

  • angle – The angle of the sprite in degrees.

class arcade.SpriteCircle(radius: int, color: tuple[int, int, int, int], soft: bool = False, **kwargs)[source]

Bases: Sprite

A circle of the specified radius.

The texture is automatically generated instead of loaded from a file.

There may be a stutter the first time a combination of radius, color, and soft is used due to texture generation. All subsequent calls for the same combination will run faster because they will re-use the texture generated earlier.

For a gradient fill instead of a solid color, set soft to True. The circle will fade from an opaque center to transparent at the edges.

Parameters:

  • radius – Radius of the circle in pixels

  • color – The Color of the sprite as an RGB or RGBA tuple

  • soft – If True, the circle will fade from an opaque center to transparent edges.

boundary_bottom: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

boundary_left: float | None

PhysicsEnginePlatformer uses this as the left boundary for moving platforms.

boundary_right: float | None

PhysicsEnginePlatformer uses this as the right boundary for moving platforms.

boundary_top: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

change_angle: float

Change in angle per 1/60th of a second.

cur_texture_index: int

Current texture index for sprite animation.

force

force vector used by pymunk

guid: str | None

A unique id for debugging purposes.

physics_engines: list[Any]

List of physics engines that have registered this sprite.

textures: list[Texture]

List of textures stored in the sprite.

class arcade.PyMunk[source]

Bases:

Object used to hold pymunk info for a sprite.

damping: float | None

Natural damping.

Damping is applied to objects to simulate the natural deceleration of objects due to friction.

gravity: tuple[float, float] | None

Gravity applied to the object.

max_horizontal_velocity: float | None

Maximum horizontal velocity allowed.

max_velocity: float | None

Maximum velocity allowed.

max_vertical_velocity: float | None

Maximum vertical velocity allowed.

class arcade.PymunkMixin[source]

Bases:

A mixin class that adds Pymunk physics to a sprite.

force

force vector used by pymunk

pymunk

Object used to hold pymunk info for a sprite.

pymunk_moved(physics_engine, dx: float, dy: float, d_angle: float) → None[source]

Called by the pymunk physics engine if this sprite moves.

Parameters:

  • physics_engine (PymunkPhysicsEngine) – The physics engine that is calling this method.

  • dx (float) – The change in x position.

  • dy (float) – The change in y position.

  • d_angle (float) – The change in angle.

class arcade.TextureKeyframe(texture: Texture, duration: int = 100, tile_id: int | None = 0, **kwargs)[source]

Bases:

Keyframe for texture animations.

Parameters:

  • texture – Texture to display for this keyframe.

  • duration – Duration in milliseconds to display this keyframe.

  • tile_id (optional) – Tile ID for this keyframe (only used for tiled maps). This can be ignored when not using tiled maps.

duration

Duration in milliseconds to display this keyframe.

texture

The texture to display for this keyframe.

tile_id

Tile ID for this keyframe (only used for tiled maps)

class arcade.TextureAnimation(keyframes: list[TextureKeyframe])[source]

Bases:

Animation class that holds a list of keyframes. The animation should not store any state related to the current time so it can be shared between multiple sprites.

Parameters:

keyframes – List of keyframes for the animation.

property duration_ms: int

Total duration of the animation in milliseconds.

property duration_seconds: float

Total duration of the animation in seconds.

get_keyframe(time: float, loop: bool = True) → tuple[int, TextureKeyframe][source]

Get the frame at a given time.

Parameters:

  • time – Time in seconds.

  • loop – If the animation should loop.

Returns:

Tuple of frame index and keyframe.

property keyframes: tuple[TextureKeyframe, ...]

A tuple of keyframes in the animation. Keyframes should not be modified directly.

property num_frames: int

Number of frames in the animation.

class arcade.TextureAnimationSprite(center_x: float = 0.0, center_y: float = 0.0, scale: float = 1.0, animation: TextureAnimation | None = None, **kwargs)[source]

Bases: Sprite

Animated sprite based on keyframes.

Primarily used internally by tilemaps to animate tiles.

Parameters:

  • path_or_texture – Path to the image file, or a Texture object.

  • center_x – Initial x position of the sprite.

  • center_y – Initial y position of the sprite.

  • scale – Initial scale of the sprite.

property animation: TextureAnimation

Animation object for this sprite.

boundary_bottom: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

boundary_left: float | None

PhysicsEnginePlatformer uses this as the left boundary for moving platforms.

boundary_right: float | None

PhysicsEnginePlatformer uses this as the right boundary for moving platforms.

boundary_top: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

change_angle: float

Change in angle per 1/60th of a second.

cur_texture_index: int

Current texture index for sprite animation.

force

force vector used by pymunk

guid: str | None

A unique id for debugging purposes.

physics_engines: list[Any]

List of physics engines that have registered this sprite.

textures: list[Texture]

List of textures stored in the sprite.

property time: float

Get or set the current time of the animation in seconds.

update_animation(delta_time: float = 0.016666666666666666, **kwargs) → None[source]

Logic for updating the animation.

Parameters:

delta_time – Time since last update.

class arcade.AnimatedWalkingSprite(scale: float | tuple[float | int, float | int] | Vec2 = 1.0, center_x: float = 0.0, center_y: float = 0.0, **kwargs)[source]

Bases: Sprite

Deprecated Sprite for platformer games that supports walking animations. Make sure to call update_animation after loading the animations so the initial texture can be set. Or manually set it.

It is highly recommended you create your own version of this class rather than try to use this pre-packaged one.

For an example, see this section of the platformer tutorial: Step 12 - Loading a Map From a Map Editor.

Parameters:

  • scale – Initial scale of the sprite.

  • center_x – Initial x position of the sprite.

  • center_y – Initial y position of the sprite.

boundary_bottom: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

boundary_left: float | None

PhysicsEnginePlatformer uses this as the left boundary for moving platforms.

boundary_right: float | None

PhysicsEnginePlatformer uses this as the right boundary for moving platforms.

boundary_top: float | None

PhysicsEnginePlatformer uses this as the top boundary for moving platforms.

change_angle: float

Change in angle per 1/60th of a second.

cur_texture_index: int

Current texture index for sprite animation.

force

force vector used by pymunk

guid: str | None

A unique id for debugging purposes.

physics_engines: list[Any]

List of physics engines that have registered this sprite.

textures: list[Texture]

List of textures stored in the sprite.

update_animation(delta_time: float = 0.016666666666666666) → None[source]

Logic for texture animation.

Parameters:

delta_time – Time since last update.