pygame_zer package

pygame_zer allows you to add zoomable and explorable regions to your pygame window. Once a driver is created, you can display its contents and pan/zoom around the world.

Everything starts from the Driver class. Once a driver is made, other objects can be added to it using their constructors. Everything else is handled internally.

import pygame
import pygame_zer

pygame.init()
screen = pygame.display.set_mode((1280, 720))
driver = pygame_zer.Driver(screen)

pygame_zer.Rect(driver, (50, 50, 100, 100))
pygame_zer.Circle(driver, (100, 100), 25, fill="red")

running = True
while running:
    for event in pygame.event.get():
        if driver.handle_event(event):
            continue
        if event.type == pygame.QUIT:
            running = False

    screen.fill((50, 50, 50))
    driver.draw()

    pygame.display.flip()

pygame.quit()

Some things are automatically exported by the default module import. These include:

Circle: pygame_zer.circle.Circle
Image: pygame_zer.image.Image
Line: pygame_zer.line.Line
Rect: pygame_zer.rect.Rect
Text: pygame_zer.text.Text
Driver: pygame_zer.driver.Driver

Flags: pygame_zer.driver.DriverFlags

F_EMPTY
F_ZOOMABLE
F_EXPLORABLE
F_NOCACHE
F_DEFAULT

Please see the GitHub repository for more examples.

class pygame_zer.camera.Camera(surface: Surface, topleft: tuple[float, float], rendersize: tuple[float, float], camerazoom: float)[source]

Bases: object

A camera for pygame_zer calculations. Anything related to zooming/panning and point/distance conversion is handled through this class.

Points either exist in “world space” or “camera space”. World space points store the coordinate of a point in the actual world the camera is looking into. Camera space points store the location of the point on the screen (e.g. 0,0 for the top left).

camerazoom

The camera zoom, e.g. 2 for 2x

Type:: float

rendersize

The output size of the camera

Type:: pygame_zer.types.Vec2f

surface

The pygame surface to draw to

Type:: pygame.Surface

topleft

The topleft of the camera in worldspace

Type:: pygame_zer.types.Vec2f

minzoom

The minimum zoom level

Type:: float, default=0.02

maxzoom

The maximum zoom level

Type:: float, default=50

distance_to_camera(distance:float) : float: Converts a distance from world space to camera space

point_to_camera(pt:pygame_zer.types.Vec2f) : pygame_zer.types.Vec2i: Converts a point from world space to camera space

translate(rel: pygame_zer.types.Vec2f)[source]: Translate the camera in worldspace

zoom(rel: float)[source]: Zooms in or out. rel should be -1 or 1

distance_to_camera(distance: float) → float[source]

Converts a distance from world space to camera space

Parameters:: distance (float) – The distance to convert. Must be in world space.

point_to_camera(pt: tuple[float, float]) → tuple[int, int][source]

Converts a point from world space to camera space

Parameters:: pt (pygame_zer.types.Vec2f) – The point to convert. Must be in world space.

translate(rel: tuple[float, float])[source]

Translate the camera in worldspace

Parameters:: rel (pygame_zer.types.Vec2f) – The distance to translate. This distance is in world space.

zoom(rel: float)[source]

Zooms in or out. rel should be -1 or 1

Parameters:: rel (float) – Whether to zoom in or out. -1 zooms out and 1 zooms in. All other values are unintended behavior.

class pygame_zer.circle.Circle(driver: Driver, center: tuple[int, int], radius: float, fill='black', outlineWidth: float = 1, outline=None)[source]

Bases: Shape

A pygamezer circle. You should use this class if you want to create a circle in the driver world. The constructor will add the shape to the driver for you. You can modify attributes of the circle after the constructor is run.

center

The center of the circle in world space

Type:: pygame_zer.types.Vec2i

driver

The driver this circle is attached to

Type:: pygame_zer.Driver

fill

The color to fill the circle with

Type:: str

radius

The radius of the circle in world space

Type:: float

outline

The color to outline the circle with. Default nothing

Type:: str, optional

outlineWidth

The width of the circle outline in world space. Default 1

Type:: float, default=1

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

pygame_zer.driver.DEFAULT_FLAGS = <DriverFlags.ZOOMABLE|EXPLORABLE: 6>: The default flags for a driver

class pygame_zer.driver.Driver(surface: ~pygame.surface.Surface, flags: ~pygame_zer.driver.DriverFlags = <DriverFlags.ZOOMABLE|EXPLORABLE: 6>)[source]

Bases: object

The driver for all pygame-zer functionality. Everything done using pygame-zer must happen through this driver. It contains a camera for point translation, a drawer to manage shapes, and any flags to modify behavior.

camera

The driver camera. Should be modified directly using driver.camera

Type:: pygame_zer.Camera

flags

The driver flags. Should not be modified after setting. Can be accessed by other classes in order to customize behavior

Type:: pygame_zer.DriverFlags

draw(): Draw to the camera/access the driver drawer.

handle_event(event:pygame.event.Event) : bool: Handle a pygame event. Returns true if handled.

_insert_shape()[source]: Add a shape to the driver drawer. Only used by shape classes.

property draw

Draw to the camera/access the driver drawer.

Driver.draw() is almost always used as a standalone called function to draw all registered shapes to the camera. However, it also returns a DriverDrawer that can perform immediate-mode drawing operations in camera space. This may incur performance hits.

handle_event(event: Event) → bool[source]

Handle a pygame event.

Call this method in your pygame event loop. This handles all pygame events related to pygame-zer and returns true if the event applied to this driver. If the event does not apply to pygame-zer and should be handled separately, this method returns false.

Parameters:: event (pygame.event.Event) – The event to attempt to handle

class pygame_zer.driver.DriverDrawer(camera: Camera)[source]

Bases: object

The drawer for the driver. This class handles all drawing actions performed. This class should not be used directly other than for immediate-mode drawing.

circle(color: pygame_zer.types.Color, center: pygame_zer.types.Vec2f, radius: float, width: float = 0)[source]: Draw a circle immediately

rect(color: pygame_zer.types.Color, rect: pygame_zer.types.Rectf, width: float = 0)[source]: Draw a rectangle immediately

line(color: pygame_zer.types.Color, start_pos: pygame_zer.types.Vec2f, end_pos: pygame_zer.types.Vec2f, width: float = 1)[source]: Draw a line immediately

circle(color: str, center: tuple[float, float], radius: float, width: float = 0)[source]: Draw a circle immediately

line(color: str, start_pos: tuple[float, float], end_pos: tuple[float, float], width: float = 1)[source]: Draw a line immediately

rect(color: str, rect: tuple[float, float, float, float], width: float = 0)[source]: Draw a rectangle immediately

class pygame_zer.driver.DriverFlags(*values)[source]

Bases: Flag

Flags to apply to a driver.

These flags can be or’d together to combine various features.

EMPTY: A featureless flag. This only exists to create a starting state for building optional flag features. Disabled by default

ZOOMABLE: Allow zooming in and out. Enabled by default

EXPLORABLE: Allow panning up/down/left/right. Enabled by default

NOCACHE: Disable caching, may reduce performance. Disabled by default

EMPTY = 1

EXPLORABLE = 4

NOCACHE = 8

ZOOMABLE = 2

class pygame_zer.image.Image(driver: Driver, source: Surface, dest: tuple[float, float], size: tuple[float, float] | None = None)[source]

Bases: Shape

A pygamezer image. You should use this class if you want to create an image in the driver world. The constructor will add the shape to the driver for you.

You can set a desired output size in world space in the constructor. If you do, the image will be scaled to fit the requested size, which may change the aspect ratio.

dest

The topleft of the image in world space

Type:: pygame_zer.types.Vec2f

driver

The driver this image is attached to

Type:: pygame_zer.Driver

image_size

The size of the internal source image. This is not necessarily the same as the original source size, since a custom output size can change the aspect ratio

Type:: pygame_zer.types.Vec2f

source

The image/surface to draw. This may be scaled internally to a different size if a custom size argument is specified

Type:: pygame.Surface

size

The size of the image in world space. Default the original source size

Type:: pygame_zer.types.Vec2f, optional

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

scaled_source(camera: Camera) → tuple[tuple[int, int], Surface] | None[source]

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

class pygame_zer.line.Line(driver: Driver, p1: tuple[float, float], p2: tuple[float, float], fill='black')[source]

Bases: Shape

A pygamezer line. You should use this class if you want to create a line in the driver world. The constructor will add the shape to the driver for you. You can modify attributes of the line after the constructor is run.

driver

The driver this line is attached to

Type:: pygame_zer.Driver

fill

The color of the line

Type:: str

p1

The first point

Type:: pygame_zer.types.Vec2f

p2

The second point

Type:: pygame_zer.types.Vec2f

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

class pygame_zer.rect.Rect(driver: Driver, rect: tuple[float, float, float, float], fill='black', outlineWidth: float = 1, outline: str = 'black')[source]

Bases: Shape

A pygamezer rectangle. You should use this class if you want to create a rectangle in the driver world. The constructor will add the shape to the driver for you. You can modify attributes of the rectangle after the constructor is run.

driver

The driver this rectangle is attached to

Type:: pygame_zer.Driver

fill

The color to fill the rectangle with

Type:: str

rect

The rectangle range to draw to in world space

Type:: pygame_zer.types.Rectf

outline

The color to outline the rectangle with. Default nothing

Type:: str, optional

outlineWidth

The width of the rectangle outline in world space. Default 1

Type:: float, default=1

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

class pygame_zer.shape.Shape[source]

Bases: object

The abstract shape class.

All shapes must be drawable to a camera and translatable to another location. The shape class is non-exhaustive and should not be treated as an exhaustive class.

draw(camera)[source]: Draws the shape to the camera specified.

translate(x, y)[source]: Moves the shape the specified distance in world space.

abstractmethod draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

abstractmethod translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

class pygame_zer.text.Text(driver: Driver, pos: tuple[float, float], font: Font, text: str, fill: str = 'black')[source]

Bases: Image

A pygamezer text display. You should use this class if you want to create text in the driver world. The constructor will add the shape to the driver for you.

Text displays extend the image class and are handled the same as images

font

The font to use for the text

Type:: pygame.freetype.Font

font_size

The font size

Type:: float

nocache

Forces no caching if true. Set in driver flags

Type:: bool

text

The text as a string

Type:: str

fill

The text color

Type:: str, default=”black”

property font_size: float

scaled_source(camera: Camera) → tuple[tuple[int, int], Surface] | None[source]

class pygame_zer.Circle(driver: Driver, center: tuple[int, int], radius: float, fill='black', outlineWidth: float = 1, outline=None)[source]

Bases: Shape

A pygamezer circle. You should use this class if you want to create a circle in the driver world. The constructor will add the shape to the driver for you. You can modify attributes of the circle after the constructor is run.

center

The center of the circle in world space

Type:: pygame_zer.types.Vec2i

driver

The driver this circle is attached to

Type:: pygame_zer.Driver

fill

The color to fill the circle with

Type:: str

radius

The radius of the circle in world space

Type:: float

outline

The color to outline the circle with. Default nothing

Type:: str, optional

outlineWidth

The width of the circle outline in world space. Default 1

Type:: float, default=1

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

class pygame_zer.Driver(surface: ~pygame.surface.Surface, flags: ~pygame_zer.driver.DriverFlags = <DriverFlags.ZOOMABLE|EXPLORABLE: 6>)[source]

Bases: object

The driver for all pygame-zer functionality. Everything done using pygame-zer must happen through this driver. It contains a camera for point translation, a drawer to manage shapes, and any flags to modify behavior.

camera

The driver camera. Should be modified directly using driver.camera

Type:: pygame_zer.Camera

flags

The driver flags. Should not be modified after setting. Can be accessed by other classes in order to customize behavior

Type:: pygame_zer.DriverFlags

draw(): Draw to the camera/access the driver drawer.

