Mask

A collision mask for pixel-perfect collision detection.

Constructor

  • Mask() → Mask
  • Mask(size: Vec2, filled: bool = False) → Mask
  • Mask(
        pixel_array: PixelArray,
        threshold: SupportsInt = 1
    ) → Mask

A collision mask for pixel-perfect collision detection.

Properties

NameDescriptionType
heightThe height of the mask in pixels.int
sizeThe size of the mask as a Vec2.Vec2
widthThe width of the mask in pixels.int

Methods

Add

add(other: Mask, offset: Any = None) → None

Add another mask to this mask with an offset.

Performs a bitwise OR operation between the masks.

Args

  • other : The mask to add.
  • offset : Position offset for the other mask. Defaults to (0, 0).

Clear

clear() → None

Clear the entire mask, setting all pixels to transparent.

Collide Mask

collide_mask(other: Mask, offset: Any = None) → bool

Check collision between this mask and another mask with an offset.

Args

  • other : The other mask to test collision with.
  • offset : Position offset between the masks. Defaults to (0, 0).

Returns

bool : True if the masks collide, False otherwise.

Copy

copy() → Mask

Create a copy of this mask.

Returns

Mask : A new Mask with the same dimensions and pixel data.

Fill

fill() → None

Fill the entire mask with solid pixels.

Get At

get_at(pos: Vec2) → bool

Get the pixel value at a specific position.

Args

  • pos : The position to check.

Returns

bool : True if the pixel is solid (above threshold), False otherwise.

Get Bounding Rect

get_bounding_rect() → Rect

Get the bounding rectangle that contains all solid pixels.

Returns

Rect : The smallest rectangle containing all solid pixels. Returns empty rect if mask has no solid pixels.

Get Center Of Mass

get_center_of_mass() → Vec2

Calculate the center of mass of all solid pixels.

Returns

Vec2 : The center of mass position. Returns (0, 0) if mask is empty.

Get Collision Points

get_collision_points(other: Mask, offset: Any = None) → list[Vec2]

Get all points where this mask collides with another mask.

Args

  • other : The other mask to test collision with.
  • offset : Position offset between the masks. Defaults to (0, 0).

Returns

list[Vec2] : A list of collision points.

Get Count

get_count() → int

Get the number of solid pixels in the mask.

Returns

int : The count of solid pixels.

Get Outline

get_outline() → list[Vec2]

Get the outline points of the mask.

Returns a list of points that form the outline of all solid regions.

Returns

list[Vec2] : A list of outline points.

Get Overlap Area

get_overlap_area(other: Mask, offset: Any = None) → int

Get the number of overlapping pixels between this mask and another.

Args

  • other : The other mask to check overlap with.
  • offset : Position offset between the masks. Defaults to (0, 0).

Returns

int : The number of overlapping solid pixels.

Get Overlap Mask

get_overlap_mask(other: Mask, offset: Any = None) → Mask

Get a mask representing the overlapping area between this mask and another.

Args

  • other : The other mask to check overlap with.
  • offset : Position offset between the masks. Defaults to (0, 0).

Returns

Mask : A new mask containing only the overlapping pixels.

Get Pixel Array

get_pixel_array(color: Any = None) → PixelArray

Convert the mask to a pixel array with the specified color.

Solid pixels become the specified color, transparent pixels become transparent.

Args

  • color : The color to use for solid pixels. Defaults to white (255, 255, 255, 255).

Returns

PixelArray : A new pixel array representation of the mask.

Raises

  • RuntimeError : If pixel array creation fails.

Get Rect

get_rect() → Rect

Get the bounding rectangle of the mask starting at (0, 0).

Invert

invert() → None

Invert all pixels in the mask.

Solid pixels become transparent and transparent pixels become solid.

Is Empty

is_empty() → bool

Check if the mask contains no solid pixels.

Returns

bool : True if the mask is empty, False otherwise.

Set At

set_at(pos: Vec2, value: bool) → None

Set the pixel value at a specific position.

Args

  • pos : The position to set.
  • value : The pixel value (True for solid, False for transparent).

Subtract

subtract(other: Mask, offset: Any = None) → None

Subtract another mask from this mask with an offset.

Removes pixels where the other mask has solid pixels.

Args

  • other : The mask to subtract.
  • offset : Position offset for the other mask. Defaults to (0, 0).