pygame-core Checked

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.
- **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.