Index of every page on this site: llms.txt
All skills
Run it yourself

Builds and debugs 2D games in Python with pygame-ce (imported as pygame): the event-update-draw loop, delta time, Surfaces and Rects, Sprite groups and headless tests. Use when code imports pygame, or a window says not responding, speed differs per PC or pygame and pygame-ce conflict. Not for engine-neutral input or saves (`input-systems`, `save-systems`) or jump feel (`platformer`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/pygame-core

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈100 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈1.2k more on demand in 1 file.

Description uses 5.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈400 characters, or 5.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

pygame Core

Build and debug a pygame game. New code targets pygame-ce 2.5.8, the maintained community fork; it installs as pygame-ce and imports as pygame. Legacy pygame 2.6 code mostly runs unchanged; pygame-ce-only APIs such as FRect and get_frect() need the fork, which getattr(pygame, "IS_CE", False) detects.

When to use

  • Starting a pygame game, or fixing its loop, speed, input, drawing, sprite groups, collision, audio or text.
  • Any project with import pygame, whichever package provides it.

When not to use: Python questions unrelated to pygame; 3D; portable design work owned by the related skills below.

Workflow

  1. Check the install. python -c "import pygame; print(pygame.version.ver, getattr(pygame, 'IS_CE', False))". Keep the project's package; for a new project use pip install pygame-ce.
  2. Keep logic testable. Put rules in classes or functions that take dt and an input snapshot, so a test can drive them without a window. Only the loop touches the display.
  3. One loop per frame: drain events, update with a clamped dt, draw, flip(). Use pixels per second, and float positions (FRect or Vector2).
  4. Load assets after set_mode, then convert() / convert_alpha() once each.
  5. Verify headless. Run the tests and a short scripted run with the dummy drivers (see the check below), then open the saved PNG. Report what ran. Feel, audio and real input still need a person: ask the user to play for a minute and report speed, controls and sound.

Pattern: a loop that can run headless

import argparse
import pygame

def main(argv=None):
    ap = argparse.ArgumentParser()
    ap.add_argument("--frames", type=int, default=0, help="quit after N frames (0 = run)")
    ap.add_argument("--shot", help="save the last frame to this PNG")
    args = ap.parse_args(argv)

    pygame.init()
    screen = pygame.display.set_mode((320, 180), pygame.SCALED)  # before any convert()
    clock = pygame.time.Clock()
    sprites = pygame.sprite.Group(Player((160, 90)))

    frame, running = 0, True
    while running:
        dt = min(clock.tick(60) / 1000, 0.05)          # clamp stalls (window drag, debugger)
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False
        sprites.update(dt, pygame.key.get_pressed())
        screen.fill((18, 18, 28))
        sprites.draw(screen)
        pygame.display.flip()
        frame += 1
        if args.frames and frame >= args.frames:
            if args.shot:
                pygame.image.save(screen, args.shot)
            running = False
    pygame.quit()
class Player(pygame.sprite.Sprite):
    def __init__(self, pos):
        super().__init__()
        self.image = pygame.image.load("player.png").convert_alpha()
        self.rect = self.image.get_frect(center=pos)   # FRect keeps sub-pixel positions
        self.speed = 120                               # pixels per second

    def update(self, dt, keys):
        move = pygame.Vector2(keys[pygame.K_RIGHT] - keys[pygame.K_LEFT],
                              keys[pygame.K_DOWN] - keys[pygame.K_UP])
        if move.length_squared():                      # zero vectors cannot be scaled
            move.scale_to_length(self.speed * dt)      # same speed on diagonals
        self.rect.center += move

Use KEYDOWN / MOUSEBUTTONDOWN events for one-off actions (jump, pause, click) and key.get_pressed() for held movement. pygame.SCALED draws a small logical screen into a larger window (handy for pixel art) and scales mouse events back to logical coordinates; the docs still call it experimental.

The check to run

SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy python -m unittest -v
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy python main.py --frames 120 --shot frame.png

A unit test sets the same variables before import pygame, calls pygame.init() and pygame.display.set_mode((1, 1)) in setUp (so convert_alpha() works), feeds a fake key snapshot and asserts on positions after a fixed number of update(1 / 60, keys) calls. The PNG has the logical size (320×180 here), not the scaled window size. The dummy run proves that the loop, loading and drawing work; it cannot show frame pacing or how input feels.

Gotchas

  • Window freezes or shows "not responding" → the event queue is not drained every frame. Call pygame.event.get() (or pygame.event.pump()) once per frame, including in menus and loading screens.
  • Game runs faster on a faster machine → movement per frame instead of per second. Scale by dt from clock.tick().
  • Objects jump or pass through walls after a window drag or a breakpoint → the next clock.tick() returns the whole stall. Clamp it: min(clock.tick(60) / 1000, 0.05).
  • Slow movement gets stuck or jitters → Rect stores integers and truncates each update (rect.x += 0.5 never moves). Use get_frect() / FRect (pygame-ce; groups and collision accept it) or keep a Vector2 position and assign rect.center from it.
  • ValueError: Can't normalize Vector of length zero (or Cannot scale a vector with zero length) → normalize() / scale_to_length() ran with no keys held. Check length_squared() first.
  • pygame.error: No convert format has been set → convert() / convert_alpha() ran before display.set_mode(). Load images after opening the window.
  • Blits are slow → images were never converted. Convert each one once at load.
  • pygame.error: mixer not initialized on a server, in CI or on a machine without sound → pygame.init() does not raise when a module fails; it returns (passed, failed) and leaves the mixer off. Set SDL_AUDIODRIVER=dummy for headless runs, or check pygame.mixer.get_init() and skip audio.
  • Text rendering eats the frame budget → font.render every frame. Cache the surface and re-render only when the string changes.
  • import pygame gives the wrong version, or module 'pygame' has no attribute 'version' → pygame and pygame-ce were both installed into one environment: they share the pygame folder, the last install wins, and removing either breaks the other. Run pip uninstall -y pygame pygame-ce, then pip install pygame-ce.
  • Nothing appears → no display.flip(), or screen.fill() runs after the drawing. Draw back to front: background, world, sprites, HUD.

References

  • Read references/sprites-and-collision.md when the game needs more than one Group: GroupSingle and LayeredUpdates z-order, circle and mask (pixel-perfect) collision, spritesheet slicing, frame animation, sound effects and music, and cached text.

Related skills

  • input-systems, save-systems — engine-neutral rebinding and persistence.
  • platformer, roguelike — genre rules that bind to this loop.
  • love2d-core — the same loop in LÖVE; bevy-ecs — when a project outgrows pygame.

Version notes

Last verified: 2026-11-11.

  • pygame-ce 2.5.8 (released 2026-08-09) is the latest release; it needs Python 3.10+ and ships wheels for CPython 3.10 to 3.15 and PyPy 3.11. It bundles SDL 2.32.10.
  • Legacy pygame's latest release is 2.6.1 (2024-09-29).
  • The loop, sprite, test and headless commands above, the error texts in Gotchas and the pygame/pygame-ce install clash were run with pygame-ce 2.5.8 on Python 3.12 and the SDL dummy drivers.
  • Sources: pygame-ce on PyPI, pygame-ce releases, pygame-ce docs, pygame on PyPI.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The skill provides instructional patterns for game development using the pygame-ce library, including best practices for game loops, asset loading, and headless testing. No security risks or malicious patterns were detected.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/pygame-core