Full API Documentation<a class="headerlink" href="#full-api-documentation" title="Permalink to this heading">#

Returns:

If save was successful.

clone()[source]#

Clones the current raster.

Return type:: Raster
Returns:: The cloned raster.

fixed_update()#: The physics function for a component.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

singular: bool#: Whether multiple components of the same type are allowed on a game object.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

Image#

class Image(path, af=False, scale=(1, 1), offset=(0, 0), rot_offset=0, z_index=0, hidden=False)[source]#

An image is a raster subclass that generates the surface from an image file.

Parameters:

path (str) -- The path to the file.
af (bool) -- Whether to use anisotropic filtering. Defaults to False.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the Raster. Defaults to (1, 1).
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the Raster. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the Raster. Defaults to 0.
z_index (int) -- The z-index of the Raster. Defaults to 0.
hidden (bool) -- Whether to hide the Raster. Defaults to False.

property af: bool#

Whether to use anisotropic filtering.

Return type:: bool

blit(other, src_rect=None, dst=(0, 0))#

Blits (merges / copies) another Surface onto this one.

Parameters:

other (Raster) -- The Surface to blit onto this one.
src_rect (Optional[tuple[int, int, int, int]]) -- The area (center_x, center_y, width, height) to crop from the source surface (other). Defaults to the whole surface.
dst (UnionType[Vector, tuple[int, int]]) -- The position to place the other surface. Defaults to (0, 0).

Note

Will not stretch the other surface to fit the destination rectangle.

clear()#: Clears the surface.

draw(camera)#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

draw_circle(center, radius, border=None, border_thickness=1, fill=None, aa=False, blending=True)#

Draws a circle on the surface.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The center of the circle.
radius (int) -- The radius of the circle.
border (Optional[Color]) -- The border color of the circle. Defaults to None.
border_thickness (int) -- The thickness of the border. Defaults to 1.
fill (Optional[Color]) -- The fill color of the circle. Set to None for no fill. Defaults to None.
aa (bool) -- Whether to use anti-aliasing. Defaults to False.
blending (bool) -- Whether to use blending. Defaults to False.

draw_line(start, end, color=Color.black, aa=False, thickness=1, blending=True)#

Draws a line on the surface.

Parameters:

start (UnionType[Vector, tuple[float, float]]) -- The start of the line.
end (UnionType[Vector, tuple[float, float]]) -- The end of the line.
color (Color) -- The color of the line. Defaults to black.
aa (bool) -- Whether to use anti-aliasing. Defaults to False.
thickness (int) -- The thickness of the line. Defaults to 1.
blending (bool) -- Whether to use blending. Defaults to False.

draw_poly(points, center=(0, 0), border=None, border_thickness=1, fill=None, aa=False, blending=True)#

Draws a polygon on the surface.

Parameters:

points (UnionType[list[Vector], list[tuple[float, float]]]) -- The points of the polygon.
center (UnionType[Vector, tuple[float, float]]) -- The center of the polygon.
border (Optional[Color]) -- The border color of the polygon. Defaults to None.
border_thickness (int) -- The thickness of the border. Defaults to 1.
fill (Optional[Color]) -- The fill color of the polygon. Set to None for no fill. Defaults to None.
aa (bool) -- Whether to use anti-aliasing. Defaults to False.
blending (bool) -- Whether to use blending. Defaults to False.

draw_rect(center, dims, border=Color.black, border_thickness=1, fill=None, blending=True)#

Draws a rectangle on the surface.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The top left corner of the rectangle.
dims (UnionType[Vector, tuple[float, float]]) -- The dimensions of the rectangle.
border (Color) -- The border color of the rectangle. Defaults to black.
border_thickness (int) -- The thickness of the border. Defaults to 1.
fill (Optional[Color]) -- The fill color of the rectangle. Set to None for no fill. Defaults to None.
blending (bool) -- Whether to use blending. Defaults to False.

fill(color)#

Fill the surface with a color.

Parameters:: color (Color) -- The color to fill with.

fixed_update()#: The physics function for a component.

flip_anti_diagonal()#: Flips the surface along the anti-diagonal.

flip_x()#: Flips the raster along the x-axis.

flip_y()#: Flips the raster along the y-axis.

get_alpha()#

Gets the surface wide alpha.

Return type:: int

get_pixel(pos)#

Gets the color of a pixel on the surface.

Parameters:: pos (UnionType[Vector, tuple[float, float]]) -- The position of the pixel.
Return type:: Color
Returns:: The color of the pixel.

get_rect()#

Generates the rectangular bounding box of the raster.

Return type:: Rectangle
Returns:: The Rectangle hitbox that bounds the raster.

get_size()#

Gets the current size of the surface.

Return type:: Vector
Returns:: The size of the surface

save_as(filename, path='./', extension='png', save_to_temp_path=False, quality=100)#

Save the raster to a file.

Parameters:

filename (str) -- The name of the file to save to.
path (str) -- Path to output folder.
extension (str) -- The extension to save the file as. (png, jpg, bmp supported)
save_to_temp_path (bool) -- Whether to save the file to a temporary path (i.e. MEIPASS used in exe).
quality (int) -- The quality of the jpg 0-100 (only used for jpgs).

Return type:

Returns:

If save was successful.

property scale: Vector#

The scale of the raster.

Return type:: Vector

set_alpha(new)#

Sets surface wide alpha.

Parameters:: new (int) -- The new alpha. (value between 0-255)

set_colorkey(color)#: Sets the colorkey of the surface. :type color: Color :param color: Color to set as the colorkey.

set_pixel(pos, color=Color.black, blending=True)#

Draws a point on the surface.

Parameters:

pos (UnionType[Vector, tuple[float, float]]) -- The position to draw the point.
color (Color) -- The color of the point. Defaults to black.
blending (bool) -- Whether to use blending. Defaults to False.

setup()#: The setup function for a component.

switch_color(color, new_color)#

Switches a color in the surface.

Parameters:

color (Color) -- The color to switch.
new_color (Color) -- The new color to switch to.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

singular: bool#: Whether multiple components of the same type are allowed on a game object.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

clone()[source]#

Clones the current raster.

Return type:: Image
Returns:: The cloned raster.

Text#

A text component.

class Text(text='', font=Font(), justify='left', anchor=(0, 0), width=0, af=True, offset=(0, 0), rot_offset=0, z_index=0, hidden=False)[source]#

A text component. Add this to game objects or UI elements to give them text. Takes a font object to render the text.

Parameters:

text (str) -- The text to display. Defaults to "".
font (Font) -- The font to use. Defaults to Font().
justify (Literal['left', 'center', 'right']) -- The justification of the text. Defaults to "left".
anchor (UnionType[Vector, tuple[float, float]]) -- The anchor of the text. The zero vector means it is centered. x component is whether to shift left, none, or right (-1, 0, 1). y component is whether to shift top, none, or bottom (-1, 0, 1). Defaults to Vector(0, 0).
width (int) -- The width of the text. Defaults to 0.
af (bool) -- Whether to use anisotropic filtering. Defaults to True.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the text from the game object. Defaults to Vector(0, 0).
rot_offset (float) -- The rotation offset of the text from the game object. Defaults to 0.
z_index (int) -- The z index of the text. Defaults to 0.
hidden (bool) -- Whether the text is hidden. Defaults to False.

anchor: Vector#

The anchor vector of the text.

This controls the position of the text relative to the game object. Is a vector where the x value controls the x anchor and the y value controls the y anchor. The values for each can be either -1, 0 or 1. This offset the text around the game object center.

Example

An anchor of Vector(0, 0) will center the text on the game object. An anchor of Vector(1, 1) will move the text so that it's top left corner is at the game object's center.

property af: bool#

Whether to use anisotropic filtering.

Return type:: bool

property text: str#

The text of the Text.

Return type:: str

property justify: Literal['left', 'center', 'right']#

The justification of the text.

Can be one of: "left", "center", "right".

Return type:: Literal['left', 'center', 'right']

fixed_update()#: The physics function for a component.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

singular: bool#: Whether multiple components of the same type are allowed on a game object.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

property width: int#

The maximum width of the text. Will automatically wrap the text. Use -1 to disable wrapping.

Return type:: int

update()[source]#: The update function for a component.

draw(camera)[source]#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

clone()[source]#

Clones the text component.

Return type:: Text

Button#

A button component that can be used in UI or to detect mouse presses in an area.

class Button(width=10, height=10, onclick=None, onrelease=None, onhover=None, onexit=None, offset=(0, 0), rot_offset=0, z_index=0, hidden=False)[source]#

A Button component. Add this to game objects or UI elements to give them clickable areas.

Parameters:

width (int) -- The width of the button. Defaults to 10.
height (int) -- The height of the button. Defaults to 10.
onclick (Optional[Callable]) -- The function to call when the button is clicked. Defaults to lambda: None.
onrelease (Optional[Callable]) -- The function to call when the button is released. Defaults to lambda: None.
onhover (Optional[Callable]) -- The function to call when the mouse enters the button. Defaults to lambda: None.
onexit (Optional[Callable]) -- The function to call when the mouse exits the button. Defaults to lambda: None.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the button from the game object. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the button from the game object. Defaults to 0.
z_index (int) -- The z-index of the button. Defaults to 0.
hidden (bool) -- Whether the button is hidden or not. Defaults to False.

dims: Vector#: The dimensions of the button.

pressed: bool#: Whether the button is currently pressed.

hover: bool#: Whether the mouse is hovering over the button.

onclick: Callable#: The function to call when the button is clicked.

draw(camera)#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

fixed_update()#: The physics function for a component.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

onrelease: Callable#: The function to call when the button is released.

singular: bool#: Whether multiple components of the same type are allowed on a game object.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

onhover: Callable#: The function to call when the mouse enters the button.

onexit: Callable#: The function to call when the mouse exits the button.

update()[source]#: The update function for buttons.

clone()[source]#

Clones the component.

Return type:: Button

Animation#

This is the animation component module for game objects.

class Animation(scale=(1, 1), fps=24, af=False, flipx=False, flipy=False, alpha=255, offset=(0, 0), rot_offset=0, z_index=0, hidden=False)[source]#

Animations are a series of images that update automatically in accordance with parameters.

Parameters:

scale (UnionType[Vector, tuple[float, float]]) -- The scale of the animation. Defaults to (1, 1).
fps (int) -- The frames per second of the animation. Defaults to 24.
af (bool) -- Whether to use anisotropic filtering on the animation. Defaults to False.
flipx (bool) -- Whether to flip the animation horizontally. Defaults to False.
flipy (bool) -- Whether to flip the animation vertically. Defaults to False.
alpha (int) -- The alpha of the animation. Defaults to 255.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the animation from the game object. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the animation from the game object. Defaults to 0.
z_index (int) -- The z-index of the animation. Defaults to 0.
hidden (bool) -- Whether the animation is hidden. Defaults to False.

