Texture Management

class arcade.texture.texture.ImageData(image: Image, hash: str | None = None, **kwargs)[source]

Bases:

A class holding the image for a texture with other metadata such as the hash. This information is used internally by the texture atlas to identify unique textures.

If a hash is not provided, it will be calculated. By default, the hash is calculated using the sha256 algorithm.

The ability to provide a hash directly is mainly there for ensuring we can load and save texture atlases to disk and for users to be able to allocate named regions in texture atlases.

Parameters:
  • image – The image for this texture

  • hash – The hash of the image

classmethod calculate_hash(image: Image) str[source]

Calculates the hash of an image.

The algorithm used is defined by the hash_func class variable.

Parameters:

image – The Pillow image to calculate the hash for

hash

The hash of the image

hash_func = 'sha256'
property height: int

Height of the image in pixels.

image

The pillow image

property size: tuple[int, int]

The size of the image in pixels.

property width: int

Width of the image in pixels.

class arcade.Texture(image: Image | ImageData, *, hit_box_algorithm: HitBoxAlgorithm | None = None, hit_box_points: Sequence[tuple[float | int, float | int] | Vec2] | None = None, hash: str | None = None, **kwargs)[source]

Bases:

A Texture is wrapper for image data as a Pillow image, hit box data for this image used in collision detection and transformations like rotation and flipping if applied.

Textures are by definition immutable. If you want to change the image data, you should create a new texture with the desired changes. There are some exceptions to this rule if you know the inner workings of the library.

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.

property atlas_name: str

The name of the texture used for the texture atlas (read only).

property cache_name: str

The name of the texture used for caching (read only).

classmethod create_atlas_name(hash: str, vertex_order: tuple[int, int, int, int] = (0, 1, 2, 3))[source]

Create a name for the texture in a texture atlas.

Parameters:
  • hash – The hash of the image data

  • vertex_order – The current vertex order of the texture

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.

Parameters:
  • hash – The hash of the image data

  • hit_box_algorithm – The hit box algorithm for this texture

  • vertex_order – The current vertex order of the texture

classmethod create_empty(name: str, size: tuple[int, int], color: tuple[int, int, int, int] = (0, 0, 0, 0), hit_box_points: Sequence[tuple[float | int, float | int] | Vec2] | None = None) Texture[source]

Create a texture with all pixels set to the given color.

The hit box of the returned Texture will be set to a rectangle with the dimensions in size unless hit_box_points are provided.

Parameters:
  • name – The unique name for this texture. This is used for caching and uniqueness in texture atlases.

  • size – The xy size of the internal image

  • color (optional) – The color to fill the texture with

  • hit_box_points (optional) – A list of hitbox points for the texture

classmethod create_image_cache_name(path: str | Path, crop: tuple[int, int, int, int] = (0, 0, 0, 0))[source]

Create a cache name for an image.

Parameters:
  • path – The path to the image file

  • crop – The crop values used to create the texture

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

property crop_values: tuple[int, int, int, int] | None

The crop values used to create this texture, This is used to track the real origin of the pixel data.

property file_path: Path | None

A Path to the file this texture was loaded from

flip_diagonally() Texture[source]

Creates 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).

flip_horizontally() Texture[source]

Create a new texture that is flipped horizontally from this texture.

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).

flip_left_right() Texture[source]

Create a new texture that is flipped left to right from this texture.

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).

flip_top_bottom() Texture[source]

Create a new texture that is flipped top to bottom from this texture.

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).

flip_vertically() Texture[source]

Create a new texture that is flipped vertically from this texture.

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).

property height: int

The virtual width of the texture in pixels.

This can be different from the actual height of the image if set manually. It can be used to trick sprites into believing the texture us much larger than it is.

property hit_box_algorithm: HitBoxAlgorithm

(read only) The algorithm used to calculate the hit box for this texture.

property hit_box_points: Sequence[tuple[float | int, float | int] | Vec2]

Get the hit box points for this texture (read only).

Custom hit box points must be supplied during texture creation and should ideally not be changed after creation.

property image: 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.

property image_cache_name: str | None

Get the image cache name for this texture. Returns None if not loaded from a file.

property image_data: ImageData

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.

property properties: dict[str, Any]

A dictionary of properties for this texture. This can be used to store any data you want.

rotate_180() Texture[source]

Create a new texture that is rotated 180 degrees from this texture.

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).

rotate_270() Texture[source]

Create a new texture that is rotated 270 degrees from this texture.

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).

rotate_90(count: int = 1) Texture[source]

Create a new texture that is rotated 90 degrees from this texture.

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.

property size: tuple[int, int]

The virtual size of the texture in pixels.

This can be different from the actual size of the image if set manually. It can be used to trick sprites into believing the texture us much larger than it is.

transform(transform: type[Transform]) Texture[source]

Create a new texture with the given transform applied.

Parameters:

transform – Transform to apply

transpose() Texture[source]

Creates 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).

transverse() Texture[source]

Creates 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).

static validate_crop(image: Image, x: int, y: int, width: int, height: int) None[source]

Validate the crop values for a given image.

Parameters:
  • image – The image to crop

  • x – X position to start crop

  • y – Y position to start crop

  • width – Width of crop

  • height – Height of crop

property width: int

The virtual width of the texture in pixels.

This can be different from the actual width of the image if set manually. It can be used to trick sprites into believing the texture us much larger than it is.

arcade.load_texture(file_path: str | Path, *, hit_box_algorithm: HitBoxAlgorithm | None = None, hash: str | None = None) Texture[source]

Load a texture from disk (no caching).

When loading a texture a set of hit box points will be generated by default based on the pixel data. The default hit box algorithm is a simple 4 to 8 point hit box. This can be overridden by passing a different hit box or the global default can be set in the hitbox module.

Examples:

# We can load a texture using resource handles, string path or Path object
texture = load_texture(":resources:image.png")
texture = load_texture("image.png")
texture = load_texture(Path("image.png"))

# We can also specify a hit box algorithm to use for this texture
texture = load_texture(
    ":resources:images/enemies/slimeBlock.png",
    hit_box_algorithm=arcade.hitbox.algo_detailed.
)
Parameters:
  • file_path – Path to the image file

  • hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not specified the global default will be used.

  • hash – (advanced) Optional custom hash/name for the loaded image. This is used for texture caching and global uniqueness in texture atlases.

arcade.load_image(file_path: str | Path, *, mode: str = 'RGBA') Image[source]

Load a Pillow image from disk (no caching).

Normally you would use load_texture instead of this function. This function is useful when you want to load an image and then manipulate it before creating a texture.

Note that Arcade mainly works with RGBA images. If you override the mode you might need to convert the final image to RGBA.

Parameters:
  • file_path – Path to the image file

  • mode – The desired mode for the image (default: “RGBA”)

arcade.load_spritesheet(file_name: str | Path) SpriteSheet[source]

Loads an image from disk returning a sprite sheet that can further be used to slice out smaller images.

Parameters:

file_name – Path to the image file

arcade.make_circle_texture(diameter: int, color: tuple[int, int, int, int], name: str | None = None, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture[source]

Creates a Texture of a circle with the given diameter and color.

Parameters:
  • diameter – Diameter of the circle and dimensions of the square Texture returned.

  • color – Color of the circle as a Color instance a 3 or 4 tuple.

  • name (optional) – A unique name for the texture. If not provided, a name will be generated. This is used for caching and unique identifier for texture atlases.

  • hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not provided, the default hit box algorithm will be used.

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]

Creates 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 (optional) – A unique name for the texture. If not provided, a name will be generated. This is used for caching and unique identifier for texture atlases.

  • hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not provided, the default hit box algorithm will be used.

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]

Creates 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 (optional) – A unique name for the texture. If not provided, a name will be generated. This is used for caching and unique identifier for texture atlases.

class arcade.TextureCacheManager(hit_box_cache: HitBoxCache | None = None, image_data_cache: ImageDataCache | None = None, texture_cache: TextureCache | None = None)[source]

Bases:

A simple manager wrapping texture, image data and hit box caches with convenient methods for loading textures and sprite sheets.

Parameters:
  • hit_box_cache – Optional hit box cache to use. If not specified, a new cache will be created.

  • image_data_cache – Optional image data cache to use. If not specified, a new cache will be created.

  • texture_cache – Optional texture cache to use. If not specified, a new cache will be created

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.

