Hitbox

arcade.hitbox.calculate_hit_box_points_simple(image: Image, *args) Sequence[tuple[float | int, float | int] | Vec2][source]

Given an RGBA image, this returns points that make up a hit box around it. Attempts to trim out transparent pixels.

Parameters:

image – Image get hit box from.

arcade.hitbox.calculate_hit_box_points_detailed(image: Image, hit_box_detail: float = 4.5) Sequence[tuple[float | int, float | int] | Vec2][source]

Given an RGBA image, this returns points that make up a hit box around it. Attempts to trim out transparent pixels.

Parameters:
  • image – Image get hit box from.

  • hit_box_detail – How detailed to make the hit box. There’s a trade-off in number of points vs. accuracy.

class arcade.hitbox.base.HitBoxAlgorithm[source]

Bases:

The base class for hit box algorithms.

Hit box algorithms are intended to calculate the points which make up a hit box for a given Image. However, advanced users can also repurpose them for other tasks.

🧙 self(*args: Any, **kwds: Any) Self[source]

Shorthand allowing any instance to be used identically to the base type.

Parameters:

args

The same positional arguments as __init__

kwds:

The same keyword arguments as __init__

Returns:

A new HitBoxAlgorithm instance

cache = True

Whether points for this algorithm should be cached

property cache_name: str

A string representation of the parameters used to create this algorithm.

It will be incorporated at the end of the string returned by Texture.create_cache_name. Subclasses should override this method to return a value which allows distinguishing different configurations of a particular hit box algorithm.

calculate(image: Image, **kwargs) Sequence[tuple[float | int, float | int] | Vec2][source]

Calculate hit box points for a given image.

Warning

This method should not be made into a class method!

Although this base class does not take arguments when initialized, subclasses use them to alter how a specific instance handles image data by default.

Parameters:
  • image – The image to calculate hitbox points for

  • kwargs – keyword arguments

create_bounding_box(image: Image) Sequence[tuple[float | int, float | int] | Vec2][source]

Create points for a simple bounding box around an image. This is often used as a fallback if a hit box algorithm doesn’t manage to figure out any reasonable points for an image.

Parameters:

image – The image to create a bounding box for.

class arcade.hitbox.base.HitBox(points: Sequence[tuple[float | int, float | int] | Vec2], position: tuple[float | int, float | int] | Vec2 = (0.0, 0.0), scale: tuple[float | int, float | int] | Vec2 = (1.0, 1.0))[source]

Bases:

A basic hit box class supporting scaling.

It includes support for rescaling as well as shorthand properties for boundary values along the X and Y axes. For rotation support, use create_rotatable() to create an instance of RotatableHitBox.

Parameters:
  • points – The unmodified points bounding the hit box

  • position – The center around which the points will be offset

  • scale – The X and Y scaling factors to use when offsetting the points

property bottom: float

Calculates the bottommost adjusted y position of this hit box

create_rotatable(angle: float = 0.0) RotatableHitBox[source]

Create a rotatable instance of this hit box.

The internal PointList is transferred directly instead of deep copied, so care should be taken if using a mutable internal representation.

Parameters:

angle – The angle to rotate points by (0 by default)

get_adjusted_points() Sequence[tuple[float | int, float | int] | Vec2][source]

Return the positions of points, scaled and offset from the center.

Unlike the boundary helper properties (left, etc), this method will only recalculate the values when necessary:

  • The first time this method is called

  • After properties affecting adjusted position were changed

property left: float

Calculates the leftmost adjusted x position of this hit box

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

The raw, unadjusted points of this hit box.

These are the points as originally passed before offsetting, scaling, and any operations subclasses may perform, such as rotation.

property position: tuple[float | int, float | int] | Vec2

The center point used to offset the final adjusted positions.

property right: float

Calculates the rightmost adjusted x position of this hit box

property scale: tuple[float, float]

The X & Y scaling factors for the points in this hit box.

These are used to calculate the final adjusted positions of points.

property top: float

Calculates the topmost adjusted y position of this hit box

class arcade.hitbox.base.RotatableHitBox(points: Sequence[tuple[float | int, float | int] | Vec2], *, position: tuple[float, float] = (0.0, 0.0), angle: float = 0.0, scale: tuple[float | int, float | int] | Vec2 = (1.0, 1.0))[source]

Bases: HitBox

A hit box with support for rotation.

Rotation is separated from the basic hitbox because it is much slower than offsetting and scaling.

Parameters:
  • points – The unmodified points bounding the hit box

  • position – The translation to apply to the points

  • angle – The angle to rotate the points by

  • scale – The X and Y scaling factors

property angle: float

The angle to rotate the raw points by in degrees

get_adjusted_points() Sequence[tuple[float | int, float | int] | Vec2][source]

Return the offset, scaled, & rotated points of this hitbox.

As with HitBox.get_adjusted_points(), this method only recalculates the adjusted values when necessary.

class arcade.hitbox.bounding_box.BoundingHitBoxAlgorithm[source]

Bases: HitBoxAlgorithm

A simple hit box algorithm that returns a hit box around the entire image.

cache = False

Whether points for this algorithm should be cached

calculate(image: Image, **kwargs) Sequence[tuple[float | int, float | int] | Vec2][source]

Given an RGBA image, this returns points that make up a hit box around it without any attempt to trim out transparent pixels.

Parameters:

image – Image get hit box from.

class arcade.hitbox.simple.SimpleHitBoxAlgorithm[source]

Bases: HitBoxAlgorithm

Simple hit box algorithm. This algorithm attempts to trim out transparent pixels from an image to create a hit box.

calculate(image: Image, **kwargs) Sequence[tuple[float | int, float | int] | Vec2][source]

Given an RGBA image, this returns points that make up a hit box around it. Attempts to trim out transparent pixels.

Parameters:

image – Image get hit box from.

class arcade.hitbox.pymunk.PymunkHitBoxAlgorithm(*, detail: float | None = None)[source]

Bases: HitBoxAlgorithm

Hit box point algorithm that uses pymunk to calculate the points.

This is a more accurate algorithm generating more points. The point count can be controlled with the detail parameter.

🧙 self(*, detail: float | None = None) PymunkHitBoxAlgorithm[source]

Create a new instance with new default values

calculate(image: Image, detail: float | None = None, **kwargs) Sequence[tuple[float | int, float | int] | Vec2][source]

Given an RGBA image, this returns points that make up a hit box around it.

Parameters:
  • image – Image get hit box from.

  • detail – How detailed to make the hit box. There’s a trade-off in number of points vs. accuracy.

default_detail = 4.5

The default detail when creating a new instance.

select_largest_line_set(line_sets: PolylineSet) list[Vec2d][source]

Given a list of line sets, return the one that covers the most of the image.

Parameters:

line_sets – List of line sets.

to_points_list(image: Image, line_set: list[Vec2d]) Sequence[tuple[float | int, float | int] | Vec2][source]

Convert a line set to a list of points.

Coordinates are offset so (0,0) is the center of the image.

Parameters:
  • image – Image to trace.

  • line_set – Line set to convert.

trace_image(image: Image) PolylineSet[source]

Trace the image and return a :py:class:~collections.abc.Sequence` of line sets.

Important

The image mode must be "RGBA"!

The returned object will be a pymunk PolylineSet. Each list inside it will contain points as pymunk.vec2d.Vec2d instances. These lists may represent:

  • the outline of the image’s contents

  • the holes in the image

When this method returns more than one line set, it’s important to pick the one which covers the largest portion of the image.

Parameters:

image – A PIL.Image.Image to trace.

Returns:

A pymunk object which is a Sequence of PolylineSet of line sets.