singular: bool#: Whether multiple components of the same type are allowed on a game object.

default_state: str#: The key of the default state.

current_state: str#: The key of the current state.

animation_frames_left: int#: The number of animation frames left.

loop: bool#: Whether the animation should loop.

scale: Vector#: The scale of the animation.

af: bool#: Whether to enable anisotropic filtering.

flipx: bool#: Whether to flip the animation along the x axis.

flipy: bool#: Whether to flip the animation along the y axis.

alpha: int#: The alpha of the animation.

fixed_update()#: The physics function for a component.

property fps#: The fps of the animation.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

property current_frame: int#

The current frame that the animation is on.

Return type:: int

anim_frame()[source]#

The current animation frame.

Return type:: Surface

set_state(new_state, loop=False, freeze=-1)[source]#

Set the current animation state.

Parameters:

new_state (str) -- The key of the new current state.
loop (bool) -- Whether to loop the state. Defaults to False.
freeze (int) -- Freezes the animation once the specified frame is reached (No animation). Use -1 to never freeze. Defaults to -1.

Raises:

KeyError -- The new_state key is not in the initialized states.

reset()[source]#: Reset the animation state back to the first frame.

add(state_name, images)[source]#

Adds a state to the animation.

Parameters:

state_name (str) -- The key used to reference this state.
images (list[Surface]) -- A list of images to use as the animation.

add_folder(state_name, path, recursive=True)[source]#

Adds a state from a folder of images. Directory must be solely comprised of images.

Parameters:

state_name (str) -- The key used to reference this state.
path (str) -- The relative path to the folder you wish to import
recursive (bool) -- Whether it will import an animation shallowly or recursively. Defaults to True.

add_spritesheet(state_name, spritesheet, from_coord=(0, 0), to_coord=(0, 0))[source]#

Adds a state from a spritesheet. Will include all sprites from the from_coord to the to_coord.

Parameters:

state_name (str) -- The key used to reference this state.
spritesheet (Spritesheet) -- The spritesheet to use.
from_coord (UnionType[Vector, tuple[float, float]]) -- The grid coordinate of the first frame. Defaults to (0, 0).
to_coord (UnionType[Vector, tuple[float, float]]) -- The grid coordinate of the last coord. Defaults to (0, 0).

Example

animation.add_spritesheet("idle", spritesheet, Vector(0, 0), Vector(1, 3))
# This will add the frames (0, 0) to (0, size) and (1, 0) to (1, 3) inclusive to the animation
# with the state name "idle".

animation.add_spritesheet("idle", spritesheet, to_coord=spritesheet.end)
# This will just load from the start to the end of the spritesheet.

update()[source]#: Steps the animation forwards.

draw(camera)[source]#: Draws the animation frame.

clone()[source]#

Clones the animation.

Return type:: Animation

Spritesheet#

Utility class for loading spritesheets.

class Spritesheet(path, sprite_size=(32, 32), grid_size=None)[source]#

A spritesheet from the filesystem.

Parameters:

path (str) -- The relative path to the spritesheet.
sprite_size (UnionType[Vector, tuple[float, float]]) -- The size of each sprite in the spritesheet. Defaults to (32, 32).
grid_size (Union[Vector, tuple[float, float], None]) -- The size of the grid of sprites in the spritesheet. Set to None to automatically determine the grid size. Defaults to None.

Raises:

IndexError -- If user does not load the entire sheet.

property grid_size: Vector#

The size of the spritesheet grid (readonly).

Return type:: Vector

property sprite_size: Vector#

The size of each sprite (readonly).

Return type:: Vector

property sheet: Surface#

The actual spritesheet sprite (readonly).

Return type:: Surface

property sprites: list[list[rubato.utils.rendering.surface.Surface]]#

The list of all the sprites as sprites (readonly).

Return type:: list[list[Surface]]

property end#: The end indexes of the Spritesheet as a vector.

Example

You can use spritesheet.get(*spritesheet.end) to get the final Sprite

get(x, y)[source]#

Gets the Sprite at the corresponding grid coordinate of the spritesheet.

Parameters:

x (int) -- The x grid coordinate.
y (int) -- The y grid coordinate.

Raises:

IndexError -- One or both of the coordinates are out of range of the spritesheet's size.

Return type:

Surface

Returns:

The Sprite at the corresponding coordinate.

static from_folder(path, sprite_size, default_state=None, recursive=True)[source]#

Creates an Animation from a folder of spritesheets. Directory must be comprised solely of spritesheets. Added alphabetically. Default is the first sheet loaded.

Parameters:

path (str) -- The relative path to the folder you wish to import
sprite_size (UnionType[Vector, tuple[float, float]]) -- The size of a single sprite in your spritesheet, should be the same in all imported sheets.
default_state (Optional[str]) -- Sets the default state of the animation.
recursive (bool) -- Whether it will import an animation shallowly or recursively. Defaults to True.

Returns:

the animation loaded from the folder of spritesheets

Return type:

Animation

Particle Sytem#

A simple particle system.

enum ParticleSystemMode(value)[source]#

The mode of the particle system.

Member Type:: int

Valid values are as follows:

RANDOM = <ParticleSystemMode.RANDOM: 0>#: The particles are generated randomly.

LOOP = <ParticleSystemMode.LOOP: 1>#: Animate the generation around the shape.

PINGPONG = <ParticleSystemMode.PINGPONG: 2>#: Animate the generation in a pingpong fashion.

BURST = <ParticleSystemMode.BURST: 3>#: Generate the particles in a burst.

class ParticleSystem(new_particle=None, duration=5, loop=False, max_particles=Math.INF, mode=ParticleSystemMode.RANDOM, spread=5, density=1, local_space=False, running=False, offset=(0, 0), rot_offset=0, z_index=0)[source]#

A simple particle system.

Parameters:

new_particle (Optional[Callable[[float], Particle]]) -- The method to generate a new particle. Takes in an angle and should return a particle object. Defaults to ParticleSystem.default_particle.
duration (float) -- The duration of the system in seconds (when to stop generating particles). Defaults to 5.
loop (bool) -- Whether the system should loop (start again at the end of its duration). Defaults to False.
max_particles (int) -- The maximum number of particles in the system. Defaults to Math.INF.
mode (ParticleSystemMode) -- The particle generation mode of the system. Defaults to ParticleSystemMode.RANDOM.
spread (float) -- The gap between particles (in degrees). Defaults to 45.
density (int) -- The density of the system. This is the number of particles generated per fixed update. Defaults to 1.
local_space (bool) -- Whether the particles should be in local space.
running (bool) -- Whether the system should start as soon as it becomes active.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the system. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the system. Defaults to 0.
z_index (int) -- The z-index of the system. Defaults to 0.

new_particle#: The user-defined function that generates a particle.

duration: float#: The duration of the system in seconds.

loop: bool#: Whether the system should loop.

max_particles: int#: The maximum number of particles in the system.

mode: ParticleSystemMode#: The particle generation mode of the system.

spread: float#: The gap between particles (in degrees).

density: int#: The density of the system. This is the number of particles generated per fixed update.

local_space: bool#: Whether the particles should be in local space.

running: bool#: Whether the system is allowed to generate particles.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

singular: bool#: Whether multiple components of the same type are allowed on a game object.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

num_particles()[source]#: The number of particles in the system.

start()[source]#: Start the system (sets running to True).

stop()[source]#: Stop the system (sets running to False).

fixed_update()[source]#: The physics function for a component.

draw(camera)[source]#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

generate_particles()[source]#: Generates particles. Called automatically by fixed_update.

clear()[source]#: Clear the system.

clone()[source]#

Clones the component.

Return type:: ParticleSystem

static default_particle(angle)[source]#

The default particle generation function. This can be passed into the Particle System constructor.

Return type:: Particle

static particle_gen(surface, movement=None, pos_func=None, dir_func=Particle.circle_direction(), start_speed=1, acceleration=(0, 0), rotation=0, rot_velocity=0, rot_acceleration=0, scale=(1, 1), lifespan=1, z_index=0, age=0)[source]#

Generates a particle generation function for the Particle System constructor.

Parameters:

surface (Surface) -- The surface to use for the particle.
movement (Optional[Callable[[Particle, float], None]]) -- The movement function. Defaults to Particle.default_movement.
pos_func (Optional[Callable[[float], Vector]]) -- The function used to determine each starting position. Must take in an angle relative to the system. Defaults to lambda _: Vector(0, 0).
dir_func (Callable[[float], Vector]) -- The function used to determine each starting direction. Must take in an angle relative to the system. Defaults to Particle.circle_direction().
start_speed (float) -- The starting speed. Defaults to 1.
acceleration (UnionType[Vector, tuple[float, float]]) -- The starting acceleration. Defaults to (0, 0).
rotation (float) -- The starting rotation. Defaults to 0.
rot_velocity (float) -- The starting rotational velocity. Defaults to 0.
rot_acceleration (float) -- The starting rotational acceleration. Defaults to 0.
scale (UnionType[Vector, tuple[float, float]]) -- The starting scale. Defaults to (1, 1).
lifespan (float) -- The lifespan of each particle. Defaults to 1.
z_index (int) -- The z-index of each particle. Defaults to 0.
age (float) -- The starting age of each particle. Defaults to 0.

Return type:

Callable[[float], Particle]

Returns:

A particle generation function.

Particle#

A simple particle.

class Particle(surface, movement=None, pos=(0, 0), velocity=(0, 0), acceleration=(0, 0), rotation=0, rot_velocity=0, rot_acceleration=0, scale=(1, 1), lifespan=1, z_index=0, age=0)[source]#

A simple particle.

Parameters:

surface (Surface) -- The surface of the particle.
movement (Optional[Callable[[Particle, float], None]]) -- The movement function of a particle. Takes in a Particle and a delta time. Defaults to Particle.default_movement.
pos (UnionType[Vector, tuple[float, float]]) -- The position of the particle. Defaults to (0, 0).
velocity (UnionType[Vector, tuple[float, float]]) -- The velocity of the particle. Defaults to (0, 0).
acceleration (UnionType[Vector, tuple[float, float]]) -- The acceleration of the particle. Defaults to (0, 0).
rotation (float) -- The rotation of the particle. Defaults to 0.
rot_velocity (float) -- The rotational velocity of the particle. Defaults to 0.
rot_acceleration (float) -- The rotational acceleration of the particle. Defaults to 0.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the particle. Defaults to (1, 1).
lifespan (float) -- The lifespan of the particle (in seconds). Defaults to 1.
z_index (int) -- The z-index of the particle. Defaults to 0.
age (float) -- The starting age of the particle (in seconds). Defaults to 0.