property hit_box_cache: HitBoxCache

Get or set the current hit box cache.

property image_data_cache: ImageDataCache

Cache for image data.

load_or_get_image(path: str | Path, hash: str | None = None, mode='RGBA') ImageData[source]

Loads a complete image from disk or return a cached version.

Parameters:
  • path – Path of the file to load.

  • hash – Optional override for image hash

  • mode – The mode to use for the image. Default is “RGBA”.

load_or_get_spritesheet(path: str | Path) SpriteSheet[source]

Load a sprite sheet from disk, or return a cached version.

Note that any texture sliced from the sprite sheet will be cached. if this is not the desirable behavior, use load_or_get_spritesheet_texture().

Parameters:

path – Path to the sprite sheet image

load_or_get_spritesheet_texture(path: str | Path, rect: Rect, hit_box_algorithm: HitBoxAlgorithm | None = None) Texture[source]

Slice out a texture slice from a sprite sheet.

  • If the spritesheet is not already loaded, it will be loaded and cached.

  • If the sliced texture is already cached, it will be returned instead.

Parameters:
  • path – Path to the sprite sheet image

  • rect – Slice of the texture in the sprite sheet.

  • hit_box_algorithm (optional) – Hit box algorithm to use. If not specified, the global default will be used.

load_or_get_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. If the image is already loaded, return the cached version.

The x, y, width, and height parameters are used to specify a sub-rectangle of the image to load. If not specified, the entire image is loaded.

Parameters:
  • file_path – Path to the image file.

  • x (optional) – X coordinate of the texture in the image.

  • y (optional) – Y coordinate of the texture in the image.

  • width (optional) – Width of the texture in the image.

  • height (optional) – Height of the texture in the image.

  • hit_box_algorithm (optional) – The hit box algorithm to use for this texture. If not specified, the global default will be used.

property texture_cache: TextureCache

Cache for textures.

class arcade.SpriteSheet(path: str | Path | None = None, image: Image | None = None)[source]

Bases:

A sprite sheet is a single image containing multiple smaller images, or frames. The class is used to load the image providing methods to slice out parts of the image as separate images or textures.

Note that the default coordinate system used for slicing is using image coordinates (0, 0) in the upper left corner. This matches the coordinate system used by PIL.

Parameters:
  • path (optional)

  • image (optional) – PIL image to use.

property flip_flags: tuple[bool, bool]

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 when flip_left_right() or flip_top_bottom() is called.

Tuple of booleans (flip_left_right, flip_top_bottom).

flip_left_right() None[source]

Flips the internal image left to right.

flip_top_bottom() None[source]

Flip the internal image top to bottom.

classmethod from_image(image: Image) SpriteSheet[source]

Create a sprite sheet from a PIL image.

Parameters:

image – PIL image to use.

get_image(rect: Rect, y_up=False) Image[source]

Slice out an image from the sprite sheet.

Parameters:
  • rect – The rectangle to crop out.

  • y_up – Sets the coordinate space of the image to assert (0, 0) in the bottom left.

get_image_grid(size: tuple[int, int], columns: int, count: int, margin: tuple[int, int, int, int] = (0, 0, 0, 0)) list[Image][source]

Slice 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)

get_texture(rect: Rect, hit_box_algorithm: HitBoxAlgorithm | None = None, y_up=False) Texture[source]

Slice out texture from the sprite sheet.

Parameters:
  • rect – The rectangle to crop out.

  • hit_box_algorithm – Hit box algorithm to use for the texture. If not provided, the default hit box algorithm will be used.

  • y_up – Sets the coordinate space of the image to assert (0, 0) in the bottom left.

get_texture_grid(size: tuple[int, int], columns: int, count: int, margin: tuple[int, int, int, int] = (0, 0, 0, 0), hit_box_algorithm: HitBoxAlgorithm | None = None) list[Texture][source]

Slice 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. If not provided, the default hit box algorithm will be used.

property image: Image

Get or set the PIL image for this sprite sheet.

property path: Path | None

The path to the sprite sheet if it was loaded from disk.

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

arcade.get_default_image(size: tuple[int, int] = (128, 128)) ImageData[source]

Generates and returns a default image of the specified size and caches it in the default texture cache.

Parameters:

size – Size of the image