PyGame Mentor-AI-powered guidance for PyGame development.

Example

Deliver a modular skeleton tailored to your game. Provide a package layout, base Scene class, event bus, and a thin App. Example base classes: """ class Scene: def __init__(self, services): self.services = services def handle_event(self, e): pass def update(self, dt): pass def draw(self, surf): pass class Services: # simple DI container def __init__(self, **deps): self.__dict__.update(deps) # Lightweight event bus class EventBus: def __init__(self): self._subs = {} def subscribe(self, topic, fn): self._subs.setdefault(topic, []).append(fn) def emit(self, topic, *a, **kw): for fn in self._subs.get(topic, []): fn(*a, **kw) """ This gives you replaceable scenes, injectable dependencies (assets, audio, save system), and decoupled subsystems via an event bus.

Scenario

Your prototype has global state and scattered asset loads. You ask for a refactor plan. I produce a step-by-step migration: (1) move assets into a loader service; (2) split scenes into menu/gameplay; (3) introduce an event bus for cross-cutting concerns (pause, music); (4) enforce a single update/draw loop contract. Result: adding a PauseScene or SettingsScene becomes trivial.

Example

Apply practical patterns with compact code. For enemy AI or game flow, a tiny FSM keeps logic readable: """ from enum import Enum, auto class State(Enum): IDLE=auto(); CHASE=auto(); ATTACK=auto() class Enemy: def __init__(self): self.state=State.IDLE; self.timer=0 def update(self, dt, player_dist): if self.state is State.IDLE and player_dist<200: self.state=State.CHASE elif self.state is State.CHASE and player_dist<40: self.state=State.ATTACK elif self.state is State.ATTACK and player_dist>60: self.state=State.CHASE # do per-state behavior here """ For many entities (bullets/particles), a minimal ECS improves throughput and clarity: """ class World: def __init__(self): self.pos={}, self.vel={} def spawn(self, eid,p,v): self.pos[eid]=p; self.vel[eid]=v def sys_move(self, dt): for e in self.pos.keys() & self.vel.keys(): x,y=self.pos[e]; vx,vy=self.vel[e]; self.pos[e]=(x+vx*dt,y+vy*dt) """ Input mapping stays decoupled from actions: """ KEYMAP={ 'shoot': [pygame.K_SPACE, pygame.BUTTON_LEFT] } """

Scenario

You want dash + stamina + combo attacks. I design an input map, a PlayerFSM with states (IDLE, RUN, DASH, ATTACK), and stamina as a component used by multiple systems. I show how to wire UI hints via an event ("stamina_changed") so the HUD updates without calling gameplay code directly. Net result: adding a new action (e.g., heavy attack) is just a new state + mapping, no rewiring across the app.

Example

Eliminate stutter and ship stable builds. I apply a frame pacing template and draw/update budgets: """ # Fixed update, variable render acc=0.0; FIXED=1/120 while running: dt = clock.tick(240)/1000.0 acc += dt for e in pygame.event.get(): handle(e) while acc >= FIXED: update(FIXED); acc -= FIXED draw(screen); pygame.display.flip() """ Speedups: convert assets once (Surface.convert/convert_alpha), pre-blit static layers to cached surfaces, batch draws with pygame.sprite.LayeredUpdates, and use spatial hashing for collisions. Quick profiling: """ import cProfile, pstats; cProfile.run('run()', 'prof') print(pstats.Stats('prof').sort_stats('tottime').print_stats(20)) """ Packaging example (Windows): """ pyinstaller -F -n MyGame --add-data "assets;assets" src/game/app.py """ Add smoke tests for deterministic systems (physics, save/load) and a CI step to build artifacts.

Scenario

Your game runs at 60 FPS locally but drops on laptops. I profile and find alpha-blitting 200 sprites per frame. We switch most to pre-composited layers, convert surfaces after load, and reduce per-frame allocations. Then we adopt fixed updates (120 Hz) with decoupled rendering (up to GPU/monitor), cutting stutter while keeping input responsive. Finally, we add a reproducible PyInstaller build and a checklist for assets, saves, and versioning.