surface: Surface#: The surface that renders the particle.

movement: Callable[[Particle, float], None]#: The movement function of the particle

velocity: Vector#: The velocity of the particle.

acceleration: Vector#: The acceleration of the particle.

pos: Vector#: The position of the particle.

rotation: float#: The rotation of the particle.

rot_velocity: float#: The rotational velocity of the particle.

rot_acceleration: float#: The rotational acceleration of the particle.

scale: Vector#: The scale of the particle.

lifespan: float#: The lifespan of the particle. (in seconds)

z_index: int#: The z index of the particle.

age: float#: The age of the particle. (in seconds)

static default_movement(particle, dt)[source]#: The default movement function.

static circle_shape(radius)[source]#

A shape function that returns a circle. The output of this generator can be used as a position value for Particles.

Parameters:: radius (float) -- The radius of the circle.
Return type:: Callable[[float], Vector]

static circle_direction()[source]#

A direction function that returns a circle. The output of this generator can be used to control the initial direction of Particles.

Return type:: Callable[[float], Vector]

static square_shape(size)[source]#

A shape function that returns a square. The output of this generator can be used as a position value for Particles.

Parameters:: size (float) -- The size of the square.
Return type:: Callable[[float], Vector]

static square_direction()[source]#

A direction function that returns a square. The output of this generator can be used to control the initial direction of Particles.

Return type:: Callable[[float], Vector]

Tilemap#

A Tiled tilemap.

class Tilemap(map_path, scale=(1, 1), collider_tag='', z_index=0, hidden=False)[source]#

A tilemap that is loaded from a Tiled map file. Once a tilemap component is created, it won't stay updated with the map file. To automatically add hitboxes to the gameobject, use Tiled Objects. We support Rectangles and Polygons in layers or on the individual tiles.

We do not support all of Tiled's features, but we do support the most common ones. Here is a list of major features that we DO NOT support:

Infinite maps
Non-orthogonal maps
Non-rectangular tiles
Animated tiles
Multiple tilesets per map
Image layers
Tile and layer opacity
Parallax scrolling
Worlds
Terrain

Parameters:

map_path (str) -- The path to the map file.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the tilemap. Defaults to (1, 1).
collider_tag (str) -- The tag of the colliders. Defaults to "".
z_index (int) -- The z index of the tilemap. Defaults to 0.
hidden (bool) -- Whether the tilemap is hidden. Defaults to False.

setup()[source]#: The setup function for a component.

draw(camera)[source]#

The draw function for a component.

Parameters:: camera -- The camera to draw the component with.

clone()[source]#

Clones the component.

Return type:: Tilemap

fixed_update()#: The physics function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

singular: bool#: Whether multiple components of the same type are allowed on a game object.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

Simple Tilemap#

A simple tilemap doesn't need to use the Tiled editor. It uses an array of numbers to keep track of tile types.

class SimpleTilemap(tilemap, tiles, tile_size=(32, 32), collision=None, collider_tag=None, scale=(1, 1), offset=(0, 0), rot_offset=0, z_index=0, hidden=False)[source]#

A simple tilemap doesn't need to use the Tiled editor. It uses an array of numbers to keep track of tile types.

Parameters:

tilemap (list[list[int]]) -- A 2D array of integers representing the tilemap.
tiles (list[Surface]) -- A list of surfaces representing the tiles. The index of the surface in the list is the number used in the tilemap array.
tile_size (UnionType[Vector, tuple[int, int]]) -- The size of each tile in the tilemap. Defaults to (32, 32).
collision (Optional[list[int]]) -- A list of integers representing the tiles that should have collision. Defaults to [].
collider_tag (Optional[list[str]]) -- A list of strings representing the tags of the colliders. The index of the tag in the list is the number used in the tilemap array. Defaults to [].
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the tilemap. Defaults to (1, 1).
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the tilemap. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the tilemap. Defaults to 0.
z_index (int) -- The z-index of the tilemap. Defaults to 0.
hidden (bool) -- Whether the tilemap is hidden. Defaults to False.

scale#: The scale of the tilemap.

uptodate#: Whether the tilemap is up to date.

update()[source]#: The update function for a component.

draw(camera)[source]#

The draw function for a component.

Parameters:: camera -- The camera to draw the component with.

fixed_update()#: The physics function for a component.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

singular: bool#: Whether multiple components of the same type are allowed on a game object.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

clone()[source]#

Clones the component.

Return type:: SimpleTilemap

Hitbox#

Various hitbox components that enable collisions

class Hitbox(color=None, tag='', trigger=False, should_collide=None, on_collide=None, on_enter=None, on_exit=None, offset=(0, 0), rot_offset=0, z_index=0, scale=(1, 1), debug=False, hidden=False)[source]#

A hitbox superclass. Do not use this class to attach hitboxes to your game objects. Instead, use Polygon or Circle, which inherit Hitbox properties.

Parameters:

