gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/pygame-core
pygame-core
VerifiedBuilds 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`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| references/sprites-and-collision.md | markdown | 4.5 KB |
references/sprites-and-collision.md
View on GitHub# pygame sprites, collision & media (pygame-ce 2.5+)
Depth behind the pygame-core skill: group variants, pixel-perfect collision,
spritesheets, animation, and audio/text.
## Contents
- [Group variants](#group-variants): `GroupSingle`, `LayeredUpdates`, `RenderUpdates`
- [Collision functions](#collision-functions): rect, circle, ratio and "any" tests
- [Pixel-perfect collision with masks](#pixel-perfect-collision-with-masks)
- [Slicing a spritesheet](#slicing-a-spritesheet) and
[simple frame animation](#simple-frame-animation)
- [Audio](#audio) and [text](#text)
## Group variants
`pygame.sprite` ships several containers; pick by need:
| Class | Use for |
|-------|---------|
| `Group` | the general case; `update(*args)` + `draw(surface)` |
| `GroupSingle` | a slot holding at most one sprite (e.g. the player) |
| `LayeredUpdates` | groups that draw by a per-sprite `_layer` (z-order) |
| `RenderUpdates` | tracks dirty rects for partial-screen redraws |
```python
from pygame.sprite import LayeredUpdates
world = LayeredUpdates()
world.add(background, layer=0)
world.add(player, layer=10) # higher layer draws on top
world.add(ui, layer=20)
world.update(dt)
world.draw(screen)
```
A sprite removes itself from **all** groups with `self.kill()`. Membership is
two-way: `group.has(sprite)`, `sprite.groups()`.
## Collision functions
`spritecollide` and `groupcollide` use rect overlap by default. The optional
`collided` callback swaps in a more precise test:
```python
import pygame
from pygame.sprite import collide_rect, collide_circle, collide_mask
# Circle collision (set sprite.radius, or it's derived from the rect):
pygame.sprite.spritecollide(player, rocks, False, collide_circle)
# Pixel-perfect via masks (see below):
pygame.sprite.spritecollide(player, spikes, False, collide_mask)
```
Other helpers: `pygame.sprite.collide_rect_ratio(0.75)` (shrunken rect),
`spritecollideany` (fast boolean-ish "any hit"), and `Rect` methods
`colliderect`, `collidepoint`, `collidelist`, `collidelistall`.
## Pixel-perfect collision with masks
Rect collision is generous; for tight hitboxes build a `Mask` from each sprite's
alpha and test overlap:
```python
class Bullet(pygame.sprite.Sprite):
def __init__(self, image, pos):
super().__init__()
self.image = image.convert_alpha()
self.rect = self.image.get_rect(center=pos)
self.mask = pygame.mask.from_surface(self.image) # build once
# collide_mask uses each sprite's .mask:
if pygame.sprite.collide_mask(bullet, enemy):
enemy.kill()
```
Rebuild the mask if the sprite's image changes (e.g. each animation frame), or
keep a per-frame list of masks.
## Slicing a spritesheet
```python
def load_frames(path, frame_w, frame_h):
sheet = pygame.image.load(path).convert_alpha()
cols = sheet.get_width() // frame_w
rows = sheet.get_height() // frame_h
frames = []
for r in range(rows):
for c in range(cols):
rect = pygame.Rect(c * frame_w, r * frame_h, frame_w, frame_h)
frames.append(sheet.subsurface(rect)) # view into the sheet, no copy
return frames
```
## Simple frame animation
```python
class AnimatedSprite(pygame.sprite.Sprite):
def __init__(self, frames, fps, pos):
super().__init__()
self.frames = frames
self.frame_time = 1 / fps
self.timer = 0.0
self.index = 0
self.image = frames[0]
self.rect = self.image.get_rect(center=pos)
def update(self, dt):
self.timer += dt
while self.timer >= self.frame_time:
self.timer -= self.frame_time
self.index = (self.index + 1) % len(self.frames)
self.image = self.frames[self.index]
```
## Audio
```python
pygame.mixer.init() # or rely on pygame.init()
jump_sfx = pygame.mixer.Sound("jump.wav") # short SFX, fully loaded
jump_sfx.set_volume(0.5)
jump_sfx.play()
pygame.mixer.music.load("theme.ogg") # streamed music (one track at a time)
pygame.mixer.music.set_volume(0.3)
pygame.mixer.music.play(loops=-1) # -1 = loop forever
```
Prefer `.ogg`/`.wav`; keep many short effects as `Sound`, and long tracks on the
single `music` stream.
## Text
```python
font = pygame.font.Font(None, 36) # None = default font; or a .ttf path
# Antialiased text is slow to render — cache the Surface, re-render only on change.
label = font.render(f"Score: {score}", True, (255, 255, 255))
screen.blit(label, (10, 10))
```
Re-rendering text every frame is a common performance trap; render once and re-blit,
re-rendering only when the string changes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |