Sprites

arcade.AnimatedTimeBasedSprite

class arcade.AnimatedTimeBasedSprite(filename: Optional[str] = None, scale: float = 1.0, image_x: int = 0, image_y: int = 0, image_width: int = 0, image_height: int = 0, center_x: float = 0.0, center_y: float = 0.0)

Sprite for platformer games that supports animations. These can be automatically created by the Tiled Map Editor.

update_animation(delta_time: float = 0.016666666666666666) → None

Logic for selecting the proper texture to use.

arcade.AnimatedWalkingSprite

class arcade.AnimatedWalkingSprite(scale: float = 1.0, image_x: int = 0, image_y: int = 0, center_x: float = 0.0, center_y: float = 0.0)

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 - Add Character Animations, and Better Keyboard Control.

update_animation(delta_time: float = 0.016666666666666666) → None

Logic for selecting the proper texture to use.

arcade.AnimationKeyframe

class arcade.AnimationKeyframe(tile_id: int, duration: int, texture: Texture)

Used in animated sprites.

arcade.PyMunk

class arcade.PyMunk

Object used to hold pymunk info for a sprite.

arcade.Sprite

class arcade.Sprite(filename: Optional[str] = None, scale: float = 1.0, image_x: int = 0, image_y: int = 0, image_width: int = 0, image_height: int = 0, center_x: float = 0.0, center_y: float = 0.0, flipped_horizontally: bool = False, flipped_vertically: bool = False, flipped_diagonally: bool = False, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5, texture: Optional[Texture] = None, angle: float = 0.0)

Class that represents a ‘sprite’ on-screen. Most games center around sprites. For examples on how to use this class, see: https://api.arcade.academy/en/latest/examples/index.html#sprites

Parameters:

• filename (str) – Filename of an image that represents the sprite.

• scale (float) – Scale the image up or down. Scale of 1.0 is none.

• image_x (float) – X offset to sprite within sprite sheet.

• image_y (float) – Y offset to sprite within sprite sheet.

• image_width (float) – Width of the sprite

• image_height (float) – Height of the sprite

• center_x (float) – Location of the sprite

• center_y (float) – Location of the sprite

• flipped_horizontally (bool) – Mirror the sprite image. Flip left/right across vertical axis.

• flipped_vertically (bool) – Flip the image up/down across the horizontal axis.

• flipped_diagonally (bool) – Transpose the image, flip it across the diagonal.

• hit_box_algorithm (str) – One of None, ‘None’, ‘Simple’ or ‘Detailed’. Defaults to ‘Simple’. Use ‘Simple’ for the PhysicsEngineSimple, PhysicsEnginePlatformer and ‘Detailed’ for the PymunkPhysicsEngine.

• texture (Texture) – Specify the texture directly.

• angle (float) – The initial rotation of the sprite in degrees

This will ignore all hit box and image size arguments.

hit_box_algorithm = “None”

hit_box_algorithm = “Simple”

hit_box_algorithm = “Detailed”

Parameters:

hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box

Attributes:

alpha:

Transparency of sprite. 0 is invisible, 255 is opaque.

angle:

Rotation angle in degrees. Sprites rotate counter-clock-wise.

radians:

Rotation angle in radians. Sprites rotate counter-clock-wise.

bottom:

Set/query the sprite location by using the bottom coordinate. This will be the ‘y’ of the bottom of the sprite.

boundary_left:

Used in movement. Left boundary of moving sprite.

boundary_right:

Used in movement. Right boundary of moving sprite.

boundary_top:

Used in movement. Top boundary of moving sprite.

boundary_bottom:

Used in movement. Bottom boundary of moving sprite.

center_x:

X location of the center of the sprite

center_y:

Y location of the center of the sprite

change_x:

Movement vector, in the x direction.

change_y:

Movement vector, in the y direction.

change_angle:

Change in rotation.

color:

Color tint the sprite

cur_texture_index:

Index of current texture being used.

guid:

Unique identifier for the sprite. Useful when debugging.

height:

Height of the sprite.

force:

Force being applied to the sprite. Useful when used with Pymunk for physics.

hit_box:

Points, in relation to the center of the sprite, that are used for collision detection. Arcade defaults to creating a hit box via the ‘simple’ hit box algorithm that encompass the image. If you are creating a ramp or making better hit-boxes, you can custom-set these.

left:

Set/query the sprite location by using the left coordinate. This will be the ‘x’ of the left of the sprite.

position:

A list with the (x, y) of where the sprite is.

right:

Set/query the sprite location by using the right coordinate. This will be the ‘y=x’ of the right of the sprite.

sprite_lists:

List of all the sprite lists this sprite is part of.

texture:

arcade.Texture class with the current texture. Setting a new texture does not update the hit box of the sprite. This can be done with my_sprite.hit_box = my_sprite.texture.hit_box_points. New textures will be centered on the current center_x/center_y.

textures:

List of textures associated with this sprite.

top:

Set/query the sprite location by using the top coordinate. This will be the ‘y’ of the top of the sprite.

scale:

Scale the image up or down. Scale of 1.0 is original size, 0.5 is 1/2 height and width.

velocity:

Change in x, y expressed as a list. (0, 0) would be not moving.

width:

Width of the sprite

It is common to over-ride the update method and provide mechanics on movement or other sprite updates.

add_spatial_hashes() → None

Add spatial hashes for this sprite in all the sprite lists it is part of.

property alpha: int

Return the alpha associated with the sprite.

property angle: float

Get the angle of the sprite’s rotation.

append_texture(texture: Texture)

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

Parameters:

texture (arcade.Texture) – Texture to add to the list of available textures

property bottom: float

Return the y coordinate of the bottom of the sprite.

property center_x: float

Get the center x coordinate of the sprite.

property center_y: float

Get the center y coordinate of the sprite.

property change_x: float

Get the velocity in the x plane of the sprite.

property change_y: float

Get the velocity in the y plane of the sprite.

clear_spatial_hashes() → None

Search the sprite lists this sprite is a part of, and remove it from any spatial hashes it is a part of.

collides_with_list(sprite_list: SpriteList) → List[Sprite]

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

Parameters:

sprite_list (SpriteList) – SpriteList to check against

Returns:

SpriteList of all overlapping Sprites from the original SpriteList

Return type:

SpriteList

collides_with_point(point: Tuple[float, float]) → bool

Check if point is within the current sprite.

Parameters:

point (Point) – Point to check.

Returns:

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

Return type:

bool

collides_with_sprite(other: Sprite) → bool

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

Parameters:

other (Sprite) – the other sprite to check against.

Returns:

True or False, whether or not they are overlapping.

Return type:

bool

property color: Union[Tuple[int, int, int], List[int]]

Return the RGB color associated with the sprite.

draw(*, filter=None, pixelated=None, blend_function=None) → None

Draw the sprite.

Parameters:

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

• pixelated – True for pixelated and False 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_box(color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]] = (0, 0, 0), line_thickness: float = 1) → None

Draw a sprite’s hit-box.

The ‘hit box’ drawing is cached, so if you change the color/line thickness later, it won’t take.

Parameters:

• color – Color of box

• line_thickness – How thick the box should be

face_point(point: Tuple[float, float]) → None

Face the sprite towards a point. Assumes sprite image is facing upwards.

Parameters:

point (Point) – Point to face towards.

forward(speed: float = 1.0) → None

Adjusts a Sprite’s movement vector forward. This method does not actually move the sprite, just takes the current change_x/change_y and adjusts it by the speed given.

Parameters:

speed – speed factor

get_adjusted_hit_box() → Sequence[Tuple[float, float]]

Get the points that make up the hit box for the rect that makes up the sprite, including rotation and scaling.

get_hit_box() → Sequence[Tuple[float, float]]

Use the hit_box property to get or set a sprite’s hit box. Hit boxes are specified assuming the sprite’s center is at (0, 0). Specify hit boxes like:

mySprite.hit_box = [[-10, -10], [10, -10], [10, 10]]

Specify a hit box unadjusted for translation, rotation, or scale. You can get an adjusted hit box with arcade.Sprite.get_adjusted_hit_box.

property height: float

Get the height in pixels of the sprite.

kill() → None

Alias of remove_from_sprite_lists

property left: float

Return the x coordinate of the left-side of the sprite’s hit box.

on_update(delta_time: float = 0.016666666666666666) → None

Update the sprite. Similar to update, but also takes a delta-time.

property position: Tuple[float, float]

