Types
- class arcade.types.HasAddSubMul(*args, **kwargs)[source]
Bases:
Protocol
[_T_contra
,_T_co
]Matches types which work with
arcade.math.lerp()
.
- class arcade.types.TiledObject(shape: Point | PointList | tuple[int, int, int, int], properties: Properties | None = None, name: str | None = None, type: str | None = None)[source]
Bases:
NamedTuple
Object in a tilemaps
- 🧙 repr(self)
Return a nicely formatted representation string
- class arcade.types.vector_like.AnchorPoint[source]
Bases:
Common anchor points as constants in UV space.
Each is a
Vec2
with axis values between0.0
and1.0
. They can be used as arguments toRect.uv_to_position
to help calculate:a pixel offset inside a
Rect
an absolute screen positions in pixels
Advanced users may also find them useful when working with shaders.
- BOTTOM_CENTER = (0.5, 0.0)
- BOTTOM_LEFT = (0.0, 0.0)
- BOTTOM_RIGHT = (1.0, 0.0)
- CENTER = (0.5, 0.5)
- CENTER_LEFT = (0.0, 0.5)
- CENTER_RIGHT = (1.0, 0.5)
- TOP_CENTER = (0.5, 1.0)
- TOP_LEFT = (0.0, 1.0)
- TOP_RIGHT = (1.0, 1.0)
- class arcade.types.color.Color(r: int, g: int, b: int, a: int = 255)[source]
Bases:
tuple
[int
,int
,int
,int
]An RGBA color as a
tuple
subclass.# The alpha channel value defaults to 255 >>> from arcade.types import Color >>> Color(255, 0, 0) Color(r=255, g=0, b=0, a=255)
If you prefer specifying color with another format, the class also provides number of helper methods for the most common RGB and RGBA formats:
Regardless of the source format, all color channels must be between 0 and 255, inclusive. If any channel is outside this range, creation will fail with a
ByteRangeError
, which is a type ofValueError
.Note
This class does not currently support HSV or other color spaces.
If you need these, you may want to try the following:
- Parameters:
r – the red channel of the color, between 0 and 255, inclusive
g – the green channel of the color, between 0 and 255, inclusive
b – the blue channel of the color, between 0 and 255, inclusive
a – the alpha or transparency channel of the color, between 0 and 255, inclusive
- classmethod from_gray(brightness: int, a: int = 255) Self [source]
Create a gray
Color
of the givenbrightness
.>>> off_white = Color.from_gray(220) >>> print(off_white) Color(r=220, g=220, b=220, a=255) >>> half_opacity_gray = Color.from_gray(128, 128) >>> print(half_opacity_gray) Color(r=128, g=128, b=128, a=128)
- Parameters:
brightness – How bright the new gray should be
a – a transparency value, fully opaque by default
- classmethod from_hex_string(code: str) Self [source]
Create a
Color
from a hex code of 3, 4, 6, or 8 digits.# RGB color codes are assumed to have an alpha value of 255 >>> Color.from_hex_string("#FF00FF") Color(r=255, g=0, b=255, a=255) # You can use eight-digit RGBA codes to specify alpha >>> Color.from_hex_string("#FF007F") Color(r=255, g=0, b=255, a=127) # For brevity, you can omit the # and use RGB shorthand >>> Color.from_hex_string("FFF") Color(r=255, g=255, b=255, a=255) # Lower case and four-digit RGBA shorthand are also allowed >>> Color.from_hex_string("ff0a") Color(r=255, g=255, b=0, a=170)
Aside from the optional leading
#
, thecode
must otherwise be a valid CSS hexadecimal color code. It will be processed as follows:Any leading
'#'
characters will be stripped3 and 4 digit shorthands are expanded by multiplying each digit’s value by 16
6 digit RGB hex codes assume 255 as their alpha values
8 digit RGBA hex codes are converted to byte values and passed directly to a new
Color
All other lengths will raise a
ValueError
To learn more, please see:
The CSS hex color specification
- Parameters:
code – A CSS hex color string which may omit the leading
#
character.
- classmethod from_iterable(iterable: Iterable[int]) Self [source]
Create a
Color
from an iterable of 3 or 4 channel values.If an iterable is already a
Color
instance, it will be returned unchanged. Otherwise, it must unpack as 3 or 4int
values between0
and255
, inclusive.If an iterable has no less than 3 or more than 4 elements, this method raises a
ValueError
. The function will attempt to create a new Color instance. The usual rules apply, i.e.: all values must be between 0 and 255, inclusive.Note
This is a more readable alternative to
*
unpacking.If you are an advanced user who needs brevity or higher performance, you can unpack directly into
Color
:>>> rgb_green_tuple = (0, 255, 0) >>> Color(*rgb_green_tuple, 127) Color(r=0, g=255, b=0, a=127)
- Parameters:
iterable – An iterable which unpacks to 3 or 4 elements, each between 0 and 255, inclusive.
- classmethod from_normalized(color_normalized: tuple[float, float, float, float]) Self [source]
Convert normalized float RGBA to an RGBA
Color
.If any input channels aren’t normalized (between
0.0
and1.0
), this method will raise aNormalizedRangeError
you can handle as aValueError
.Examples:
>>> Color.from_normalized((1.0, 0.0, 0.0, 1.0)) Color(r=255, g=0, b=0, a=255) >>> normalized_half_opacity_green = (0.0, 1.0, 0.0, 0.5) >>> Color.from_normalized(normalized_half_opacity_green) Color(r=0, g=255, b=0, a=127)
- Parameters:
color_normalized – A tuple of 4 normalized (
0.0
to1.0
) RGBA values.
- classmethod from_uint24(color: int, a: int = 255) Self [source]
Convert an unsigned 24-bit integer to a
Color
.# The alpha channel is assumed to be 255 >>> Color.from_uint24(0x010203) Color(r=1, g=2, b=3, a=255) # Specify alpha via the a keyword argument >>> Color.from_uint24(0x010203, a=127) Color(r=1, g=2, b=3, a=127) # The maximum value as decimal >>> Color.from_uint24(16777215) Color(r=255, g=255, b=255, a=255)
To convert from an RGBA value as a 32-bit integer, see
from_uint32()
.- Parameters:
color – a 3-byte
int
between0
and16777215
(0xFFFFFF
)a – An alpha value to use between 0 and 255, inclusive.
- classmethod from_uint32(color: int) Self [source]
Convert an unsigned 32-bit integer to a
Color
.The four bytes are interpreted as R, G, B, A:
>>> Color.from_uint32(0x01020304) Color(r=1, g=2, b=3, a=4) # The maximum value as a decimal integer >>> Color.from_uint32(4294967295) Color(r=255, g=255, b=255, a=255)
To convert from an RGB value as a 24-bit integer, see
from_uint24()
.- Parameters:
color – An
int
between0
and4294967295
(0xFFFFFFFF
)
- property normalized: tuple[float, float, float, float]
Convert the
Color
to a tuple of 4 normalized floats.>>> arcade.color.WHITE.normalized (1.0, 1.0, 1.0, 1.0) >>> arcade.color.BLACK.normalized (0.0, 0.0, 0.0, 1.0) >>> arcade.color.TRANSPARENT_BLACK.normalized (0.0, 0.0, 0.0, 0.0)
- classmethod random(r: int | None = None, g: int | None = None, b: int | None = None, a: int | None = None) Self [source]
Create a
Color
by randomizing all unspecified channels.All arguments are optional. If you specify a channel’s value, it will be used in the new color instead of randomizing:
# Randomize all channels >>> Color.random() Color(r=35, g=145, b=4, a=200) # Create a random opaque color >>> Color.random(a=255) Color(r=25, g=99, b=234, a=255)
- Parameters:
r – Specify a value for the red channel
g – Specify a value for the green channel
b – Specify a value for the blue channel
a – Specify a value for the alpha channel
- replace(r: int | None = None, g: int | None = None, b: int | None = None, a: int | None = None) Color [source]
Create a
Color
with specified values replaced in a predefined color.# Color with alpha with a predefined constant >>> arcade.color.BLUE.replace(a = 100) Color(r = 0, g = 0, b = 255, a = 100)
- Parameters:
r – Specify a value for the red channel
g – Specify a value for the green channel
b – Specify a value for the blue channel
a – Specify a value for the alpha channel
- property rgb: tuple[int, int, int]
Return only a color’s RGB components.
This is syntactic sugar for slice indexing as below:
>>> from arcade.color import WHITE >>> WHITE[:3] (255, 255, 255) # Equivalent but slower than the above >>> (WHITE.r, WHITE.g, WHITE.b) (255, 255, 255)
To reorder the channels as you retrieve them, see
swizzle()
.
- swizzle(order: str) tuple[int, ...] [source]
Get a
tuple
of channel values in the givenorder
.This imitates GLSL’s swizzling, a way to reorder vector values:
>>> from arcade.types import Color >>> color = Color(180, 90, 0, 255) >>> color.swizzle("abgr") (255, 0, 90, 180)
Unlike GLSL, this function allows upper case.
>>> from arcade.types import Color >>> color = Color(180, 90, 0, 255) # You can repeat channels and use upper case >>> color.swizzle("ABGRa") (255, 0, 90, 180, 255)
Note
The
order
is case-insensitive.If you were hoping
order
would also specify how to convert data, you may instead be looking for Python’s built-instruct
andarray
modules.- Parameters:
order – A string of channel names as letters in
"RGBArgba"
with repeats allowed.- Returns:
A tuple of channel values in the given
order
.
- class arcade.types.rect.RectKwargs[source]
Bases:
TypedDict
Annotates a plain
dict
ofRect
arguments.This is only meaningful as a type annotation during type checking. For example, the
Rect.kwargs
property returns an ordinary will actually be adict
ofRect
field names tofloat
values.To learn more, please see:
- class arcade.Rect(left: float, right: float, bottom: float, top: float, width: float, height: float, x: float, y: float)[source]
Bases:
NamedTuple
A rectangle, with several convenience properties and functions.
This object is immutable by design. It provides no setters, and is a NamedTuple subclass.
Attempts to implement all Rectangle functions used in the library, and to be a helpful tool for developers storing/manipulating rectangle and rectangle-like constructs.
Rectangles cannot rotate by design, since this complicates their implementation a lot.
You probably don’t want to create one of these directly, and should instead use a helper method, like
LBWH()
,LRBT()
,XYWH()
, orViewport()
.You can also use
from_kwargs()
to create a Rect from keyword arguments.- 🧙 self & other: Rect Rect | None [source]
Shorthand for
rect.intersection(other)
.- Parameters:
other – Another
Rect
instance.
- 🧙 point: tuple[float | int, float | int] | Vec2 | Any in self bool [source]
Shorthand for
rect.point_in_rect(point)
.
- 🧙 self | other: Rect Rect [source]
Shorthand for
rect.union(other)
.- Parameters:
other – Another
Rect
instance.
- 🧙 repr(self)
Return a nicely formatted representation string
- align_bottom(value: float | int) Rect [source]
Returns a new
Rect
, which is aligned to the bottom at value.
- align_center(value: tuple[float | int, float | int] | Vec2) Rect [source]
Returns a new
Rect
, which is aligned to the center x and y at value.
- align_left(value: float | int) Rect [source]
Returns a new
Rect
, which is aligned to the left at value.
- align_right(value: float | int) Rect [source]
Returns a new
Rect
, which is aligned to the right at value.
- align_top(value: float | int) Rect [source]
Returns a new
Rect
, which is aligned to the top at value.
- at_position(position: tuple[float | int, float | int] | Vec2) Rect [source]
Returns a new
Rect
which is moved to put position at its center.
- clamp_height(min_height: float | int | None = None, max_height: float | int | None = None, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Return a
Rect
that has a height between min_height and max_height, positioned at the current position and anchored to a point (default center.)
- clamp_size(min_width: float | int | None = None, max_width: float | int | None = None, min_height: float | int | None = None, max_height: float | int | None = None, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Get a new clamped-size rectangle at the same position and anchored at
anchor_point
.This combines the effects of
clamp_width()
andclamp_height()
into one call.
- clamp_width(min_width: float | int | None = None, max_width: float | int | None = None, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Return a
Rect
constrained to the passed dimension.It will be created as follows:
Its
width
will be between any providedmin_width
andmax_width
It will be positioned at the current position using the passed
anchor
- distance_from_bounds(point: tuple[float | int, float | int] | Vec2) float [source]
Returns the point’s distance from the boundary of this rectangle.
- classmethod from_kwargs(**kwargs: float | int) Rect [source]
Creates a new Rect from keyword arguments. Throws ValueError if not enough are provided.
Expected forms are:
LRBT (providing
left
,right
,bottom
, andtop
)LBWH (providing
left
,bottom
,width
, andheight
)XYWH (providing
x
,y
,width
, andheight
)
- get_relative_to_anchor(point: tuple[float | int, float | int] | Vec2, anchor: Vec2 = (0.5, 0.5)) Vec2 [source]
Convert a point to a relative offset from the anchor point.
- Parameters:
point – The point to make relative.
anchor – The anchor point to make the point relative to.
- height: float
The total height of the rectangle along the Y axis. To get the rectangle’s
width
as well, usesize
.
- intersection(other: Rect) Rect | None [source]
Return a
Rect
of the overlap if any exists.If the two
Rect
instances do not intersect, this method will returnNone
instead.- Parameters:
other – Another
Rect
instance.
- property kwargs: RectKwargs
Get this rectangle as a
dict
of field names to values.Many data formats have corresponding Python modules with write support. Such modules often one or more functions which convert a passed
dict
to astr
or write the result of such a conversion to a file.For example, the built-in
json
module offers the following functions on all Python versions currently supported by Arcade:Function
Summary
Useful For
Write a
dict
to a fileSaving game progress or edited levels
Calls to a Web API
Note
The return value is an ordinary
dict
.Although the return type is annotated as a
RectKwargs
, it is only meaningful when type checking. Seetyping.TypedDict
to learn more.
- property lbwh: tuple[float | int, float | int, float | int, float | int]
Provides a tuple in the format of (left, bottom, width, height).
- property lbwh_int: tuple[int, int, int, int]
Provides a tuple in the format of (left, bottom, width, height), casted to ints.
- property lrbt: tuple[float | int, float | int, float | int, float | int]
Provides a tuple in the format of (left, right, bottom, top).
- property lrbt_int: tuple[int, int, int, int]
Provides a tuple in the format of (left, right, bottom, top), casted to ints.
- max_size(width: float | int | None = None, height: float | int | None = None, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Return a
Rect
that is at most size width by height, positioned at the current position and anchored to a point (default center.)
- min_size(width: float | int | None = None, height: float | int | None = None, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Return a
Rect
that is at least size width by height, positioned at the current position and anchored to a point (default center.)
- move(dx: float | int = 0.0, dy: float | int = 0.0) Rect [source]
Returns a new
Rect
which is moved by dx in the x-direction and dy in the y-direction.
- overlaps(other: Rect) bool [source]
Returns
True
if other overlaps withself
.- Parameters:
other – Another
Rect
instance.
- point_in_bounds(point: tuple[float | int, float | int] | Vec2) bool [source]
Returns
True
ifpoint
is inside this rectangle excluding the boundaries.
- point_in_rect(point: tuple[float | int, float | int] | Vec2) bool [source]
Returns
True
ifpoint
is inside this rectangle.
- point_on_bounds(point: tuple[float | int, float | int] | Vec2, tolerance: float) bool [source]
Returns
True
ifpoint
is withintolerance
of the bounds.The
point
’s distance from the bounds is computed by throughdistance_from_bounds()
.- Parameters:
point – The point to check.
tolerance – The maximum distance the point can be from the bounds.
- position_to_uv(point: tuple[float | int, float | int] | Vec2) Vec2 [source]
Convert a point to UV space values inside the rectangle.
This is like a pair of ratios which measure how far the
point
is from the rectangle’sbottom_left()
up toward itstop_right()
along each axis.Warning
This method does not clamp output!
Since
point
is absolute pixels, one or both axes of the returnedVec2
can be:less than
0.0
greater than
1.0
Each axis of the return value measures how far into the rectangle’s
size
thepoint
is relative to thebottom_left()
:# consult the diagram below Vec2( (point.x - rect.left) / rect.width, (point.y - rect.bottom) / rect.height )
|------- rect.width ------| The rectangle (rect.top_right) +-------------------------T --- | | | - - - - - - - P (Point x, y)| | | | | rect.height | | | | | y | | | | B----------|--------------+ --- | (rect.bottom_right) | O----- x -----|
- Parameters:
point – A point relative to the rectangle’s
bottom_left()
corner.
- resize(width: float | int | None = None, height: float | int | None = None, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Returns a new
Rect
at the current Rect’s position, but with a new width and height, anchored at a point (default center.)
- scale(new_scale: float | int, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Returns a new
Rect
scaled by a factor ofnew_scale
, anchored at a point (default center.)
- scale_axes(new_scale: tuple[float | int, float | int] | Vec2, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Return a new
Rect
scaled by a factor of new_scale.x in the width and new_scale.y in the height, anchored at a point (default center.)
- to_points() tuple[Vec2, Vec2, Vec2, Vec2] [source]
Return a new
tuple
of this rectangle’s corner points.The points will be ordered as follows:
- uv_to_position(uv: tuple[float | int, float | int] | Vec2) Vec2 [source]
Convert a point in UV-space to a point within the rectangle.
The
uv
is a pair of ratios which describe how far a point extends across the rectangle’swidth
andheight
from thebottom_left
toward itstop_right
.Warning
This method does not clamp output!
Since one or both of
uv
’s components can be less than0.0
or greater than1.0
, the returned point can fall outside the rectangle.The following can be used as arguments to this function:
Values in
AnchorPoint
Returned values from
position_to_uv()
Rescaled input data from controllers
- Parameters:
uv – A pair of ratio values describing how far a a point falls from a rectangle’s
bottom_left
toward itstop_right
.
- width: float
The total width of the rectangle along the X axis. To get the rectangle’s
height
well, usesize
- property xyrr: tuple[float | int, float | int, float | int, float | int]
Provides a tuple in the format of (x, y, width / 2, height / 2).
- property xyrr_int: tuple[float | int, float | int, float | int, float | int]
Provides a tuple in the format of (x, y, width / 2, height / 2), casted to ints.
- property xywh: tuple[float | int, float | int, float | int, float | int]
Provides a tuple in the format of (x, y, width, height).
- arcade.LRBT(left: float | int, right: float | int, bottom: float | int, top: float | int) Rect [source]
Creates a new
Rect
from left, right, bottom, and top parameters.
- arcade.LBWH(left: float | int, bottom: float | int, width: float | int, height: float | int) Rect [source]
Creates a new
Rect
from left, bottom, width, and height parameters.
- arcade.XYWH(x: float | int, y: float | int, width: float | int, height: float | int, anchor: Vec2 = (0.5, 0.5)) Rect [source]
Creates a new
Rect
from x, y, width, and height parameters, anchored at a relative point (default center).
- arcade.types.rect.XYRR(x: float | int, y: float | int, half_width: float | int, half_height: float | int) Rect [source]
Creates a new
Rect
from center x, center y, half width, and half height parameters. This is mainly used by OpenGL.
- arcade.types.rect.Viewport(left: int, bottom: int, width: int, height: int) Rect [source]
Creates a new
Rect
from left, bottom, width, and height parameters, restricted to integers.
- class arcade.types.box.BoxKwargs[source]
Bases:
TypedDict
Annotates a plain
dict
ofBox
arguments.This is only meaningful as a type annotation during type checking. For example, the
Box.kwargs
property returns an ordinary will actually be adict
ofBox
field names tofloat
values.To learn more, please see:
- class arcade.types.box.Box(left: float, right: float, bottom: float, top: float, near: float, far: float, width: float, height: float, depth: float, x: float, y: float, z: float)[source]
Bases:
NamedTuple
A 3D box, with several convenience properties and functions.
Important
Boxes are immutable and axis-aligned bounding prisms!
As
NamedTuple
subclasses, they cannot rotate and have no setters. This keeps their design simple and efficient. To rotate a box’s points in 3D, useto_points()
with a 3D math library of your choice.To create a box, the helper class methods are usually the best choice:
- 🧙 self & other: Box Box | None [source]
Shorthand for
Box.intersection(other)
.- Parameters:
other – Another
Box
instance.
- 🧙 point: tuple[float | int, float | int, float | int] | Vec3 | Any in self bool [source]
Shorthand for
Box.point_in_box(point)
.
- 🧙 self | other: Box Box [source]
Shorthand for
Box.union(other)
.- Parameters:
other – Another
Box
instance.
- 🧙 repr(self)
Return a nicely formatted representation string
- at_position(position: tuple[float | int, float | int, float | int] | Vec3) Box [source]
Returns a new
Box
which is moved to put position at its center.
- property bottom_face_center: Vec3
Returns a
Rect
representing the center of the bottom face of the box.
- property bottom_left_near: Vec3
Returns a
Vec3
representing the bottom-left-near corner of the box.
- property bottom_right_far: Vec3
Returns a
Vec3
representing the bottom-right-far corner of the box.
- property bottom_right_near: Vec3
Returns a
Vec3
representing the bottom-right-near corner of the box.
- intersection(other: Box) Box | None [source]
Return a
Box
of the overlap if any exists.If the two
Box
instances do not intersect, this method will returnNone
instead.- Parameters:
other – Another
Box
instance.
- property lbnwhd: tuple[float | int, float | int, float | int, float | int, float | int, float | int]
Provides a tuple in the form (left, bottom, near, width, height, depth).
- property left_face_center: Vec3
Returns a
Rect
representing the center of the left face of the box.
- property lrbtnf: tuple[float | int, float | int, float | int, float | int, float | int, float | int]
Provides a tuple in the form (left, right, bottom, top, near, far).
- move(dx: float | int = 0.0, dy: float | int = 0.0, dz: float | int = 0.0) Box [source]
Returns a new
Box
which is moved by dx in the x-direction,`dy` in the y-direction, and dz in the z-direction.
- property near_face_center: Vec3
Returns a
Rect
representing the center of the near face of the box.
- overlaps(other: Box) bool [source]
Returns
True
if other overlaps withself
.- Parameters:
other – Another
Box
instance.
- point_in_box(point: tuple[float | int, float | int, float | int] | Vec3) bool [source]
True
if the point is in or touching the box, otherwiseFalse
.- Parameters:
point – A 3D point.
- property right_face_center: Vec3
Returns a
Rect
representing the center of the right face of the box.
- to_points() tuple[Vec3, Vec3, Vec3, Vec3, Vec3, Vec3, Vec3, Vec3] [source]
Return a new
tuple
of this box’s corners as 3D points.The points will be ordered as follows:
- arcade.types.box.XYZWHD(x: float, y: float, z: float, width: float, height: float, depth: float) Box [source]
Creates a new
Box
from center x, center y, center z, width, height, and depth parameters.