pygame-core

Q: How do I install pygame-core?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill pygame-core in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/pygame-core/ (personal) or .claude/skills/pygame-core/ (project).

by gamedev-skillsMedia & Creative

Structure a pygame (pygame-ce) game in Python: the init/event/update/draw loop, delta-time movement, Surface/Rect blitting, keyboard/mouse input, and Sprite/Group management with collision. Use when building or debugging a pygame game — when the user mentions pygame, pygame-ce, the game loop, blit, Surface, Rect, sprite groups, or clock.tick. Targets pygame-ce.

Installs: 5.4K
Last 24h: +293
Trending rank: #983
Security: Pass

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill pygame-core

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads pygame-core automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·The skill provides standard instructional patterns for using the pygame-ce library (a community-maintained fork of Pygame) in Python. No security risks were identified.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

SKILL.md

The instructions your agent reads when the skill is triggered.

pygame Core

Build the foundation of a pygame game in Python: the main loop, delta-time movement, drawing with Surface/Rect, input, and Sprite/Group management. Targets pygame-ce 2.5.8 (the actively maintained community fork; same import pygame), which supports Python 3.10–3.15.

When to use

Use when starting a pygame game, fixing the loop, frame-rate-dependent speed, input handling, blitting, or sprite/group collision.
Use when code does import pygame and the project depends on pygame-ce (or pygame).

When not to use: Python language questions unrelated to pygame. 3D rendering (pygame is 2D). For cross-engine save/load use save-systems; for rebindable input architecture see input-systems.

Core workflow

Install pygame-ce, not legacy pygame. pip install pygame-ce — it's the maintained fork and imports as pygame. Don't install both in one environment.
Init and open a window. pygame.init(), screen = pygame.display.set_mode((w, h)), clock = pygame.time.Clock().
Run one loop: events → update → draw → flip. Pump the event queue every frame (for event in pygame.event.get()), update state, redraw, then pygame.display.flip().
Make it frame-rate independent. Get dt = clock.tick(60) / 1000 (seconds) and scale all motion by dt. Keep positions as floats; blit at integer rects.
Handle input two ways: event-based (KEYDOWN/MOUSEBUTTONDOWN, for discrete actions) and polled (pygame.key.get_pressed(), for held movement).
Organise objects with Sprite + Group. Subclass pygame.sprite.Sprite with image/rect; group.update(dt) and group.draw(screen) handle the batch. Run it and watch the window before assuming it works.

Patterns

1. Minimal game loop (the skeleton)

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
pygame.display.set_caption("My Game")
clock = pygame.time.Clock()

running = True
while running:
    dt = clock.tick(60) / 1000          # cap at 60 FPS; dt = seconds since last frame
    for event in pygame.event.get():    # MUST drain the queue or the OS thinks it hung
        if event.type == pygame.QUIT:
            running = False

    # update game state here, scaled by dt ...

    screen.fill((18, 18, 28))           # clear each frame
    # draw everything here ...
    pygame.display.flip()               # present the frame

pygame.quit()

2. Delta-time movement (frame-rate independent)

from pygame.math import Vector2

pos = Vector2(100, 100)        # keep position as floats
speed = 220                    # PIXELS PER SECOND, not per frame

# inside the loop, after computing dt:
keys = pygame.key.get_pressed()
direction = Vector2(
    keys[pygame.K_RIGHT] - keys[pygame.K_LEFT],
    keys[pygame.K_DOWN]  - keys[pygame.K_UP],
)
if direction.length_squared() > 0:
    direction = direction.normalize()      # equal speed on diagonals
pos += direction * speed * dt              # RIGHT: dt-scaled
screen.blit(player_img, (round(pos.x), round(pos.y)))  # blit at integer pixels

3. Input: events vs polling

for event in pygame.event.get():
    if event.type == pygame.QUIT:
        running = False
    elif event.type == pygame.KEYDOWN:        # discrete press: jump, menu, pause
        if event.key == pygame.K_SPACE:
            jump()
        elif event.key == pygame.K_ESCAPE:
            running = False
    elif event.type == pygame.MOUSEBUTTONDOWN:
        shoot_at(event.pos)                   # event.pos = (x, y)

