pygame-core

pygame Core

Python で pygame ゲームの基盤を構築します。メインループ、デルタタイムによる移動、Surface／Rect を使った描画、入力、Sprite／Group の管理を扱います。 対象は pygame-ce 2.5.8 です（現在も活発にメンテナンスされているコミュニティ版フォーク。同じく import pygame を使用します）。

使用する場面

• pygame ゲームの開始、ループの修正、フレームレートに依存する速度、入力処理、ブリット、スプライト／グループの衝突を扱う場合に使用します。
• コードで import pygame を行い、プロジェクトが pygame-ce（または pygame）に依存している場合に使用します。

使用しない場面： pygame に関係のない Python 言語の質問。3D レンダリング（pygame は 2D です）。エンジンを問わないセーブ／ロードには save-systems を、再バインド可能な入力アーキテクチャには input-systems を参照してください。

基本的なワークフロー

1. レガシー版の pygame ではなく pygame-ce をインストールします。 pip install pygame-ce — メンテナンスされているフォークで、インポート名は pygame です。同じ環境に両方をインストールしないでください。
2. 初期化してウィンドウを開きます。 pygame.init()、screen = pygame.display.set_mode((w, h))、clock = pygame.time.Clock() を実行します。
3. 1 つのループを実行します：イベント → 更新 → 描画 → 反転。 毎フレーム、イベントキューを処理し（for event in pygame.event.get()）、状態を更新して再描画し、最後に pygame.display.flip() を呼び出します。
4. フレームレートに依存しない動作にします。 dt = clock.tick(60) / 1000（秒）を取得し、すべての動きに dt を掛けます。位置は浮動小数点数で保持し、整数の矩形にブリットします。
5. 入力は 2 つの方法で処理します： イベント方式（離散的なアクションには KEYDOWN／MOUSEBUTTONDOWN）とポーリング方式（押し続ける移動には pygame.key.get_pressed()）です。
6. Sprite と Group でオブジェクトを整理します。 image／rect を持つ pygame.sprite.Sprite のサブクラスを作成します。group.update(dt) と group.draw(screen) で一括処理できます。動作すると決めつける前に、実行してウィンドウを確認してください。

パターン

1. 最小限のゲームループ（骨組み）

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. デルタタイムによる移動（フレームレートに依存しない動作）

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. 入力：イベント方式とポーリング方式

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. Sprite サブクラスと 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. 衝突検出

# 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()

注意点

• ウィンドウがフリーズする／「応答なし」になる → イベントキューを処理していません。毎フレーム pygame.event.get()（または pygame.event.pump()）を呼び出してください。
• マシンによって速度が異なる → フレームごとに固定量を移動させています。dt = clock.tick(fps) / 1000 を使ってスケーリングし、1 秒あたりのピクセル数で値を指定してください。
• サブピクセル移動がカクつく／跳ねる → rect 座標は整数です。実際の位置は浮動小数点数の Vector2 として保持し、毎フレーム rect.center = round(...) を設定してください。
• ブリットが遅い／フレームレートが低下する → 読み込んだ画像に対し、一度だけ .convert()（不透明）または .convert_alpha()（透明）を呼び出してください。変換されていないサーフェスはブリットが大幅に遅くなります。
• 何も表示されない → pygame.display.flip()（または update()）を忘れているか、screen.fill(...) の前に描画したため消去されています。
• 描画順が間違っている → pygame はペインター方式を使います。後からブリットしたものが先のものを覆います。背景を先に、スプライトを最後に描画してください。
• pip install pygame で古いものがインストールされた → メンテナンスされているフォークには pip install pygame-ce を使ってください。両方がインストールされているとインポート時に競合します。
• 斜め移動が速くなる → 速度を掛ける前に方向ベクトルを正規化してください。

参考資料

• Group の各種バリエーション（Z オーダー用の GroupSingle、LayeredUpdates）、mask を使ったピクセル単位の衝突判定、スプライトシートの分割、簡単なアニメーション、サウンド／音楽、テキスト描画については、references/sprites-and-collision.md を参照してください。

関連スキル

• love2d-core — LÖVE／Lua での同様のループ概念です。
• bevy-ecs — プロジェクトが pygame の範囲を超えた場合に使える、より大規模な ECS エンジンです。
• input-systems／save-systems — エンジンに依存しない入力と永続化です。
• platformer／roguelike — pygame と組み合わせられるジャンル別テンプレートです。