pygame

Pygame Best Practices

This guide outlines the essential patterns for building robust and visually appealing Pygame applications, leveraging pygame-gui for all UI interactions. Adhere to these principles for maintainable, performant, and scalable game development.

1. Core Application Structure

Always structure your Pygame application with a clear main loop, a single UIManager, and a fixed timestep. Separate game logic from UI logic.

❌ BAD: Scattered UI element creation, no UIManager, variable framerate.

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
pygame.display.set_caption("Bad Example")

running = True
while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        # UI logic directly in main loop
        if event.type == pygame.MOUSEBUTTONDOWN:
            print("Mouse clicked!")

    screen.fill((0, 0, 0))
    # Draw game elements
    pygame.draw.rect(screen, (255, 0, 0), (100, 100, 50, 50))
    pygame.display.flip()

✅ GOOD: Dedicated UIManager, fixed timestep, clear event processing.

import pygame
import pygame_gui
from pygame_gui.core.interfaces import IUIManagerInterface

class Game:
    def __init__(self, screen_size: tuple[int, int]):
        pygame.init()
        self.screen = pygame.display.set_mode(screen_size)
        pygame.display.set_caption("Good Example")
        self.manager: IUIManagerInterface = pygame_gui.UIManager(screen_size, 'data/themes/default.json')
        self.clock = pygame.time.Clock()
        self.is_running = True
        self.fps = 60

        # Example UI button
        pygame_gui.elements.UIButton(
            relative_rect=pygame.Rect((350, 275), (100, 50)),
            text='Click Me',
            manager=self.manager
        )

    def run(self):
        while self.is_running:
            time_delta = self.clock.tick(self.fps) / 1000.0
            self._handle_events()
            self._update(time_delta)
            self._draw()
        pygame.quit()

    def _handle_events(self):
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                self.is_running = False
            if event.type == pygame_gui.UI_BUTTON_PRESSED:
                print("Button pressed!")
            self.manager.process_events(event)

    def _update(self, time_delta: float):
        self.manager.update(time_delta)
        # Update game logic here

    def _draw(self):
        self.screen.fill((0, 0, 0))
        # Draw game elements
        pygame.draw.rect(self.screen, (255, 0, 0), (100, 100, 50, 50))
        self.manager.draw_ui(self.screen)
        pygame.display.flip()

if __name__ == '__main__':
    game = Game((800, 600))
    game.run()