# Polled state (read once per frame) for continuous/held input:
keys = pygame.key.get_pressed()
if keys[pygame.K_a]:
    move_left(dt)

4. A Sprite subclass + a Group

class Player(pygame.sprite.Sprite):
    def __init__(self, x, y):
        super().__init__()
        # convert() once at load makes blits much faster; _alpha keeps transparency.
        self.image = pygame.image.load("player.png").convert_alpha()
        self.rect = self.image.get_rect(center=(x, y))
        self.pos = pygame.math.Vector2(self.rect.center)
        self.speed = 240

    def update(self, dt):                      # Group.update(dt) calls this per sprite
        keys = pygame.key.get_pressed()
        self.pos.x += (keys[pygame.K_RIGHT] - keys[pygame.K_LEFT]) * self.speed * dt
        self.rect.center = (round(self.pos.x), round(self.pos.y))

all_sprites = pygame.sprite.Group()
all_sprites.add(Player(400, 300))

# in the loop:
all_sprites.update(dt)        # calls each sprite's update(dt)
all_sprites.draw(screen)      # blits each sprite at its rect

5. Collision detection

# Sprite vs group: e.g. player picking up coins (True = remove collided coins).
collected = pygame.sprite.spritecollide(player, coins, dokill=True)
score += len(collected)

# Group vs group: bullets vs enemies (kill both on hit).
hits = pygame.sprite.groupcollide(bullets, enemies, True, True)

# Plain rect overlap (no sprites needed):
if player.rect.colliderect(door_rect):
    open_door()

Pitfalls

Window freezes / "not responding" → you didn't pump the event queue. Call pygame.event.get() (or pygame.event.pump()) every frame.
Speed differs on faster machines → you moved by a fixed amount per frame. Scale by dt = clock.tick(fps) / 1000 and use pixels-per-second values.
Sub-pixel movement snaps/jitters → rect coordinates are integers; store the true position as a Vector2 of floats and assign rect.center = round(...) each frame. In pygame-ce you can instead use a float rect: image.get_frect(...) returns a pygame.FRect, which sprite groups and collision functions accept like a Rect.
Objects jump or tunnel through walls after the window was dragged or the game paused in a debugger → the next clock.tick() returns the whole stall as one huge dt. Clamp it before use, e.g. dt = min(clock.tick(60) / 1000, 0.05).
ValueError: Can't normalize Vector of length zero → Vector2.normalize() was called with no keys held. Check length_squared() > 0 first, as in Pattern 2.
Blits are slow / framerate drops → call .convert() (opaque) or .convert_alpha() (transparent) on loaded images once; un-converted surfaces blit far slower.
Nothing appears → you forgot pygame.display.flip() (or update()), or you drew before screen.fill(...) so it was cleared away.
Wrong draw order → pygame uses painter's order; later blits cover earlier ones. Draw background first, sprites last.
pip install pygame got the old one → for the maintained fork use pip install pygame-ce; having both installed causes import conflicts.
Diagonal movement is faster → normalise the direction vector before scaling by speed.

References

For Group variants (GroupSingle, LayeredUpdates for z-order), pixel-perfect collision with mask, slicing a spritesheet, simple animation, sound/music, and text rendering, read references/sprites-and-collision.md.

Related skills

love2d-core — the same loop concepts in LÖVE/Lua.
bevy-ecs — a heavier ECS engine when a project outgrows pygame.
input-systems / save-systems — engine-agnostic input and persistence.
platformer / roguelike — genre templates that pair with pygame.

FAQ

What does the pygame-core skill do?

How do I install pygame-core?

Run npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill pygame-core in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/pygame-core/ (personal) or .claude/skills/pygame-core/ (project).

Which AI agents can use pygame-core?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is pygame-core safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains pygame-core?

It is published by gamedev-skills in gamedev-skills/awesome-gamedev-agent-skills. It has 5,388 recorded installs.