handle_event(event:pygame.event.Event) : bool: Handle a pygame event. Returns true if handled.

_insert_shape()[source]: Add a shape to the driver drawer. Only used by shape classes.

property draw

Draw to the camera/access the driver drawer.

Driver.draw() is almost always used as a standalone called function to draw all registered shapes to the camera. However, it also returns a DriverDrawer that can perform immediate-mode drawing operations in camera space. This may incur performance hits.

handle_event(event: Event) → bool[source]

Handle a pygame event.

Call this method in your pygame event loop. This handles all pygame events related to pygame-zer and returns true if the event applied to this driver. If the event does not apply to pygame-zer and should be handled separately, this method returns false.

Parameters:: event (pygame.event.Event) – The event to attempt to handle

class pygame_zer.Image(driver: Driver, source: Surface, dest: tuple[float, float], size: tuple[float, float] | None = None)[source]

Bases: Shape

A pygamezer image. You should use this class if you want to create an image in the driver world. The constructor will add the shape to the driver for you.

You can set a desired output size in world space in the constructor. If you do, the image will be scaled to fit the requested size, which may change the aspect ratio.

dest

The topleft of the image in world space

Type:: pygame_zer.types.Vec2f

driver

The driver this image is attached to

Type:: pygame_zer.Driver

image_size

The size of the internal source image. This is not necessarily the same as the original source size, since a custom output size can change the aspect ratio

Type:: pygame_zer.types.Vec2f

source

The image/surface to draw. This may be scaled internally to a different size if a custom size argument is specified

Type:: pygame.Surface

size

The size of the image in world space. Default the original source size

Type:: pygame_zer.types.Vec2f, optional

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

scaled_source(camera: Camera) → tuple[tuple[int, int], Surface] | None[source]

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

class pygame_zer.Line(driver: Driver, p1: tuple[float, float], p2: tuple[float, float], fill='black')[source]

Bases: Shape

A pygamezer line. You should use this class if you want to create a line in the driver world. The constructor will add the shape to the driver for you. You can modify attributes of the line after the constructor is run.

driver

The driver this line is attached to

Type:: pygame_zer.Driver

fill

The color of the line

Type:: str

p1

The first point

Type:: pygame_zer.types.Vec2f

p2

The second point

Type:: pygame_zer.types.Vec2f

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

pygame_zer.PygameDriver: alias of Driver

class pygame_zer.Rect(driver: Driver, rect: tuple[float, float, float, float], fill='black', outlineWidth: float = 1, outline: str = 'black')[source]

Bases: Shape

A pygamezer rectangle. You should use this class if you want to create a rectangle in the driver world. The constructor will add the shape to the driver for you. You can modify attributes of the rectangle after the constructor is run.

driver

The driver this rectangle is attached to

Type:: pygame_zer.Driver

fill

The color to fill the rectangle with

Type:: str

rect

The rectangle range to draw to in world space

Type:: pygame_zer.types.Rectf

outline

The color to outline the rectangle with. Default nothing

Type:: str, optional

outlineWidth

The width of the rectangle outline in world space. Default 1

Type:: float, default=1

draw(camera: Camera)[source]

Draws the shape to the camera specified.

Parameters:: camera (pygame_zer.Camera) – The camera to draw the shape to

translate(x: float, y: float)[source]

Moves the shape the specified distance in world space.

Parameters:

x (float) – The distance to move along the x axis
y (float) – The distance to move along the y axis

class pygame_zer.Text(driver: Driver, pos: tuple[float, float], font: Font, text: str, fill: str = 'black')[source]

Bases: Image

A pygamezer text display. You should use this class if you want to create text in the driver world. The constructor will add the shape to the driver for you.

Text displays extend the image class and are handled the same as images

font

The font to use for the text

Type:: pygame.freetype.Font

font_size

The font size

Type:: float

nocache

Forces no caching if true. Set in driver flags

Type:: bool

text

The text as a string

Type:: str

fill

The text color

Type:: str, default=”black”

property font_size: float

scaled_source(camera: Camera) → tuple[tuple[int, int], Surface] | None[source]