pygame_utility package

Submodules

pygame_utility.image_util module

pygame_utility.image_util.load_frames(path: str | Path, scale_ratio: Tuple[float, float] = (1.0, 1.0), scale_size: Tuple[int, int] | None = None) → List[Surface | None]

Load frames (images) from the given path and return them as a List of pygame Surfaces. The images within the directory are loaded in alphabetical order.

Parameters:

• path (Union[str, Path]) – Path of the directory containing image files.

• scale_ratio (Tuple[float, float]) – Tuple representing the scaling ratio for width and height. Defaults to (1.0, 1.0).

• scale_size (Optional[Tuple[int, int]]) – Tuple representing the target width and height in pixels. If provided, scale_size takes priority over scale_ratio.

Returns:

A List of loaded and scaled frames as pygame Surface objects.

Return type:

List[Optional[pygame.Surface]]

pygame_utility.image_util.load_image(path: str | Path, scale_ratio: Tuple[float, float] = (1.0, 1.0), scale_size: Tuple[int, int] | None = None) → Surface | None

Load an image from the given path and return it as a pygame Surface, scaled by the given ratio or size.

Parameters:

• path (Union[str, Path]) – Path of the image file.

• scale_ratio (Tuple[float, float]) – Tuple representing the scaling ratio for width and height. Defaults to (1.0, 1.0).

• scale_size (Optional[Tuple[int, int]]) – Tuple representing the target width and height in pixels. If provided, scale_size takes priority over scale_ratio.

Returns:

The loaded and scaled image as a pygame Surface object, or None if loading fails.

Return type:

Optional[pygame.Surface]

pygame_utility.image_util.load_state_frames(path: str | Path, scale_ratio: Tuple[float, float] = (1.0, 1.0), scale_size: Tuple[int, int] | None = None) → dict[str, List[Surface | None]]

Load multiple frames (images) from subdirectories of the given path and return them as a dictionary of Lists of pygame Surfaces. The images within each subdirectory are loaded in alphabetical order.

Parameters:

• path (Union[str, Path]) – Path of the directory containing subdirectories of image files.

• scale_ratio (Tuple[float, float]) – Tuple representing the scaling ratio for width and height. Defaults to (1.0, 1.0).

• scale_size (Optional[Tuple[int, int]]) – Tuple representing the target width and height in pixels. If provided, scale_size takes priority over scale_ratio.

Returns:

A dictionary where keys are subdirectory names and values are Lists of loaded and scaled frames as pygame Surface objects.

Return type:

dict[str, List[Optional[pygame.Surface]]]

pygame_utility.maploader module

class pygame_utility.maploader.MapLoader(filepath: str | Path)

Bases: object

Class for loading and managing TMX maps.

property all_layernames: List[str]

Get all layer names except TiledGroupLayer.

Returns:

List of layer names.

Return type:

List[str]

get_image_by_gid(gid: int) → Surface | None

Get an image by its GID.

Parameters:

gid (int) – The global ID of the tile.

Returns:

The image associated with the GID, or None if not found.

Return type:

Optional[Surface]

get_layer_data_by_name(name: str, only_coord: bool) → List[Tuple[int, int, Surface | None, int]]

Get data for a specific layer by name.

Parameters:

• name (str) – Name of the layer.

• only_coord (bool) – If True, return only coordinates; otherwise, include images.

Returns:

List of tuples containing x, y, the image (or None), and the image id.

Return type:

List[Tuple[int, int, Optional[Surface], int]]

Raises:

ValueError – If the layer does not exist.

get_map_data() → Dict[str, List[Tuple[int, int, Surface | None, int]]]

Get data for all layers in the map.

Returns:

Dictionary with layer names as keys and layer data (x, y, surface, id) as values.

Return type:

Dict[str, List[Tuple[int, int, Optional[Surface], int]]]

get_map_grid() → List[List[int]]

Yield TileLayer data as a 2D grid.

Returns:

Grid representing the map with tile GIDs.

Return type:

List[List[int]]

ok() → None

Clean up map data.

pygame_utility.sortkeys module

pygame_utility.sortkeys.get_numeric_sort_key(filepath: Path | str) → Tuple[float, str]

Extract the numeric part from a file path for sorting. If no numeric part is found, return infinity.

Parameters:

filepath (Union[Path, str]) – The file path to extract the numeric part from. Can be a Path object or a string.

Returns:

A tuple containing the numeric part as a float (or infinity if no number is found)

and the original file path. The tuple is used for sorting files primarily by the numeric part and secondarily by the file path if needed.

Return type:

Tuple[float, str]

Example without callback:

>>> files = ['file10.txt', 'file2.txt', 'file1.txt']
>>> sorted(files)
['file1.txt', 'file10.txt', 'file2.txt']

Example with get_numeric_sort_key callback:

>>> files = ['file10.txt', 'file2.txt', 'file1.txt']
>>> sorted(files, key=get_numeric_sort_key)
['file1.txt', 'file2.txt', 'file10.txt']

Module contents