color (Optional[Color]) -- The color of the hitbox. Set to None to not show the hitbox. Defaults to None.
tag (str) -- A string to tag the hitbox. Defaults to "".
trigger (bool) -- Whether the hitbox is a trigger. Defaults to False.
should_collide (Optional[Callable[[Hitbox, Hitbox], bool]]) -- A function to call to determine whether the hitbox should collide with another hitbox. Defaults to lambda self, other: True.
on_collide (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox collides with another hitbox. Defaults to lambda manifold: None.
on_enter (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox enters another hitbox. Defaults to lambda manifold: None.
on_exit (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox exits another hitbox. Defaults to lambda manifold: None.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the hitbox from the gameobject. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the hitbox. Defaults to 0.
z_index (int) -- The z-index of the hitbox. Defaults to 0.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the hitbox. Defaults to (1, 1).
debug (bool) -- Whether to draw the hitbox. Defaults to False.
hidden (bool) -- Whether the hitbox is hidden. Defaults to False.

debug: bool#: Whether to draw a green outline around the hitbox or not.

trigger: bool#: Whether this hitbox is just a trigger or not.

scale: Vector#: The scale of the hitbox.

should_collide: Callable[[Hitbox, Hitbox], bool]#: The should_collide function to call to determine whether two hitboxes should collide.

on_collide: Callable[[Manifold], None]#: The on_collide function to call when a collision happens with this hitbox.

on_enter: Callable[[Manifold], None]#: The on_enter function to call when collision begins with this hitbox.

on_exit: Callable[[Manifold], None]#: The on_exit function to call when a collision ends with this hitbox.

singular: bool#: Whether this hitbox is singular or not.

tag: str#: The tag of the hitbox (can be used to identify hitboxes in collision callbacks)

colliding: set[Hitbox]#: An unordered set of hitboxes that the Hitbox is currently colliding with.

color: Color | None#: The color of the hitbox.

uptodate: bool#: Whether the hitbox image is up to date or not.

regen()[source]#: Regenerates internal hitbox information.

contains_pt(pt)[source]#

Checks if a point is inside the Hitbox.

Parameters:: pt (UnionType[Vector, tuple[float, float]]) -- The point to check, in game-world coordinates.
Returns:: Whether the point is inside the Hitbox.

redraw()[source]#: Regenerates the image of the hitbox.

get_aabb()[source]#

Gets bottom left and top right corners of the axis-aligned bounding box of the hitbox in world coordinates.

Returns:: The bottom left and top right right corners of the bounding box as Vectors as a tuple. (bottom left, top right)
Return type:: tuple[Vector, Vector]

update()[source]#: The update function for a component.

draw(camera)[source]#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

clone()#

Clones the component.

Return type:: Component

fixed_update()#: The physics function for a component.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

Rectangle#

class Rectangle(width=0, height=0, color=None, tag='', trigger=False, should_collide=None, on_collide=None, on_enter=None, on_exit=None, offset=(0, 0), rot_offset=0, z_index=0, scale=(1, 1), debug=False, hidden=False)[source]#

A Rectangular Hitbox component.

Parameters:

width (UnionType[int, float]) -- The width of the rectangle. Defaults to 0.
height (UnionType[int, float]) -- The height of the rectangle. Defaults to 0.
color (Optional[Color]) -- The color of the hitbox. Set to None to not show the hitbox. Defaults to None.
tag (str) -- A string to tag the hitbox. Defaults to "".
trigger (bool) -- Whether the hitbox is a trigger. Defaults to False.
should_collide (Optional[Callable[[Hitbox, Hitbox], bool]]) -- A function to call to determine whether the hitbox should collide with another hitbox. Defaults to lambda self, other: True.
on_collide (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox collides with another hitbox. Defaults to lambda manifold: None.
on_enter (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox enters another hitbox. Defaults to lambda manifold: None.
on_exit (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox exits another hitbox. Defaults to lambda manifold: None.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the hitbox from the gameobject. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the hitbox. Defaults to 0.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the hitbox. Defaults to (1, 1).
debug (bool) -- Whether to draw the hitbox. Defaults to False.
z_index (int) -- The z-index of the hitbox. Defaults to 0.
hidden (bool) -- Whether the hitbox is hidden. Defaults to False.

property width: int | float#

The width of the Rectangle.

Return type:: UnionType[int, float]

property height: int | float#

The height of the Rectangle.

Return type:: UnionType[int, float]

property verts: list[rubato.utils.computation.vector.Vector]#

The list of Rectangle vertices. (get-only)

Return type:: list[Vector]

property radius: float#

The radius of the Rectangle. (get-only)

Return type:: float

property top_left#: The top left corner of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

property bottom_left#: The bottom left corner of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

property top_right#: The top right corner of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

property bottom_right#: The bottom right corner of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

property top#: The y value of the top side of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

draw(camera)#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

fixed_update()#: The physics function for a component.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

debug: bool#: Whether to draw a green outline around the hitbox or not.

trigger: bool#: Whether this hitbox is just a trigger or not.

scale: Vector#: The scale of the hitbox.

should_collide: Callable[[Hitbox, Hitbox], bool]#: The should_collide function to call to determine whether two hitboxes should collide.

on_collide: Callable[[Manifold], None]#: The on_collide function to call when a collision happens with this hitbox.

on_enter: Callable[[Manifold], None]#: The on_enter function to call when collision begins with this hitbox.

on_exit: Callable[[Manifold], None]#: The on_exit function to call when a collision ends with this hitbox.

singular: bool#: Whether this hitbox is singular or not.

tag: str#: The tag of the hitbox (can be used to identify hitboxes in collision callbacks)

colliding: set[Hitbox]#: An unordered set of hitboxes that the Hitbox is currently colliding with.

color: Color | None#: The color of the hitbox.

uptodate: bool#: Whether the hitbox image is up to date or not.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

property left#: The x value of the left side of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

property bottom#: The y value of the bottom side of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

property right#: The x value of the right side of the AABB surrounding the rectangle. Setting to this value changes the gameobject's position, not the hitbox offset.

get_aabb()[source]#

Gets bottom left and top right corners of the axis-aligned bounding box of the hitbox in world coordinates.

Returns:: The bottom left and top right right corners of the bounding box as Vectors as a tuple. (bottom left, top right)
Return type:: tuple[Vector, Vector]

offset_verts()[source]#

The list of rectangle vertices offset by the Rectangles's offsets.

Return type:: list[Vector]

true_verts()[source]#

Returns a list of the Rectangle's vertices in world coordinates. Accounts for gameobject position and rotation.

Return type:: list[Vector]

regen()[source]#: Regenerates internal hitbox information.

redraw()[source]#: Regenerates the image of the hitbox.

contains_pt(pt)[source]#

Checks if a point is inside the Hitbox.

Parameters:: pt (UnionType[Vector, tuple[float, float]]) -- The point to check, in game-world coordinates.
Return type:: bool
Returns:: Whether the point is inside the Hitbox.

clone()[source]#

Clones the component.

Return type:: Rectangle

Polygon#

class Polygon(verts=[], color=None, tag='', trigger=False, should_collide=None, on_collide=None, on_enter=None, on_exit=None, offset=(0, 0), rot_offset=0, z_index=0, scale=(1, 1), debug=False, hidden=False)[source]#

A Polygonal Hitbox component.

Danger

If creating vertices by hand, make sure you generate them in a CLOCKWISE direction. Otherwise, polygons may not behave or draw properly. We recommend using Vector.poly() to generate the vertex list for regular polygons.

Warning

rubato does not currently support concave polygons. Creating concave polygons will result in undesired behavior.

Parameters:

verts (UnionType[list[Vector], list[tuple[float, float]]]) -- The vertices of the polygon. Defaults to [].
color (Optional[Color]) -- The color of the hitbox. Set to None to not show the hitbox. Defaults to None.
tag (str) -- A string to tag the hitbox. Defaults to "".
trigger (bool) -- Whether the hitbox is a trigger. Defaults to False.
should_collide (Optional[Callable[[Hitbox, Hitbox], bool]]) -- A function to call to determine whether the hitbox should collide with another hitbox. Defaults to lambda self, other: True.
on_collide (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox collides with another hitbox. Defaults to lambda manifold: None.
on_enter (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox enters another hitbox. Defaults to lambda manifold: None.
on_exit (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox exits another hitbox. Defaults to lambda manifold: None.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the hitbox from the gameobject. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the hitbox. Defaults to 0.
z_index (int) -- The z-index of the hitbox. Defaults to 0.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the hitbox. Defaults to (1, 1).
debug (bool) -- Whether to draw the hitbox. Defaults to False.
hidden (bool) -- Whether the hitbox is hidden. Defaults to False.

property verts: list[rubato.utils.computation.vector.Vector]#

A list of the vertices in the Polygon.

Return type:: list[Vector]

property radius: float#

The radius of the Polygon. (get-only)

Return type:: float

get_aabb()[source]#

Gets bottom left and top right corners of the axis-aligned bounding box of the hitbox in world coordinates.

Returns:: The bottom left and top right right corners of the bounding box as Vectors as a tuple. (bottom left, top right)
Return type:: tuple[Vector, Vector]

offset_verts()[source]#

The list of polygon vertices offset by the Polygon's offsets.

Return type:: list[Vector]

true_verts()[source]#

Returns a list of the Polygon's vertices in world coordinates. Accounts for gameobject position and rotation.

Return type:: list[Vector]

regen()[source]#: Regenerates internal hitbox information.

redraw()[source]#: Regenerates the image of the hitbox.

contains_pt(pt)[source]#

Checks if a point is inside the Hitbox.

Parameters:: pt (UnionType[Vector, tuple[float, float]]) -- The point to check, in game-world coordinates.
Return type:: bool
Returns:: Whether the point is inside the Hitbox.

clone()[source]#

Clones the Polygon

Return type:: Polygon

draw(camera)#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

fixed_update()#: The physics function for a component.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

debug: bool#: Whether to draw a green outline around the hitbox or not.

trigger: bool#: Whether this hitbox is just a trigger or not.

scale: Vector#: The scale of the hitbox.

should_collide: Callable[[Hitbox, Hitbox], bool]#: The should_collide function to call to determine whether two hitboxes should collide.

on_collide: Callable[[Manifold], None]#: The on_collide function to call when a collision happens with this hitbox.

on_enter: Callable[[Manifold], None]#: The on_enter function to call when collision begins with this hitbox.

on_exit: Callable[[Manifold], None]#: The on_exit function to call when a collision ends with this hitbox.

singular: bool#: Whether this hitbox is singular or not.

tag: str#: The tag of the hitbox (can be used to identify hitboxes in collision callbacks)

colliding: set[Hitbox]#: An unordered set of hitboxes that the Hitbox is currently colliding with.

color: Color | None#: The color of the hitbox.

uptodate: bool#: Whether the hitbox image is up to date or not.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

Circle#

class Circle(radius=0, color=None, tag='', trigger=False, should_collide=None, on_collide=None, on_enter=None, on_exit=None, offset=(0, 0), rot_offset=0, z_index=0, scale=(1, 1), debug=False, hidden=False)[source]#

A Circular Hitbox component.

Parameters:

radius (UnionType[int, float]) -- The radius of the circle. Defaults to 0.
color (Optional[Color]) -- The color of the hitbox. Set to None to not show the hitbox. Defaults to None.
tag (str) -- A string to tag the hitbox. Defaults to "".
trigger (bool) -- Whether the hitbox is a trigger. Defaults to False.
should_collide (Optional[Callable[[Hitbox, Hitbox], bool]]) -- A function to call to determine whether the hitbox should collide with another hitbox. Defaults to lambda self, other: True.
on_collide (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox collides with another hitbox. Defaults to lambda manifold: None.
on_enter (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox enters another hitbox. Defaults to lambda manifold: None.
on_exit (Optional[Callable[[Manifold], None]]) -- A function to call when the hitbox exits another hitbox. Defaults to lambda manifold: None.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the hitbox from the gameobject. Defaults to (0, 0).
rot_offset (float) -- The rotation offset of the hitbox. Defaults to 0.
z_index (int) -- The z-index of the hitbox. Defaults to 0.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the hitbox. Note that only the largest value will determine the scale. Defaults to (1, 1).
debug (bool) -- Whether to draw the hitbox. Defaults to False.
hidden (bool) -- Whether the hitbox is hidden. Defaults to False.

draw(camera)#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

fixed_update()#: The physics function for a component.

regen()#: Regenerates internal hitbox information.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

debug: bool#: Whether to draw a green outline around the hitbox or not.

trigger: bool#: Whether this hitbox is just a trigger or not.

scale: Vector#: The scale of the hitbox.

should_collide: Callable[[Hitbox, Hitbox], bool]#: The should_collide function to call to determine whether two hitboxes should collide.

on_collide: Callable[[Manifold], None]#: The on_collide function to call when a collision happens with this hitbox.

on_enter: Callable[[Manifold], None]#: The on_enter function to call when collision begins with this hitbox.

on_exit: Callable[[Manifold], None]#: The on_exit function to call when a collision ends with this hitbox.

singular: bool#: Whether this hitbox is singular or not.

tag: str#: The tag of the hitbox (can be used to identify hitboxes in collision callbacks)

colliding: set[Hitbox]#: An unordered set of hitboxes that the Hitbox is currently colliding with.

color: Color | None#: The color of the hitbox.

uptodate: bool#: Whether the hitbox image is up to date or not.

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

property radius: int | float#

The radius of the circle.

Return type:: UnionType[int, float]

property center: Vector#

The center of the circle. Equivalent to true_pos. Setting to this will change the Gameobject position.

Return type:: Vector

get_aabb()[source]#

Gets bottom left and top right corners of the axis-aligned bounding box of the hitbox in world coordinates.

Returns:: The bottom left and top right right corners of the bounding box as Vectors as a tuple. (bottom left, top right)
Return type:: tuple[Vector, Vector]

true_radius()[source]#

Gets the true radius of the circle

Return type:: UnionType[int, float]

redraw()[source]#: Regenerates the image of the hitbox.

contains_pt(pt)[source]#

Checks if a point is inside the Hitbox.

Parameters:: pt (UnionType[Vector, tuple[float, float]]) -- The point to check, in game-world coordinates.
Return type:: bool
Returns:: Whether the point is inside the Hitbox.

clone()[source]#

Clones the component.

Return type:: Circle

Manifold#

class Manifold(shape_a, shape_b, penetration=0, normal=Vector())[source]#

A class that represents information returned in collision callbacks.

Parameters:

shape_a (Hitbox) -- The first shape involved in the collision (the reference shape).
shape_b (Hitbox) -- The second shape involved in the collision (the incident shape).
penetration (float) -- The amount of penetration between the two shapes.
normal (Vector) -- The normal of the collision.

shape_a: Hitbox#: The reference shape.

shape_b: Hitbox#: The incident (colliding) shape.

penetration: float#: The amount by which the colliders are intersecting.

normal: Vector#: The direction that would most quickly separate the two colliders.

RigidBody#

The Rigidbody component describes how the physics engine handles a game object.

class RigidBody(mass=1, gravity=(0, 0), friction=0, static=False, bounciness=0, max_speed=(Math.INF, Math.INF), velocity=(0, 0), ang_vel=0, pos_correction=0.25, offset=(0, 0), rot_offset=0, z_index=0)[source]#

A RigidBody implementation with built in physics and collisions. Rigidbodies require hitboxes.

Parameters:

mass (float) -- The mass of the rigidbody. Defaults to -1.
gravity (UnionType[Vector, tuple[float, float]]) -- The gravity of the rigidbody. Defaults to (0, 0).
friction (float) -- The friction of the rigidbody. Defaults to 0.
static (bool) -- Whether the rigidbody is static. Defaults to False.
bounciness (float) -- The bounciness of the rigidbody. Defaults to 0.
max_speed (UnionType[Vector, tuple[float, float]]) -- The maximum speed of the rigidbody. Defaults to (INF, INF).
velocity (UnionType[Vector, tuple[float, float]]) -- The velocity of the rigidbody. Defaults to (0, 0).
ang_vel (float) -- The angular velocity of the rigidbody. Defaults to 0.
pos_correction (float) -- The positional correction of the rigidbody. Defaults to 0.25.
offset (UnionType[Vector, tuple[float, float]]) -- The offset of the rigidbody from the gameobject. Defaults to (0, 0).
rot_offset (float) -- The offset of the rigidbody's rotation from the gameobject. Defaults to 0.
z_index (int) -- The z-index of the rigidbody. Defaults to 0.

static: bool#: Whether the rigidbody is static (as in, it does not move).

gravity: Vector#: The acceleration of the gravity that should be applied.

friction: float#: The friction coefficient of the Rigidbody (usually a value between 0 and 1).

max_speed: Vector#: The maximum speed of the Rigidbody.

pos_correction: float#: The positional correction of the rigidbody.

velocity: Vector#: The current velocity of the Rigidbody.

ang_vel: float#: The current angular velocity of the Rigidbody.

singular: bool#: Whether multiple components of the same type are allowed on a game object.

inv_mass: float#: The inverse mass of the Rigidbody.

draw(camera)#

The draw function for a component.

Parameters:: camera (Camera) -- The camera to draw the component with.

setup()#: The setup function for a component.

true_pos()#

Returns the world position of the component.

Return type:: Vector

true_rotation()#

Returns the rotation of the component offset by its parent gameobject rotation.

Return type:: float

true_z()#

Returns the z_index of the component offset by its parent gameobject z_index.

Return type:: int

update()#: The update function for a component.

bounciness: float#: How bouncy the rigidbody is (usually a value between 0 and 1).

offset: Vector#: The offset from the center of the game object that the hitbox should be placed.

rot_offset: float#: The rotational offset from the game object's rotation.

z_index: int#: Where to draw the component in the z direction.

gameobj: GameObject#: The game object this component is attached to.

hidden#: Whether the component is hidden (not drawn).

property mass: float#

The mass of the Rigidbody.

Return type:: float

add_force(force)[source]#

Applies a force to the Rigidbody.

Parameters:: force (UnionType[Vector, tuple[float, float]]) -- The force to add.

add_impulse(impulse)[source]#

Applies an impulse to the rigidbody.

Parameters:: impulse (UnionType[Vector, tuple[float, float]]) -- The impulse to add.

add_cont_force(force, time)[source]#

Add a continuous force to the Rigidbody. A continuous force is a force that is continuously applied over a time period. (the force is added every frame for a specific duration).

Parameters:

force (UnionType[Vector, tuple[float, float]]) -- The force to add.
time (float) -- The time in seconds that the force should be added.

add_cont_impulse(impulse, time)[source]#

Add a continuous impulse to the Rigidbody. A continuous impulse is a impulse that is continuously applied over a time period. (the impulse is added every frame for a specific duration).

Parameters:

impulse (UnionType[Vector, tuple[float, float]]) -- The impulse to add.
time (float) -- The time in seconds that the impulse should be added.

fixed_update()[source]#: The physics loop for the rigidbody component.

stop()[source]#: Stops the rigidbody by setting velocity and ang_vel to 0.

clone()[source]#

Clones the component.

Return type:: RigidBody

Hardware Interaction#

All of these static classes let you interact with the hardware. Either by checking for user input, drawing to the screen or playing a sound.

Display#

Static class that allows for intuitive window management.

class Display[source]#

A static class that houses all of the display information

window#

The pysdl2 window element.

Type:: sdl2.Window

renderer#

The pysdl2 renderer element.

Type:: sdl2.Renderer

format#

The pysdl2 pixel format element.

Type:: sdl2.PixelFormat

window_size#

The pixel size of the physical window.

Warning

Using this value to determine the placement of your game objects may lead to unexpected results. You should instead use Display.res

Type:: Vector

res#

The pixel resolution of the game. This is the number of virtual pixels on the window.

Example

The window (Display.window_size) could be rendered at 500x500 while the resolution is at 1000x1000. This would mean that you can place game objects at 900, 900 and still see them despite the window not being 900 pixels tall.

Warning

While this value can be changed, it is recommended that you do not alter it after initialization as it will scale your entire project in unexpected ways. If you wish to achieve scaling across an entire scene, simply utilize the camera zoom property in your scene's camera.

Type:: Vector

window_pos#

The current position of the window in terms of screen pixels.

Type:: Vector

window_name#

The name of the window.

Type:: str

hidden#

Whether the window is currently hidden.

Type:: bool

class property display_ratio: Vector#

The ratio of the renderer resolution to the window size. This is a read-only property.

Returns:: The ratio of the renderer resolution to the window size seperated by x and y.
Return type:: Vector

class property border_size: int#

The size of the black border on either side of the drawing area when the aspect ratios don't match.

Return type:: int

classmethod has_x_border()[source]#

Whether the window has a black border on the left or right side.

Return type:: bool

classmethod has_y_border()[source]#

Whether the window has a black border on the top or bottom.

Return type:: bool

classmethod set_window_icon(path)[source]#

Set the icon of the window.

Parameters:: path (str) -- The path to the icon.

classmethod set_fullscreen(on=True)[source]#

Set the window to fullscreen.

Parameters:: on (bool) -- Whether to set the window to fullscreen.

classmethod get_window_border_size()[source]#

Get the size of the window border. pixels on the top sides and bottom of the window.

Returns:: The size of the window border.

classmethod save_screenshot(filename, path='./', extension='png', save_to_temp_path=False, quality=100)[source]#

Save the current screen to a file.

Parameters:

filename (str) -- The name of the file to save to.
path (str) -- Path to output folder.
extension (str) -- The extension to save the file as. (png, jpg, bmp supported)
save_to_temp_path (bool) -- Whether to save the file to a temporary path (i.e. MEIPASS used in exe).
quality (int) -- The quality of the jpg 0-100 (only used for jpgs).

Return type:

Returns:

If save was successful.

classmethod show_window()[source]#: Show the window.

classmethod hide_window()[source]#: Hide the window.

classmethod maximize_window()[source]#: Maximize the window.

classmethod minmize_window()[source]#: Minimize the window.

classmethod restore_window()[source]#: Restore the window.

class property center: Vector#

The position of the center of the window.

Return type:: Vector

class property top: float#

The position of the top of the window.

Return type:: float

class property right: float#

The position of the right of the window.

Return type:: float

class property left: float#

The position of the left of the window.

Return type:: float

class property bottom: float#

The position of the bottom of the window.

Return type:: float

class property top_left: Vector#

The position of the top left of the window.

Return type:: Vector

class property top_right: Vector#

The position of the top right of the window.

Return type:: Vector

class property bottom_left: Vector#

The position of the bottom left of the window.

Return type:: Vector

class property bottom_right: Vector#

The position of the bottom right of the window.

Return type:: Vector

class property top_center: Vector#

The position of the top center of the window.

Return type:: Vector

class property bottom_center: Vector#

The position of the bottom center of the window.

Return type:: Vector

class property center_left: Vector#

The position of the center left of the window.

Return type:: Vector

class property center_right: Vector#

The position of the center right of the window.

Return type:: Vector

Input#

An abstraction for checking for hardware input from a user.

class Input[source]#

The input class, handling keyboard, mouse, and controller functionality.

Go here for a list of all the available keys.

classmethod controllers()[source]#

A list of the controllers currently registered.

If non-zero, the controllers are registered from 0 to n-1 where n is the number of controllers. This number index is passed to events that are propagated when controllers are inputted to.

Return type:: list[int]
Returns:: A list of the integer indexes of the controllers currently registered.

classmethod controller_name(controller)[source]#

Get the name of the controller at the given index.

Parameters:: index -- The index of the controller to get the name of.
Raises:: IndexError -- The controller for the given index is not registered.
Return type:: str
Returns:: The name of the controller.

classmethod controller_axis(controller, axis)[source]#

Get the value of a given joystick axis on a controller.

Parameters:

controller (int) -- The index of the controller.
axis (int) -- The index of the joystick axis.

Raises:

IndexError -- The controller for the given index is not registered.

Return type:

float

Returns:

The value of the axis.

classmethod axis_centered(val)[source]#

Check whether a given axis value is within the +/-10% bounds of deadzone considered the "center".

Parameters:: val (float) -- The value of the axis.
Return type:: bool
Returns:: Whether the axis is centered.

classmethod controller_button(controller, button)[source]#

Check whether a given button on a controller is pressed.

Parameters:

controller (int) -- The index of the controller.
button (int) -- The index of the button.

Raises:

IndexError -- The controller for the given index is not registered.

Return type:

Returns:

Whether the button is pressed.

classmethod controller_hat(controller, hat)[source]#

Get the value of a given hat on a controller.

Parameters:

controller (int) -- The index of the controller.
hat (int) -- The index of the hat.

Raises:

IndexError -- The controller for the given index is not registered.

Returns:

The value of the hat, which you can translate with translate_hat().

Return type:

int

classmethod translate_hat(val)[source]#

Translate a hat value to a string.

Parameters:: val (int) -- The hat value.
Returns:: The string representation of the hat value.
Return type:: str

classmethod key_pressed(*keys)[source]#

Checks if keys are pressed. Case insensitive.

Parameters:: *keys -- The names of the keys to check.
Returns:: Whether the keys are pressed.
Return type:: bool

Example

if rb.Input.key_pressed("a"):
    # handle the "a" keypress

if rb.Input.key_pressed("shift", "w"):
    # handle the "shift+w" keypress

classmethod get_keyboard_state()[source]#: Returns a list with the current SDL keyboard state.

classmethod get_name(code)[source]#

Gets the name of a key from its keycode.

Parameters:: code (int) -- A keycode.
Returns:: The corresponding key.
Return type:: str

classmethod mods_from_code(code)[source]#

Gets the modifier names from a mod code.

Parameters:: code (int) -- The mod code.
Returns:: A list with the names of the currently pressed modifiers.
Return type:: list[str]

classmethod key_from_name(char)[source]#

Gets the keycode of a key from its name.

Parameters:: char (str) -- The name of the key.
Returns:: The corresponding keycode.
Return type:: int

classmethod scancode_from_name(char)[source]#

Gets the scancode of a key from its name.

Parameters:: char (str) -- The name of the key.
Returns:: The corresponding scancode.
Return type:: int

classmethod window_focused()[source]#

Checks if the display has keyboard focus.

Returns:: True if the window is focused, false otherwise.
Return type:: bool

classmethod mouse_state()[source]#

Checks which mouse buttons are pressed.

Return type:: tuple[bool, bool, bool, bool, bool]
Returns:: A tuple with 5 booleans representing the state of each mouse button. (button1, button2, button3, button4, button5)

classmethod mouse_pressed()[source]#

Checks if any mouse button is pressed.

Return type:: bool
Returns:: True if any button is pressed, false otherwise.

classmethod get_mouse_pos()[source]#

The current position of the mouse, in screen-coordinates.

Return type:: Vector
Returns:: A Vector representing position.

static get_mouse_abs_pos()[source]#

The current absolute position of the mouse, in display coordinates.

Return type:: Vector
Returns:: A Vector representing position.

static set_mouse_pos(v)[source]#

Sets the position of the mouse.

Parameters:: v (UnionType[Vector, tuple[float, float]]) -- The position to set the mouse to.

classmethod mouse_is_visible()[source]#

Checks if the mouse is currently visible.

Returns:: True for visible, false otherwise.
Return type:: bool

classmethod set_mouse_visibility(toggle)[source]#

Sets the mouse visibility.

Parameters:: toggle (bool) -- True to show the mouse and false to hide the mouse.

static pt_in_poly(pt, verts)[source]#

Checks if a point is inside a polygon.

Parameters:

pt (UnionType[Vector, tuple[float, float]]) -- The point to check.
verts (UnionType[list[Vector], list[tuple[float, float]]]) -- The polygon representation as a list of Vector | tuple[float, float]s (vertices)

Returns:

Whether the point is inside the polygon.

Return type:

bool

classmethod mouse_in(center, dims=(1, 1), angle=0)[source]#

Checks if the mouse is inside a rectangle defined by its center and dimensions

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The center of the rectangle.
dims (UnionType[Vector, tuple[float, float]]) -- The dimensions of the rectangle. Defaults to (1, 1).
angle (float) -- The angle of the rectangle in degrees. Defaults to 0.

Returns:

Whether the mouse is in the defined rectangle.

Return type:

bool

Sound#

A multi-channel sound system for rubato.

class Sound(path, sound_name='')[source]#

Used to play sounds in rubato. The following file formats are supported:

MP3
WAV
OGG
FLAC
MOD
MIDI (not always available on linux)
OPUS
AIFF
VOC

Parameters:

path (str) -- The relative path to the sound file you wish to import.
sound_name (str) -- The name of the sound. Defaults to the name of the file.

loaded_sounds: dict[str, rubato.utils.hardware.sound.Sound] = {}#: A dictionary housing all the loaded sounds, stored by their name.

active_channels: dict[int, rubato.utils.hardware.sound.Sound] = {}#: A dictionary housing all the active sounds, stored by their name.

property state: int#

The current state of the sound.

The possible states are:

Sound.STOPPED
Sound.PLAYING
Sound.PAUSED

Returns:: The current state of the sound.
Return type:: int

play(loops=0, init_volume=128)[source]#

Plays a sound.

Parameters:

loops (int) -- The number of times to loop a sound after the first play through. Use -1 to loop forever. Defaults to 0.'
init_volume (int) -- The initail volume of the sound. Defaults to the volume of the sound. range(0, MIX_MAX_VOLUME=>128)

stop()[source]#: Stops all instances of the sound.

pause()[source]#: Pauses all instances of the sound.

resume()[source]#: Resumes all instance of the sound.

set_volume(volume)[source]#

Sets the volume of the sound.

Parameters:: volume (int) -- The volume of the sound. range(0, MIX_MAX_VOLUME=>128)

get_volume()[source]#

Gets the volume of the sound.

Return type:: int
Returns:: The volume of the sound. range(0, MIX_MAX_VOLUME=>128)

classmethod import_sound_folder(path, duplicate_names=False, recursive=True)[source]#

Imports a folder of sounds, saving each one in the loaded_sounds dictionary by filename.

Parameters:

path (str) -- The relative path to the folder you wish to import.
duplicate_names -- if you wish to have duplicate names to your sounds,
name (it will use the relative and the sound path for the sounds) --
recursive (bool) -- Whether it will import an animation shallowly or recursively. Defaults to True.

classmethod get_sound(sound_name)[source]#

Gets the sound based on the sound name.

Parameters:: sound_name (str) -- The name of the sound.
Raises:: IdError -- No sound is associated to the sound name.
Returns:: The sound.
Return type:: Sound

Utilities#

These classes are utility classes that are used to make certain tasks easier.

Surface#

An abstraction for a grid of pixels that can be drawn onto.

class Surface(width=32, height=32, scale=(1, 1), rotation=0, af=False)[source]#

A grid of pixels that can be modified without being attached to a game object.

Parameters:

width (int) -- The width of the surface in pixels. Once set this cannot be changed. Defaults to 32.
height (int) -- The height of the surface in pixels. Once set this cannot be changed. Defaults to 32.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the surface. Defaults to (1, 1).
rotation (float) -- The clockwise rotation of the sprite.
af (bool) -- Whether to use anisotropic filtering. Defaults to False.

rotation: float#: The clockwise rotation of the sprite.

scale: Vector#: The scale of the sprite.

uptodate: bool#: Whether the texture is up to date with the surface. Can be set to False to trigger a texture regeneration at the next draw cycle.

property width: int#

The width of the surface in pixels (read-only).

Return type:: int

property height: int#

The height of the surface in pixels (read-only).

Return type:: int

property af#: Whether to use anisotropic filtering.

size_scaled()[source]#

Gets the current size of the Surface. (Scaled)

Return type:: Vector
Returns:: The size of the Surface

size()[source]#

Gets the current size of the Surface. (Unscaled)

Return type:: Vector
Returns:: The size of the Surface

blit(other, src_rect=None, dst=(0, 0))[source]#

Blits (merges / copies) another Surface onto this one.

Parameters:

other (Surface) -- The Surface to blit onto this one.
src_rect (Optional[tuple[int, int, int, int]]) -- The area (center_x, center_y, width, height) to crop from the source surface (other). Defaults to the whole surface.
dst (UnionType[Vector, tuple[int, int]]) -- The position to place the other surface. Defaults to (0, 0).

Note

Will not stretch the other surface to fit the destination rectangle.

flip_x()[source]#: Flips the surface horizontally.

flip_y()[source]#: Flips the surface vertically.

flip_anti_diagonal()[source]#: Flips the surface along the anti diagonal.

clear()[source]#: Clears the surface.

fill(color)[source]#

Fill the surface with a color.

Parameters:: color (Color) -- The color to fill with.

get_pixel(pos)[source]#

Gets the color of a pixel on the surface.

Parameters:: pos (UnionType[Vector, tuple[float, float]]) -- The position of the pixel.
Return type:: Color
Returns:: The color of the pixel.

set_pixel(pos, color=Color.black, blending=True)[source]#

Draws a point on the surface.

Parameters:

pos (UnionType[Vector, tuple[float, float]]) -- The position to draw the point.
color (Color) -- The color of the point. Defaults to black.
blending (bool) -- Whether to use blending. Defaults to False.

draw_line(start, end, color=Color.black, aa=False, thickness=1, blending=True)[source]#

Draws a line on the surface.

Parameters:

start (UnionType[Vector, tuple[float, float]]) -- The start of the line.
end (UnionType[Vector, tuple[float, float]]) -- The end of the line.
color (Color) -- The color of the line. Defaults to black.
aa (bool) -- Whether to use anti-aliasing. Defaults to False.
thickness (int) -- The thickness of the line. Defaults to 1.
blending (bool) -- Whether to use blending. Defaults to False.

draw_rect(center, dims, border=None, border_thickness=1, fill=None, blending=True)[source]#

Draws a rectangle on the surface.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The top left corner of the rectangle.
dims (UnionType[Vector, tuple[float, float]]) -- The dimensions of the rectangle.
border (Optional[Color]) -- The border color of the rectangle. Defaults to None.
border_thickness (int) -- The thickness of the border. Defaults to 1.
fill (Optional[Color]) -- The fill color of the rectangle. Set to None for no fill. Defaults to None.
blending (bool) -- Whether to use blending. Defaults to False.

draw_circle(center, radius, border=None, border_thickness=1, fill=None, aa=False, blending=True)[source]#

Draws a circle on the surface.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The center of the circle.
radius (int) -- The radius of the circle.
border (Optional[Color]) -- The border color of the circle. Defaults to None.
border_thickness (int) -- The thickness of the border. Defaults to 1.
fill (Optional[Color]) -- The fill color of the circle. Set to None for no fill. Defaults to None.
aa (bool) -- Whether to use anti-aliasing. Defaults to False.
blending (bool) -- Whether to use blending. Defaults to False.

draw_poly(points, center=(0, 0), border=None, border_thickness=1, fill=None, aa=False, blending=True)[source]#

Draws a polygon on the surface.

Parameters:

points (UnionType[list[Vector], list[tuple[float, float]]]) -- The points of the polygon.
center (UnionType[Vector, tuple[float, float]]) -- The center of the polygon.
border (Optional[Color]) -- The border color of the polygon. Defaults to None.
border_thickness (int) -- The thickness of the border. Defaults to 1.
fill (Optional[Color]) -- The fill color of the polygon. Set to None for no fill. Defaults to None.
aa (bool) -- Whether to use anti-aliasing. Defaults to False.
blending (bool) -- Whether to use blending. Defaults to False.

switch_color(color, new_color)[source]#

Switches a color in the surface.

Parameters:

color (Color) -- The color to switch.
new_color (Color) -- The new color to switch to.

set_colorkey(color)[source]#

Sets the colorkey of the surface.

Parameters:: color (Color) -- Color to set as the colorkey.

remove_colorkey()[source]#: Remove the colorkey of the surface.

clone()[source]#

Clones the current surface.

Return type:: Surface
Returns:: The cloned surface.

set_alpha(new)[source]#

Sets surface wide alpha.

Parameters:: new (int) -- The new alpha. (value between 0-255)

get_alpha()[source]#

Gets the surface wide alpha.

Return type:: int

save_as(filename, path='./', extension='png', save_to_temp_path=False, quality=100)[source]#

Save the surface to a file.

Parameters:

filename (str) -- The name of the file to save to.
path (str) -- Path to output folder.
extension (str) -- The extension to save the file as. (png, jpg, bmp supported)
save_to_temp_path (bool) -- Whether to save the file to a temporary path (i.e. MEIPASS used in exe).
quality (int) -- The quality of the jpg 0-100 (only used for jpgs).

Return type:

Returns:

If save was successful.

classmethod from_file(path, scale=(1, 1), rotation=0, af=False)[source]#

Loads a surface from an image file.

Parameters:

path (str) -- The path to the file.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the surface. Defaults to (1, 1).
rotation (float) -- The clockwise rotation of the sprite. Defaults to 0.
af (bool) -- Whether to use anisotropic filtering. Defaults to False.

Return type:

Surface

Returns:

The resultant surface.

Draw#

A static class for drawing things directly to the window.

class Draw[source]#

A static class allowing drawing items to the window.

classmethod clear(background_color=Color.white, border_color=Color.black)[source]#

Clears the screen and draws a background.

Parameters:

background_color (Color) -- The background color. Defaults to white.
border_color (Color) -- The border color. Defaults to black. Shown when the aspect ratio of the game does not match the aspect ratio of the window.

classmethod queue_pixel(pos, color=Color.cyan, z_index=0, camera=None)[source]#

Draw a point onto the renderer at the end of the frame.

Parameters:

pos (UnionType[Vector, tuple[float, float]]) -- The position of the point.
color (Color) -- The color to use for the pixel. Defaults to Color.cyan.
z_index (int) -- Where to draw it in the drawing order. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod pixel(pos, color=Color.cyan, camera=None)[source]#

Draw a point onto the renderer immediately.

Parameters:

pos (UnionType[Vector, tuple[float, float]]) -- The position of the point.
color (Color) -- The color to use for the pixel. Defaults to Color.cyan.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod queue_line(p1, p2, color=Color.cyan, width=1, z_index=0, camera=None)[source]#

Draw a line onto the renderer at the end of the frame.

Parameters:

p1 (UnionType[Vector, tuple[float, float]]) -- The first point of the line.
p2 (UnionType[Vector, tuple[float, float]]) -- The second point of the line.
color (Color) -- The color to use for the line. Defaults to Color.cyan.
width (UnionType[int, float]) -- The width of the line. Defaults to 1.
z_index (int) -- Where to draw it in the drawing order. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

static line(p1, p2, color=Color.cyan, width=1, camera=None)[source]#

Draw a line onto the renderer immediately.

Parameters:

p1 (UnionType[Vector, tuple[float, float]]) -- The first point of the line.
p2 (UnionType[Vector, tuple[float, float]]) -- The second point of the line.
color (Color) -- The color to use for the line. Defaults to Color.cyan.
width (UnionType[int, float]) -- The width of the line. Defaults to 1.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod queue_rect(center, width, height, border=Color.cyan, border_thickness=1, fill=None, angle=0, z_index=0, camera=None)[source]#

Draws a rectangle onto the renderer at the end of the frame.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The center of the rectangle.
width (UnionType[int, float]) -- The width of the rectangle.
height (UnionType[int, float]) -- The height of the rectangle.
border (Optional[Color]) -- The border color. Defaults to Color.cyan.
border_thickness (UnionType[int, float]) -- The border thickness. Defaults to 1.
fill (Optional[Color]) -- The fill color. Defaults to None.
angle (float) -- The angle in degrees. Defaults to 0.
z_index (int) -- Where to draw it in the drawing order. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod rect(center, width, height, border=Color.cyan, border_thickness=1, fill=None, angle=0, camera=None)[source]#

Draws a rectangle onto the renderer immediately.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The center of the rectangle.
width (UnionType[int, float]) -- The width of the rectangle.
height (UnionType[int, float]) -- The height of the rectangle.
border (Optional[Color]) -- The border color. Defaults to Color.cyan.
border_thickness (UnionType[int, float]) -- The border thickness. Defaults to 1.
fill (Optional[Color]) -- The fill color. Defaults to None.
angle (float) -- The angle in degrees. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

Raises:

ValueError -- If the width and height are not positive.

classmethod queue_circle(center, radius=4, border=Color.cyan, border_thickness=1, fill=None, z_index=0, camera=None)[source]#

Draws a circle onto the renderer at the end of the frame.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The center.
radius (int) -- The radius. Defaults to 4.
border (Optional[Color]) -- The border color. Defaults to Color.cyan.
border_thickness (UnionType[int, float]) -- The border thickness. Defaults to 1.
fill (Optional[Color]) -- The fill color. Defaults to None.
z_index (int) -- Where to draw it in the drawing order. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod circle(center, radius=4, border=Color.cyan, border_thickness=1, fill=None, camera=None)[source]#

Draws a circle onto the renderer immediately.

Parameters:

center (UnionType[Vector, tuple[float, float]]) -- The center.
radius (UnionType[int, float]) -- The radius. Defaults to 4.
border (Optional[Color]) -- The border color. Defaults to Color.cyan.
border_thickness (UnionType[int, float]) -- The border thickness. Defaults to 1.
fill (Optional[Color]) -- The fill color. Defaults to None.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

Raises:

ValueError -- If the radius is not positive.

classmethod queue_poly(points, center, border=Color.cyan, border_thickness=1, fill=None, z_index=0, camera=None)[source]#

Draws a polygon onto the renderer at the end of the frame.

Parameters:

points (UnionType[list[Vector], list[tuple[float, float]]]) -- The list of points to draw relative to the center.
center (UnionType[Vector, tuple[float, float]]) -- The center of the polygon.
border (Optional[Color]) -- The border color. Defaults to Color.cyan.
border_thickness (UnionType[int, float]) -- The border thickness. Defaults to 1.
fill (Optional[Color]) -- The fill color. Defaults to None.
z_index (int) -- Where to draw it in the drawing order. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod poly(points, center, border=Color.cyan, border_thickness=1, fill=None, camera=None)[source]#

Draws a polygon onto the renderer immediately.

Parameters:

points (UnionType[list[Vector], list[tuple[float, float]]]) -- The list of points to draw relative to the center.
center (UnionType[Vector, tuple[float, float]]) -- The center of the polygon.
border (Optional[Color]) -- The border color. Defaults to Color.cyan.
border_thickness (UnionType[int, float]) -- The border thickness. Defaults to 1.
fill (Optional[Color]) -- The fill color. Defaults to None.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod queue_text(text, font, pos=(0, 0), justify='left', align=(0, 0), width=0, scale=(1, 1), shadow=False, shadow_pad=(0, 0), af=True, z_index=0, camera=None)[source]#

Draws some text onto the renderer at the end of the frame.

Parameters:

text (str) -- The text to draw.
font (Font) -- The Font object to use.
pos (UnionType[Vector, tuple[float, float]]) -- The top left corner of the text. Defaults to (0, 0).
justify (str) -- The justification of the text. (left, center, right). Defaults to "left".
align (UnionType[Vector, tuple[float, float]]) -- The alignment of the text. Defaults to (0, 0).
width (UnionType[int, float]) -- The maximum width of the text. Will automatically wrap the text. Defaults to -1.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the text. Defaults to (1, 1).
shadow (bool) -- Whether to draw a basic shadow box behind the text. Defaults to False.
shadow_pad (UnionType[Vector, tuple[float, float]]) -- What padding to use for the shadow. Defaults to (0, 0).
af (bool) -- Whether to use anisotropic filtering. Defaults to True.
z_index (int) -- Where to draw it in the drawing order. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod text(text, font, pos=(0, 0), justify='left', align=(0, 0), width=0, scale=(1, 1), shadow=False, shadow_pad=(0, 0), af=True, camera=None)[source]#

Draws some text onto the renderer immediately.

Parameters:

text (str) -- The text to draw.
font (Font) -- The Font object to use.
pos (UnionType[Vector, tuple[float, float]]) -- The top left corner of the text. Defaults to (0, 0).
justify (str) -- The justification of the text. (left, center, right). Defaults to "left".
align (UnionType[Vector, tuple[float, float]]) -- The alignment of the text. Defaults to (0, 0).
width (UnionType[int, float]) -- The maximum width of the text. Will automatically wrap the text. Defaults to -1.
scale (UnionType[Vector, tuple[float, float]]) -- The scale of the text. Defaults to (1, 1).
shadow (bool) -- Whether to draw a basic shadow box behind the text. Defaults to False.
shadow_pad (UnionType[Vector, tuple[float, float]]) -- What padding to use for the shadow. Defaults to (0, 0).
af (bool) -- Whether to use anisotropic filtering. Defaults to True.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod queue_surface(surface, pos=(0, 0), z_index=0, camera=None)[source]#

Draws an surface onto the renderer at the end of the frame.

Parameters:

surface (Surface) -- The surface to draw.
pos (UnionType[Vector, tuple[float, float]]) -- The position to draw the surface at. Defaults to (0, 0).
z_index (int) -- The z-index of the surface. Defaults to 0.
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod surface(surface, pos=(0, 0), camera=None)[source]#

Draws an surface onto the renderer immediately.

Parameters:

surface (Surface) -- The surface to draw.
pos (UnionType[Vector, tuple[float, float]]) -- The position to draw the surface at. Defaults to (0, 0).
camera (Optional[Camera]) -- The camera to use. Defaults to None.

classmethod clear_cache()[source]#

Clears the draw cache.

Generally, you shouldn't need to call this method, but it can help free up memory if you're running low; the true best way to avoid this though is to rely on surfaces for shapes that change/recolor often, and call the draw surface method directly instead of the draw shape methods.

Vector#

An abstraction for a container of x and y values.

class Vector(x=0, y=0)[source]#

A Vector object that defines a 2D point in space

Parameters:

x (UnionType[float, int]) -- The x coordinate. Defaults to 0.
y (UnionType[float, int]) -- The y coordinate. Defaults to 0.

x: float = None#: The x coordinate.

y: float = None#: The y coordinate.

property magnitude: float#

The magnitude of the vector. You can set to this value.

Return type:: float

property mag_sq: float#

The squared magnitude of the vector (readonly).

Return type:: float

property angle: float#

The angle of the vector in north-degrees (readonly).

Return type:: float

property rationalized_mag: str#

Returns a string representation of a rationalized vector magnitude as you would use in math class.

Example

>>> Vector(8, 8).rationalized_mag
4√8

Warning

Should only be used on vectors with integer components.

Return type:: str

property rationalized_mag_vector: Vector#

Returns a vector with the rationalized magnitude.

Example

>>> Vector(8, 8).rationalized_mag
rubato.Vector(4, 8)

Warning

Should only be used on vectors with integer components.

Return type:: Vector

property rationalized_unit: str#

Returns a string representation of a rationalized unit vector as you would use in math class.

Warning

Should only be used on vectors with integer components.

Return type:: str

normalized(out=None)[source]#

Determines the unit vector of this vector.

Parameters:: out (Vector, optional) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.
Returns:: The vector output of the operation.
Return type:: Vector

normalize()[source]#: Normalizes the current vector.

sum()[source]#: Sums the x and y coordinates of the vector.

dot(other)[source]#

Takes the dot product of two vectors.

Parameters:: other (Vector) -- The other vector.
Return type:: UnionType[float, int]
Returns:: The resulting dot product.

cross(other)[source]#

Takes the cross product of two vectors.

Parameters:: other (Vector) -- The other vector.
Return type:: UnionType[float, int]
Returns:: The resultant scalar magnitude of the orthogonal vector along an imaginary z-axis.

perpendicular(scalar=1, out=None)[source]#

Computes a scaled 90 degree clockwise rotation on a given vector.

Parameters:

scalar (UnionType[float, int]) -- The scalar value.
out (Optional[Vector]) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.

Return type:

Returns:

The resultant vector when transformed.

clamp(lower, upper, absolute=False, out=None)[source]#

Clamps x and y between the two values given.

Parameters:

lower (UnionType[Vector, float, int]) -- The lower bound. If a vector is specified, its x coord is used to clamp the x coordinate and same for y.
upper (UnionType[Vector, float, int]) -- The upper bound. If a vector is specified, its x coord is used to clamp the x coordinate and same for y.
absolute (bool) -- Whether to clamp the absolute value of the vector instead of the actual value. Defaults to False.
out (Optional[Vector]) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.

rotate(angle, out=None)[source]#

Rotates the vector by a given number of degrees.

Parameters:

angle (UnionType[float, int]) -- The rotation amount in north-degrees you want to rotate by (relative).
out (Optional[Vector]) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.

Return type:

Returns:

The resultant Vector.

to_tuple()[source]#

Returns the x and y coordinates of the vector as a tuple.

Return type:: tuple[float, float]

tuple_int()[source]#

Returns a tuple with int-cast values.

Return type:: tuple[int, int]

clone()[source]#

Returns a copy of the vector.

Return type:: Vector

lerp(target, t, out=None)[source]#

Lerps the current vector to target by a factor of t.

Parameters:

target (Vector) -- The target Vector.
t (UnionType[float, int]) -- The lerping amount (between 0 and 1).
out (Optional[Vector]) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.

Return type:

Returns:

The resulting vector.

round(decimal_places=0, out=None)[source]#

Returns a new vector with the coordinates rounded.

Parameters:

decimal_places (int) -- The amount of decimal places rounded to. Defaults to 0.
out (Vector, optional) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.

Returns:

The resultant Vector.

Return type:

Vector

max()[source]#

Returns the maximum of x and y.

Return type:: float

min()[source]#

Returns the minimum of x and y.

Return type:: float

ceil(out=None)[source]#

Returns a new vector with the coordinates ciel-ed.

Parameters:: out (Vector, optional) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.
Returns:: The resultant Vector.
Return type:: Vector

floor(out=None)[source]#

Returns a new vector with the coordinates floored.

Parameters:: out (Vector, optional) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.
Returns:: The resultant Vector.
Return type:: Vector

abs(out=None)[source]#

Returns a new vector with the absolute value of the original coordinates.

Parameters:: out (Vector, optional) -- The output vector to set to. Defaults to a new vector. If you want the function to act on itself, set this value to the reference of the vector.
Returns:: The resultant Vector.
Return type:: Vector

dir_to(other)[source]#

Direction from the Vector to another Vector (or tuple of floats).

Parameters:: other (UnionType[Vector, tuple[float, float]]) -- the position to which you are pointing
Return type:: Vector
Returns:: A unit vector that is in the pointing to the other position passed in

dist_to(other)[source]#

Finds the pythagorean distance to another vector (or tuple of floats).

Parameters:: other (UnionType[Vector, tuple[float, float]]) -- The other vector.
Return type:: float
Returns:: The distance.

within(other, distance)[source]#

Checks if the vector is within a certain distance of another vector (or tuple of floats).

Parameters:

other (UnionType[Vector, tuple[float, float]]) -- The other vector
distance (UnionType[float, int]) -- The distance to check

Return type:

Returns:

True if the vector is within the distance, False otherwise

static from_radial(magnitude, angle)[source]#

Generates a Vector from the given angle and magnitude.

Parameters:

magnitude (UnionType[float, int]) -- Length of vector.
angle (UnionType[float, int]) -- Direction of vector in North degrees.

Return type:

Returns:

Vector from the given direction and distance

static clamp_magnitude(vector, max_magnitude, min_magnitude=0)[source]#

Clamps the magnitude of the vector to the given range.

Parameters:

vector (Vector) -- The vector to clamp.
max_magnitude (UnionType[float, int]) -- The maximum magnitude of the vector.
min_magnitude (UnionType[float, int]) -- The minimum magnitude of the vector. Defaults to 0.

Return type:

Returns:

A new vector with the magnitude clamped to the given range.

classmethod angle_between(a, b)[source]#

Returns the smallest possible angle between two vectors.

Parameters:

a (Vector) -- First vector.
b (Vector) -- Second vector.

Return type:

float

Returns:

Angle in degrees between the two vectors.

classmethod rand_unit_vector()[source]#

Returns a random unit vector inside the unit circle.

Return type:: Vector
Returns:: Random vector inside the unit circle.

classmethod poly(num_sides, radius=1)[source]#

Returns a list of vectors representing a polygon with the given number of sides and radius.

Parameters:

num_sides (int) -- The number of sides of the polygon.
radius (UnionType[float, int]) -- The radius of the polygon. Defaults to 1.

Raises:

SideError -- If num_sides is less than 3.

Return type:

list[Vector]

Returns:

The list of vectors representing the polygon.

classmethod rect(width, height)[source]#

Returns a list of vectors representing a rectangle with the given width and height.

Parameters:

width (float | int) -- The width of the rectangle.
height (float | int) -- The height of the rectangle.

Returns:

The list of vectors representing the rectangle.

Return type:

list[Vector]

static zero()[source]#: A zeroed Vector

static one()[source]#

A Vector with all ones

Return type:: Vector

static up()[source]#: A Vector in the up direction

static left()[source]#: A Vector in the left direction

static down()[source]#: A Vector in the down direction

static right()[source]#: A Vector in the right direction

static infinity()[source]#: A Vector at positive infinity

static create(obj)[source]#

Makes a Vector from a Vector-like object.

Parameters:: obj (UnionType[Vector, tuple[float, float]]) -- The object to make a Vector from.
Return type:: Vector

Math#

The math module includes some helper functions for commonly used equations.

class Math[source]#

Adds additonal functionality to the math module that is commonly used in game development.

INF: int = 2147483647#: The max value of a 32-bit integer.

PI_HALF: float = 1.5707963267948966#: The value of pi / 2.

PI_TWO: float = 6.283185307179586#: The value of pi * 2.

static clamp(a, lower, upper)[source]#

Clamps a value.

Parameters:

a (UnionType[float, int]) -- The value to clamp.
lower (UnionType[float, int]) -- The lower bound of the clamp.
upper (UnionType[float, int]) -- The upper bound of the clamp.

Returns:

The clamped result.

Return type:

static sign(n)[source]#

Checks the sign of n.

Parameters:: n (UnionType[float, int]) -- A number to check.
Return type:: int
Returns:: The sign of the number. (1 for positive, 0 for 0, -1 for negative)

static lerp(a, b, t)[source]#

Linearly interpolates between lower and upper bounds by t

Parameters:

a (UnionType[float, int]) -- The lower bound.
b (UnionType[float, int]) -- The upper bound.
t (float) -- Distance between upper and lower (1 gives b, 0 gives a).

Returns:

The linearly interpolated value.

Return type:

classmethod map(variable, variable_lower, variable_upper, map_lower, map_upper)[source]#

Maps the variable from its range defined by lower and upper to a new range defined by map_lower and map_upper.

Parameters:

variable -- The variable to map.
variable_lower -- The lower bound of the variable.
variable_upper -- The upper bound of the variable.
map_lower -- The lower bound of the new range.
map_upper -- The upper bound of the new range.

Returns:

The mapped value.

Return type:

static floor(x)[source]#

Quickly rounds down a number.

Parameters:: x (float) -- The number to round.
Returns:: The rounded number.
Return type:: int

static ceil(x)[source]#

Quickly rounds up a number.

Parameters:: x (float) -- The number to round.
Returns:: The rounded number.
Return type:: int

static is_int(x, error=0)[source]#

Checks if a float can be rounded to an integer without dropping decimal places (within a certain error).

Parameters:

x (float) -- The number to check.
error (float) -- The error margin from int that we accept, used for float inaccuracy.

Return type:

Returns:

True if the number is an integer within the error.

static simplify_sqrt(square_rooted)[source]#

Simplifies a square root.

Parameters:: square_rooted (int) -- The sqrt to simplify (inside the sqrt).
Return type:: tuple
Returns:: The simplified square root, (multiple, square rooted).

Example

Will try to simplify radicals.

>>> Math.simplify_sqrt(16) # √16 = 4√1
(4, 1)
>>> Math.simplify_sqrt(26) # √26 = 1√26
(1, 26)
>>> Math.simplify_sqrt(20) # √20 = 2√5

static simplify(a, b)[source]#

Simplifies a fraction.

Parameters:

a (int) -- numerator.
b (int) -- denominator.

Return type:

tuple

Returns:

The simplified fraction, (numerator, denominator).

static gen_primes()[source]#

Generate an infinite sequence of prime numbers. A python generator ie. must use next().

Notes

Sieve of Eratosthenes Code by David Eppstein, UC Irvine, 28 Feb 2002 http://code.activestate.com/recipes/117119/

Returns:: A generator of prime numbers.
Return type:: generator

Example

>>> generator = Math.gen_primes()
>>> next(generator)
2

static north_deg_to_rad(deg)[source]#

Converts a north-degrees (naturally used in rubato) to east-radians.

Parameters:: deg (float) -- North-degrees.
Return type:: float
Returns:: East-radians.

static rad_to_north_deg(rad)[source]#

Converts east-radians to north-degrees (naturally used in rubato).

Parameters:: rad (float) -- East-radians.
Return type:: float
Returns:: North-degrees.

Noise#

A utility for generating simple smooth noise in your projects.

class Noise[source]#

A utility for generating simple smooth noise, based on OpenSimplex2.

seed: int = 0#: The seed for the random noise. Setting to a fixed value will result in the same noise every time.

classmethod noise(x)[source]#

Creates noise from 1 dimensional input. This is identical to noise2(x, 0).

Parameters:: x (float) -- the x coordinate of noise.
Returns:: the random noise value.
Return type:: float

classmethod noise2(x, y)[source]#

Creates noise from 2 dimensional input.

Parameters:

x (float) -- the x coordinate of noise.
y (float) -- the y coordinate of noise.

Returns:

the random noise value.

Return type: