Texture Management#

arcade.Texture#

class arcade.Texture(name: str, image: Optional[PIL.Image.Image] = None, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5)[source]#

Class that represents a texture. Usually created by the load_texture or load_textures commands.

Parameters

name (str) – Name of texture. Used for caching, so must be unique for each texture.
image (PIL.Image.Image) – Image to use as a texture.
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.

hit_box_algorithm = “None”#

hit_box_algorithm = “Simple”#

hit_box_algorithm = “Detailed”#
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box

Attributes:

name: Unique name of the texture. Used by load_textures for caching. If you are manually creating a texture, you can just set this to whatever.
image: A PIL.Image.Image object.
width: Width of the texture in pixels.
height: Height of the texture in pixels.
size: Tuple containing (width, height)
hit_box_points: The computed hit box of the texture

static build_cache_name(name, x, y, w, h, fh, fv, fd, hba) → str[source]#: Build the cache name of a texture

calculate_hit_box_points()[source]#: Calculate the hit box points for this texture based on the configured hit box algorithm. This is usually done on texture creation or when the hit box points are requested the first time.

classmethod create_empty(name: str, size: Tuple[int, int]) → arcade.texture.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 (str) – The unique name for this texture
size (Tuple[int,int]) – 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: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]]) → arcade.texture.Texture[source]#

Create a texture completely filled with the passed color.

The hit box of the returned Texture will be set to a rectangle with the dimensions in size because all pixels are filled with the same color.

Parameters

name (str) – The unique name for this texture
size (Tuple[int,int]) – The xy size of the internal image
color (Color) – the color to fill the texture with

This function has multiple uses, including:

A helper for pre-blending backgrounds into terrain tiles

Fillers to stand in for state-specific textures

Quick filler assets for various proofs of concept

If you want to create more than one filled texture with the same background color, 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 filled Texture instance you would like to create. This can be especially helpful if you are creating multiple large Textures.

draw_scaled(center_x: float, center_y: float, scale: float = 1.0, angle: float = 0.0, alpha: int = 255)[source]#

Draw the texture.

Parameters

center_x (float) – X location of where to draw the texture.
center_y (float) – Y location of where to draw the texture.
scale (float) – Scale to draw rectangle. Defaults to 1.
angle (float) – Angle to rotate the texture by.
alpha (int) – 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.

property height: int#: Height of the texture in pixels.

property size: Tuple[int, int]#: Width and height as a tuple

property width: int#: Width of the texture in pixels.

arcade.cleanup_texture_cache#

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.load_spritesheet#

arcade.load_spritesheet(file_name: Union[str, pathlib.Path], sprite_width: int, sprite_height: int, columns: int, count: int, margin: int = 0, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5) → List[arcade.texture.Texture][source]#

Parameters

file_name (str) – Name of the file to that holds the texture.
sprite_width (int) – Width of the sprites in pixels
sprite_height (int) – Height of the sprites in pixels
columns (int) – Number of tiles wide the image is.
count (int) – Number of tiles in the image.
margin (int) – Margin between images
hit_box_algorithm (str) – One of None, ‘None’, ‘Simple’ (default) or ‘Detailed’.
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box

Returns List

List of Texture objects.

arcade.load_texture#

arcade.load_texture(file_name: Union[str, pathlib.Path], x: int = 0, y: int = 0, width: int = 0, height: int = 0, flipped_horizontally: bool = False, flipped_vertically: bool = False, flipped_diagonally: bool = False, can_cache: bool = True, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5) → arcade.texture.Texture[source]#

Load an image from disk and create a texture.

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 (str) – Name of the file to that holds the texture.
x (float) – X position of the crop area of the texture.
y (float) – Y position of the crop area of the texture.
width (float) – Width of the crop area of the texture.
height (float) – Height of the crop area of the texture.
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.
can_cache (bool) – If a texture has already been loaded, load_texture will return the same texture in order to save time. Sometimes this is not desirable, as resizing a cached texture will cause all other textures to resize with it. Setting can_cache to false will prevent this issue at the experience of additional resources.
mirrored (bool) – Deprecated.
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.

hit_box_algorithm = “None”#

hit_box_algorithm = “Simple”#

hit_box_algorithm = “Detailed”#
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box

Returns

New Texture object.

Raises

ValueError

arcade.load_texture_pair#

arcade.load_texture_pair(file_name: str, hit_box_algorithm: str = 'Simple')[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 (str) – Path to texture
hit_box_algorithm (str) – The hit box algorithm

arcade.load_textures#

arcade.load_textures(file_name: Union[str, pathlib.Path], image_location_list: Union[Tuple[Union[Tuple[float, float, float, float], List[float]], ...], List[Union[Tuple[float, float, float, float], List[float]]]], mirrored: bool = False, flipped: bool = False, hit_box_algorithm: Optional[str] = 'Simple', hit_box_detail: float = 4.5) → List[arcade.texture.Texture][source]#

Load a set of textures from a single image file.

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 (str) – Name of the file.
image_location_list (List) – List of image sub-locations. Each rectangle should be a List of four floats: [x, y, width, height].
mirrored (bool) – If set to True, the image is mirrored left to right.
flipped (bool) – If set to True, the image is flipped upside down.
hit_box_algorithm (str) – One of None, ‘None’, ‘Simple’ (default) or ‘Detailed’.
hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box

Returns

List of Texture’s.

Raises

ValueError

arcade.make_circle_texture#

arcade.make_circle_texture(diameter: int, color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]], name: Optional[str] = None) → arcade.texture.Texture[source]#

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

Parameters

diameter (int) – Diameter of the circle and dimensions of the square Texture returned.
color (Color) – Color of the circle.
name (str) – Custom or pre-chosen name for this texture

Returns

New Texture object.

arcade.make_soft_circle_texture#

arcade.make_soft_circle_texture(diameter: int, color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]], center_alpha: int = 255, outer_alpha: int = 0, name: Optional[str] = None) → arcade.texture.Texture[source]#

Return a Texture of a circle with the given diameter and color, fading out at its edges.

Parameters

diameter (int) – Diameter of the circle and dimensions of the square Texture returned.
color (Color) – Color of the circle.
center_alpha (int) – Alpha value of the circle at its center.
outer_alpha (int) – Alpha value of the circle at its edges.
name (str) – Custom or pre-chosen name for this texture

Returns

New Texture object.

Return type

arcade.Texture

arcade.make_soft_square_texture#

arcade.make_soft_square_texture(size: int, color: Union[Tuple[int, int, int], List[int], Tuple[int, int, int, int]], center_alpha: int = 255, outer_alpha: int = 0, name: Optional[str] = None) → arcade.texture.Texture[source]#

Return a Texture of a square with the given diameter and color, fading out at its edges.

Parameters

size (int) – Diameter of the square and dimensions of the square Texture returned.
color (Color) – Color of the square.
center_alpha (int) – Alpha value of the square at its center.
outer_alpha (int) – Alpha value of the square at its edges.
name (str) – Custom or pre-chosen name for this texture

Returns

New Texture object.

arcade.trim_image#

arcade.trim_image(image: PIL.Image.Image) → PIL.Image.Image[source]#

Crops the extra whitespace out of an image.

Returns: New PIL.Image.Image object.