Sprites#
arcade.AnimatedTimeBasedSprite#
- class arcade.AnimatedTimeBasedSprite(path_or_texture: str | Path | Texture | None = None, center_x: float = 0.0, center_y: float = 0.0, scale: float = 1.0, **kwargs)[source]#
Sprite for platformer games that supports animations. These can be automatically created by the Tiled Map Editor.
- 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.
arcade.AnimatedWalkingSprite#
- class arcade.AnimatedWalkingSprite(scale: float = 1.0, center_x: float = 0.0, center_y: float = 0.0, **kwargs)[source]#
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.
- Parameters:
scale – Initial scale of the sprite.
center_x – Initial x position of the sprite.
center_y – Initial y position of the sprite.
arcade.AnimationKeyframe#
arcade.BasicSprite#
- class arcade.BasicSprite(texture: Texture, scale: float = 1.0, center_x: float = 0, center_y: float = 0, **kwargs)[source]#
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.
- 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.
- 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) – SpriteList to check against
- Returns:
List of all overlapping Sprites from the original SpriteList
- Return type:
- collides_with_point(point: Tuple[float, float]) bool [source]#
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:
- collides_with_sprite(other: SpriteType) bool [source]#
Will check if a sprite is overlapping (colliding) another Sprite.
- 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 255an 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] = Color(r=0, g=0, b=0, a=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 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.
- on_update(delta_time: float = 0.016666666666666666) None [source]#
Update the sprite. Similar to update, but also takes a delta-time. It can be called manually or by the SpriteList’s on_update method.
- Parameters:
delta_time (float) – Time since last update.
- property position: Tuple[float, float]#
Get or set the center x and y position of the sprite.
- Returns:
(center_x, center_y)
- 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.
- rescale_relative_to_point(point: Tuple[float, float], factor: float) None [source]#
Rescale the sprite and its distance from the passed point.
This function does two things:
Multiply both values in the sprite’s
scale_xy
value byfactor
.Scale the distance between the sprite and
point
byfactor
.
If
point
equals the sprite’sposition
, 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 [source]#
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
infactors_xy
.Internally, this function does the following:
Multiply the x & y of the sprite’s
scale_xy
attribute by the corresponding part fromfactors_xy
.Scale the x & y of the difference between the sprite’s position and
point
by the corresponding component fromfactors_xy
.
If
point
equals the sprite’sposition
, 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 topoint
.
- Returns:
- 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: float#
Get or set 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.
- 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() None [source]#
Generic update method. It can be called manually or by the SpriteList’s update method.
- update_animation(delta_time: float = 0.016666666666666666) 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 (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:
arcade.SpriteCircle#
- class arcade.SpriteCircle(radius: int, color: Tuple[int, int, int, int], soft: bool = False, **kwargs)[source]#
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
, andsoft
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
toTrue
. The circle will fade from an opaque center to transparent at the edges.
arcade.SpriteSolidColor#
- class arcade.SpriteSolidColor(width: int, height: int, center_x: float = 0, center_y: float = 0, color: Tuple[int, int, int, int] = Color(r=255, g=255, b=255, a=255), angle: float = 0, **kwargs)[source]#
A rectangular sprite of the given
width
,height
, andcolor
.The texture is automatically generated instead of loaded from a file. Internally only a single global texture is used for this sprite type, so concerns about memory usage non-existent regardless of size or number of sprite variations.
- Parameters:
width (int) – Width of the sprite in pixels
height (int) – Height of the sprite in pixels
center_x (float) – Initial x position of the sprite
center_y (float) – Initial y position of the sprite
color (ColorLike) – The color of the sprite as a
Color
, an RGBA tuple, or an RGB tuple.angle (float) – Initial angle of the sprite in degrees
arcade.PyMunk#
arcade.PymunkMixin#
arcade.load_animated_gif#
- arcade.load_animated_gif(resource_name) AnimatedTimeBasedSprite [source]#
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.
arcade.Sprite#
- class arcade.Sprite(path_or_texture: str | Path | Texture | None = None, scale: float = 1.0, center_x: float = 0.0, center_y: float = 0.0, angle: float = 0.0, **kwargs)[source]#
Sprites are used to render image data to the screen & perform collisions.
Most games center around sprites. They are most frequently used as follows:
Create
Sprite
instances from image dataAdd the sprites to a
SpriteList
instanceCall
SpriteList.draw()
on the instance inside youron_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 (str) – Path to an image file, or a texture object.
center_x (float) – Location of the sprite in pixels.
center_y (float) – Location of the sprite in pixels.
scale (float) – Show the image at this many times its original size.
angle (float) – 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)[source]#
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
- draw(*, filter=None, pixelated=None, blend_function=None) None [source]#
Draw the sprite.
- 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’
- face_point(point: Tuple[float, float]) None [source]#
Face the sprite towards a point. Assumes sprite image is facing upwards.
- Parameters:
point (Point) – Point to face towards.
- property hit_box: HitBox#
Get or set the hit box for this sprite.
- property properties: Dict[str, Any]#
Get or set custom sprite properties.
- Return type:
Dict[str, Any]
- 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) 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.
- remove_from_sprite_lists() None [source]#
Remove this sprite from all sprite lists it is in including registered physics engines.
- 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 (int) – Index into
self.textures
- 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