The Foolproof Game Framework
Explore the docs »
Report Bug
·
Request Feature
Table of Contents
Pyrite is a framework for eliminating much of the boilerplate of setting up a pygame project and getting running, while encouraging good project architecture with proper seperation of responsibilities among game elements. It includes several built-in systems to get development up and going.
Pyrite is written in pure python, with no system dependencies, and should be OS-agnostic.
Pyrite can be installed from the PyPI using pip:
pip install pyrite-frameworkand can be imported for use with:
import pyritePyrite additionally is built for pygame-ce, which must also be installed.
At its core, Pyrite is built around a single main class: the Game class. Game is useable as-is in its default state, or it can be subclassed to allow for more specific behaviors.
A game can be started in multiple ways.
- Traditional way
import pyrite
my_game = pyrite.Game() # Creating with default settings
# ----------------------
#
# Game setup stuff here
#
# ----------------------
my_game.main()This will create a window with a black background, at the default size (800x600), with a caption of "Game"
Keep in mind, anything after calling main() will be on hold until after the game stops running.
- Context Manager
Alternatively, we can use python's with syntax to create a game.
import pyrite
with pyrite.Game() as my_game:
# ----------------------
#
# Game setup stuff here
#
# ----------------------As with the above example, this will start a game with default settings. As a context manager, Game will start itself once the context ends.
Using context manager syntax offers a couple benefits.
-
Avoids needing to manually call main().
This is minor, but it's an additional step that needs to be minded otherwise.
-
Indentation helps make it clear what code is being used to set up the game.
-
Errors are captured.
Any error that occurs during the set up will be captured by the context manager, and Game has a setting to suppress these errors.
Game has several data classes that hold information for it. You can construct the yourself and pass them to the game instance, or you can pass their parameters as keywords into the Game constructor.
# This:
display_settings = DisplaySettings((400, 300))
with Game(display_settings=display_settings) as my_game:
...
# Is the same as this
with Game(resolution=(400, 300)) as my_game:
...A game is built around a loop, and that loop has certain phases. The pyrite game loop offers these phases:
-
Events: The pygame event queue is processed
-
Const_update: Runs at a fixed rate, regardless of frame rate. Useful for time-invariant things, like physics.
-
Pre_update: Runs earlier than the main update phase.
-
Update: Main update phase. Most logic is run here.
-
Post-update: Runs after the main update phase.
-
Render: For drawing to the screen.
The basic Game class will call each of the phases on all enabled Entities and Renderables, but also has these available as methods to allow for more specific behavior when subclassed.
These are the core feature of Pyrite. Most objects in your game should inherit from at least one of these. They allow you to define behaviors, and render out images onto the screen.
An entity is any object that has behavior. They can be typical objects, like an enemy, or obstacle, or they can be systems and services, like a physics service. To use, simply subclass Entity, and overwrite at least one of the four update-phase methods or the on_event method. Then, when the entity is created, it will automatically have those methods called each frame.
class MyEntity(Entity):
def __init__(self, container=None, enabled=True):
super().__init__(container, enabled)
self.position: tuple[int, int] = (0, 0)
def update(self, delta_time: float):
keys = pygame.key.get_pressed()
x = y = 0
if keys[pygame.K_w]:
y -= 1
if keys[pygame.K_s]:
y += 1
if keys[pygame.K_a]:
x -= 1
if keys[pygame.K_d]:
x += 1
self.move((x, y))
def move(self, direction: tuple[int, int]):
self.position = (
self.position[0] + direction[0], self.position[1] + direction[1]
)This will create a simple entity that will move with the WASD keys. Note, however, that it does not show anything on screen, as it is not renderable.
Renderables are anything that needs to be drawn to the screen. They must implement the render method, which must return a ready-to-draw surface, and the get_rect method, which returns a pygame Rectangle, with the position and size of the renderable. Classes can inherit from both Entity and Renderable, to allow them to both be drawn and have behavior.
class MyRenderable(Renderable):
# __init__ here
def get_rect(self) -> pygame.Rect:
return pygame.Rect(100, 50, 10, 10)
def render(self, delta_time: float):
surface = Surface((10, 10))
surface.fill(Color("fuchsia"))
return surfaceThis will draw a small fuchsia square at a world position of 100, 50.
There's a special layer in the the render system, the UI layer. Renderables in the UI layer are always drawn in screen space, not world space.
In base pygame, all surfaces are rendered in terms of screen space. This means that changing the resolution changes the size of the display, but not the objects on it. This means either a complicated setup that accounts for the window size before figuring out where to draw everything, or locking down the resolution, never to be changed.
Pyrite features a camera system as part of its default renderer. Cameras are moveable and zoomable, and automatically ignore any renderables they can't see, speeding up your game when items are offscreen.
You can even have multiple cameras, rendered to different parts of the screen!*
Renderables have layers and draw indexes to ensure that everything is drawn in the desired order. You can even add additional layers, and have cameras ignore layers, as needed.
Cameras are, or course, optional. Pyrite can treat your world space just like screen space if you don't want/need cameras for your project.
*Currently, multiple cameras slows the game greatly.
- (Eternal) Improve the renderer. Faster rendering means more renderables!
See the open issues for a full list of proposed features (and known issues).
Distributed under the MIT License. See LICENSE.txt for more information.
Better Built Fool - [email protected]
Bluesky - @betterbuiltfool.bsky.social
Project Link: https://github.com/BetterBuiltFool/pyrite_framework