Get the center x and y coordinates of the sprite.

Returns:

(center_x, center_y)

property properties: Dict[str, Any]

Get or set custom sprite properties.

Return type:

Dict[str, Any]

property pymunk: PyMunk

Get or set the Pymunk property objects. This is used by the pymunk physics engine.

pymunk_moved(physics_engine, dx, dy, d_angle)

Called by the pymunk physics engine if this sprite moves.

property radians: float

Converts the degrees representation of self.angle into radians. :return: float

register_physics_engine(physics_engine) → None

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.

register_sprite_list(new_list: SpriteList) → None

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

Remove the sprite from all sprite lists.

rescale_relative_to_point(point: Tuple[float, float], factor: float) → None

Rescale the sprite and its distance from the passed point.

This function does two things:

1. Multiply both values in the sprite’s scale_xy value by factor.

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

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.

• factor – Multiplier for sprite scale & distance to point.

Returns:

rescale_xy_relative_to_point(point: Tuple[float, float], factors_xy: Iterable[float]) → None

Rescale the sprite and its distance from the passed point.

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.

Returns:

reverse(speed: float = 1.0) → None

Adjusts a Sprite’s movement vector backwards. This method does not actually move the sprite, just takes the current change_x/change_y and adjusts it by the speed given.

Parameters:

speed – speed factor

property right: float

Return the x coordinate of the right-side of the sprite’s hit box.

property scale: float

Get the sprite’s x scale value or set both x & y scale to the same value.

Note

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

property scale_xy: Tuple[float, float]

Get or set the x & y scale of the sprite as a pair of values.

set_hit_box(points: Sequence[Tuple[float, float]]) → None

Set a sprite’s hit box. Hit box should be relative to a sprite’s center, and with a scale of 1.0. Points will be scaled with get_adjusted_hit_box.

set_position(center_x: float, center_y: float) → None

Set a sprite’s position

Parameters:

• center_x (float) – New x position of sprite

• center_y (float) – New y position of sprite

set_texture(texture_no: int)

Sets texture by texture id. Should be renamed because it takes a number rather than a texture, but keeping this for backwards compatibility.

stop() → None

Stop the Sprite’s motion.

strafe(speed: float = 1.0) → None

Adjusts a Sprite’s movement vector sideways. This method does not actually move the sprite, just takes the current change_x/change_y and adjusts it by the speed given.

Parameters:

speed – speed factor

property top: float

Return the y coordinate of the top of the sprite.

turn_left(theta: float = 90.0) → None

Rotate the sprite left by the passed number of degrees.

Parameters:

theta – change in angle, in degrees

turn_right(theta: float = 90.0) → None

Rotate the sprite right by the passed number of degrees.

Parameters:

theta – change in angle, in degrees

update() → None

Update the sprite.

update_animation(delta_time: float = 0.016666666666666666) → None

Override this to add code that will change what image is shown, so the sprite can be animated.

Parameters:

delta_time (float) – Time since last update.

property visible: bool

Get or set the visibility of this sprite. This is a shortcut for changing the alpha value of a sprite to 0 or 255:

# Make the sprite invisible
sprite.visible = False
# Change back to visible
sprite.visible = True
# Toggle visible
sprite.visible = not sprite.visible

Return type:

bool

property width: float

Get the width of the sprite.

arcade.SpriteCircle

class arcade.SpriteCircle(radius: int, color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]], soft: bool = False)

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 (int) – Radius of the circle in pixels

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

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

arcade.SpriteSolidColor

class arcade.SpriteSolidColor(width: int, height: int, color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]])

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

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

There may be a stutter the first time a combination of width, height, and color 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.

Parameters:

• width (int) – Width of the sprite in pixels

• height (int) – Height of the sprite in pixels

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

arcade.get_distance_between_sprites

arcade.get_distance_between_sprites(sprite1: Sprite, sprite2: Sprite) → float

Returns the distance between the center of two given sprites

Parameters:

• sprite1 (Sprite) – Sprite one

• sprite2 (Sprite) – Sprite two

Returns:

Distance

Return type:

float

arcade.load_animated_gif

arcade.load_animated_gif(resource_name) → AnimatedTimeBasedSprite

Attempt to load an animated GIF as an AnimatedTimeBasedSprite.

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.