Texture Management#
- arcade.make_circle_texture(diameter: int, color: Tuple[int, int, int, int], name: str | None = None, hitbox_algorithm: HitBoxAlgorithm | None = None) Texture [source]#
Return a Texture of a circle with the given diameter and color.
- arcade.make_soft_circle_texture(diameter: int, color: Tuple[int, int, int, int], center_alpha: int = 255, outer_alpha: int = 0, name: str | None = None, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture [source]#
Return a
Texture
of a circle with the given diameter and color, fading out at its edges.- Parameters:
diameter – Diameter of the circle and dimensions of the square
Texture
returned.color – Color of the circle as a 4-length tuple or
Color
instance.center_alpha – Alpha value of the circle at its center.
outer_alpha – Alpha value of the circle at its edges.
name – Custom or pre-chosen name for this texture
hit_box_algorithm – The hit box algorithm
- Returns:
New
Texture
object.
- arcade.make_soft_square_texture(size: int, color: Tuple[int, int, int, int], center_alpha: int = 255, outer_alpha: int = 0, name: str | None = None) Texture [source]#
Return a
Texture
of a square with the given diameter and color, fading out at its edges.- Parameters:
size – Diameter of the square and dimensions of the square Texture returned.
color – Color of the square.
center_alpha – Alpha value of the square at its center.
outer_alpha – Alpha value of the square at its edges.
name – Custom or pre-chosen name for this texture
- Returns:
New
Texture
object.
- arcade.cleanup_texture_cache()[source]#
This cleans up the cache of textures. Useful when running unit tests so that the next test starts clean.
- arcade.get_default_image(size: Tuple[int, int] = (128, 128)) ImageData [source]#
Generates and returns a default image and caches it internally for future use.
- Parameters:
size – Size of the image to create.
- Returns:
The default image.
- arcade.get_default_texture(size: Tuple[int, int] = (128, 128)) Texture [source]#
Creates and returns a default texture and caches it internally for future use.
- Parameters:
size – Size of the texture to create
- Returns:
The default texture.
- class arcade.TextureManager[source]#
Bases:
This class is used to manage textures. It is used to keep track of textures that have been loaded, and to make sure we don’t load the same texture twice.
Textures loaded through this manager is cached internally.
- flush(sprite_sheets: bool = True, textures: bool = True, image_data: bool = True, hit_boxes: bool = False)[source]#
Remove contents from the texture manager.
- Parameters:
sprite_sheets – If
True
, sprite sheets will be flushed.textures – If
True
, textures will be flushed.image_data – If
True
, image data will be flushed.hit_boxes – If
True
, hit boxes will be flushed.
- arcade.load_spritesheet(file_name: str | Path, sprite_width: int, sprite_height: int, columns: int, count: int, margin: int = 0, hit_box_algorithm: HitBoxAlgorithm | None = None) List[Texture] [source]#
- Parameters:
file_name – Name of the file to that holds the texture.
sprite_width – Width of the sprites in pixels
sprite_height – Height of the sprites in pixels
columns – Number of tiles wide the image is.
count – Number of tiles in the image.
margin – Margin between images
hit_box_algorithm – The hit box algorithm
- Returns List:
List of
Texture
objects.
- arcade.load_texture(file_path: str | Path, *, x: int = 0, y: int = 0, width: int = 0, height: int = 0, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture [source]#
Load an image from disk and create a texture.
The
x
,y
,width
, andheight
parameters are used to specify a sub-rectangle of the image to load. If not specified, the entire image is loaded.- Parameters:
file_name – Name of the file to that holds the texture.
x – X coordinate of the texture in the image.
y – Y coordinate of the texture in the image.
width – Width of the texture in the image.
height – Height of the texture in the image.
hit_box_algorithm –
- Returns:
New
Texture
object.- Raises:
ValueError
- arcade.load_texture_pair(file_name: str | Path, hit_box_algorithm: HitBoxAlgorithm | None = None) Tuple[Texture, Texture] [source]#
Load a texture pair, with the second being a mirror image of the first. Useful when doing animations and the character can face left/right.
- Parameters:
file_name – Path to texture
hit_box_algorithm – The hit box algorithm
- arcade.load_textures(file_name: str | Path, image_location_list: Tuple[Tuple[int, int, int, int] | List[int], ...] | List[Tuple[int, int, int, int] | List[int]], mirrored: bool = False, flipped: bool = False, hit_box_algorithm: HitBoxAlgorithm | None = None) List[Texture] [source]#
Load a set of textures from a single image file.
Note: If the code is to load only part of the image, the given x, y coordinates will start with the origin (0, 0) in the upper left of the image. When drawing, Arcade uses (0, 0) in the lower left corner. Be careful with this reversal.
For a longer explanation of why computers sometimes start in the upper left, see: http://programarcadegames.com/index.php?chapter=introduction_to_graphics&lang=en#section_5
- Parameters:
file_name – Name of the file.
image_location_list – List of image sub-locations. Each rectangle should be a List of four floats: [x, y, width, height].
mirrored – If set to True, the image is mirrored left to right.
flipped – If set to True, the image is flipped upside down.
hit_box_algorithm – One of None, ‘None’, ‘Simple’ (default) or ‘Detailed’.
hit_box_detail – Float, defaults to 4.5. Used with ‘Detailed’ to hit box
- Returns:
List of
Texture
’s.- Raises:
ValueError
- class arcade.Texture(image: Image | ImageData, *, hit_box_algorithm: HitBoxAlgorithm | None = None, hit_box_points: Sequence[Tuple[float | int, float | int]] | None = None, hash: str | None = None, **kwargs)[source]#
Bases:
An arcade.Texture is simply a wrapper for image data as a Pillow image and the hit box data for this image used in collision detection. Usually created by the
load_texture
orload_textures
commands.- Parameters:
image – The image or ImageData for this texture
hit_box_algorithm – The algorithm to use for calculating the hit box.
hit_box_points – A list of hitbox points for the texture to use (Optional). Completely overrides the hit box algorithm.
hash – Optional unique name for the texture. Can be used to make this texture globally unique. By default the hash of the pixel data is used.
- add_atlas_ref(atlas: TextureAtlas) None [source]#
Add a reference to an atlas that this texture is in.
- classmethod create_atlas_name(hash: str, vertex_order: Tuple[int, int, int, int] = (0, 1, 2, 3))[source]#
- classmethod create_cache_name(*, hash: str, hit_box_algorithm: HitBoxAlgorithm, vertex_order: Tuple[int, int, int, int] = (0, 1, 2, 3)) str [source]#
Create a cache name for the texture.
- classmethod create_empty(name: str, size: Tuple[int, int], color: Tuple[int, int, int, int] = (0, 0, 0, 0)) Texture [source]#
Create a texture with all pixels set to transparent black.
The hit box of the returned Texture will be set to a rectangle with the dimensions in
size
because there is no non-blank pixel data to calculate a hit box.- Parameters:
name – The unique name for this texture
size – The xy size of the internal image
This function has multiple uses, including:
Allocating space in texture atlases
Generating custom cached textures from component images
The internal image can be altered with Pillow draw commands and then written/updated to a texture atlas. This works best for infrequent changes such as generating custom cached sprites. For frequent texture changes, you should instead render directly into the texture atlas.
Warning
If you plan to alter images using Pillow, read its documentation thoroughly! Some of the functions can have unexpected behavior.
For example, if you want to draw one or more images that contain transparency onto a base image that also contains transparency, you will likely need to use PIL.Image.alpha_composite as part of your solution. Otherwise, blending may behave in unexpected ways.
This is especially important for customizable characters.
Be careful of your RAM usage when using this function. The Texture this method returns will have a new internal RGBA Pillow image which uses 4 bytes for every pixel in it. This will quickly add up if you create many large Textures.
If you want to create more than one blank texture with the same dimensions, you can save CPU time and RAM by calling this function once, then passing the
image
attribute of the resulting Texture object to the class constructor for each additional blank Texture instance you would like to create. This can be especially helpful if you are creating multiple large Textures.
- classmethod create_filled(name: str, size: Tuple[int, int], color: Tuple[int, int, int, int]) Texture [source]#
Create a filled texture. This is an alias for
create_empty()
.
- classmethod create_image_cache_name(path: str | Path, crop: Tuple[int, int, int, int] = (0, 0, 0, 0))[source]#
- crop(x: int, y: int, width: int, height: int) Texture [source]#
Create a new texture from a sub-section of this texture.
If the crop is the same size as the original texture or the crop is 0 width or height, the original texture is returned.
- Parameters:
x – X position to start crop
y – Y position to start crop
width – Width of crop
height – Height of crop
cache – If True, the cropped texture will be cached
- Returns:
Texture
- draw_scaled(center_x: float, center_y: float, scale: float = 1.0, angle: float = 0.0, alpha: int = 255)[source]#
Draw the texture.
Warning
This is a very slow method of drawing a texture, and should be used sparingly. The method simply creates a sprite internally and draws it.
- Parameters:
center_x – X location of where to draw the texture.
center_y – Y location of where to draw the texture.
scale – Scale to draw rectangle. Defaults to 1.
angle – Angle to rotate the texture by.
alpha – The transparency of the texture (0-255).
- draw_sized(center_x: float, center_y: float, width: float, height: float, angle: float = 0.0, alpha: int = 255)[source]#
Draw a texture with a specific width and height.
Warning
This is a very slow method of drawing a texture, and should be used sparingly. The method simply creates a sprite internally and draws it.
- Parameters:
center_x – X position to draw texture
center_y – Y position to draw texture
width – Width to draw texture
height – Height to draw texture
angle – Angle to draw texture
alpha – Alpha value to draw texture
- flip_diagonally() Texture [source]#
Returns a new texture that is flipped diagonally from this texture. This is an alias for
transpose()
.This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- flip_horizontally() Texture [source]#
Flip the texture left to right / horizontally.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- flip_left_right() Texture [source]#
Flip the texture left to right / horizontally.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- flip_top_bottom() Texture [source]#
Flip the texture top to bottom / vertically.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- flip_vertically() Texture [source]#
Flip the texture top to bottom / vertically.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- remove_atlas_ref(atlas: TextureAtlas) None [source]#
Remove a reference to an atlas that this texture is in.
- remove_from_cache(ignore_error: bool = True) None [source]#
Remove this texture from the cache.
- Parameters:
ignore_error – If True, ignore errors if the texture is not in the cache
- Returns:
None
- rotate_180() Texture [source]#
Rotate the texture 180 degrees.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- rotate_270() Texture [source]#
Rotate the texture 270 degrees.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- rotate_90(count: int = 1) Texture [source]#
Rotate the texture by a given number of 90 degree steps.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Parameters:
count – Number of 90 degree steps to rotate.
- Returns:
Texture
- transform(transform: Type[Transform]) Texture [source]#
Create a new texture with the given transform applied.
- Parameters:
transform – Transform to apply
- Returns:
New texture
- transpose() Texture [source]#
Returns a new texture that is transposed from this texture. This flips the texture diagonally from lower right to upper left.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- transverse() Texture [source]#
Returns a new texture that is transverse from this texture. This flips the texture diagonally from lower left to upper right.
This returns a new texture with the same image data, but has updated hit box data and a transform that will be applied to the image when it’s drawn (GPU side).
- Returns:
Texture
- static validate_crop(image: Image, x: int, y: int, width: int, height: int) None [source]#
Validate the crop values for a given image.
- atlas_name#
The name of the texture used for the texture atlas (read only).
- Returns:
str
- cache_name#
The name of the texture used for caching (read only).
- Returns:
str
- crop_values#
The crop values used to create this texture in the referenced file
- Returns:
Tuple[int, int, int, int]
- file_path#
A Path object to the file this texture was loaded from
- Returns:
Path
- height#
The virtual width of the texture in pixels.
This can be different from the actual width if the texture has been transformed or the size have been set manually.
- hit_box_algorithm#
(read only) The algorithm used to calculate the hit box for this texture.
- hit_box_points#
Get the hit box points for this texture.
Custom hit box points must be supplied during texture creation and should ideally not be changed after creation.
- Returns:
PointList
- image#
Get or set the image of the texture.
Warning
This is an advanced function. Be absolutely sure you know the consequences of changing the image. It can cause problems with the texture atlas and hit box points.
- Parameters:
image – The image to set
- image_data#
The image data of the texture (read only).
This is a simple wrapper around the image containing metadata like hash and is used to determine the uniqueness of the image in texture atlases.
- Returns:
ImageData
- properties#
A dictionary of properties for this texture. This can be used to store any data you want.
- Returns:
Dict[str, Any]
- size#
The virtual size of the texture in pixels.
This can be different from the actual width if the texture has been transformed or the size have been set manually.
- width#
The virtual width of the texture in pixels. This can be different from the actual width if the texture has been transformed or the size have been set manually.
- class arcade.SpriteSheet(path: str | Path | None = None, image: Image | None = None)[source]#
Bases:
Class to hold a sprite sheet. A sprite sheet is a single image that contains multiple textures. Textures can be created from the sprite sheet by cropping out sections of the image.
This is only a utility class. It does not have any special functionality
- Parameters:
path – Path to the file to load.
image – PIL image to use.
- crop(area: Tuple[int, int, int, int] | List[int])[source]#
Crop a texture from the sprite sheet.
- Parameters:
area – Area to crop
(x, y, width, height)
- crop_grid(size: Tuple[int, int], columns: int, count: int, margin: Tuple[int, int, int, int] | List[int] = (0, 0, 0, 0), hit_box_algorithm: HitBoxAlgorithm | None = None) List[Texture] [source]#
Crop a grid of textures from the sprite sheet.
- Parameters:
size – Size of each texture
(width, height)
columns – Number of columns in the grid
count – Number of textures to crop
margin – The margin around each texture
(left, right, bottom, top)
hit_box_algorithm – Hit box algorithm to use for the textures.
- crop_sections(sections: List[Tuple[int, int, int, int] | List[int]])[source]#
Crop multiple textures from the sprite sheet by specifying a list of areas to crop.
- Parameters:
sections – List of areas to crop
[(x, y, width, height), ...]
- classmethod from_image(image: Image)[source]#
Create a sprite sheet from a PIL image.
- Parameters:
image – PIL image to use.
- flip_flags#
Query the orientation of the sprite sheet. This can be used to determine if the sprite sheet needs to be flipped.
Default values are
(False, False)
. Will be modified whenflip_left_right()
orflip_top_bottom()
is called.- Returns:
Tuple of booleans
(flip_left_right, flip_top_bottom)
.
- image#
Get or set the PIL image for this sprite sheet.
- path#
The path to the sprite sheet.
- Returns:
The path.