PyGame-S — PyGame Simplified

Current version: 2.4.4

PyGame-S is a beginner-friendly wrapper around Pygame that simplifies game development without limiting what you can build. Write less boilerplate, focus more on your game.

Installation

pip install pygames-simplified

Importing

from pygames.advanced import Player, Animator, PhysicSprite, Game  # Physics + Player + Animator (recommended)
from pygames.medium import PhysicSprite, Game                       # Physics only (no player input)

Quick Start

from pygames.advanced import Player, Game
from pygames.pygames_engine.pygames import LAYER_BACKGROUND, LAYER_PLAYER
from pygames.pygames_engine.utils.object_manager import SSprites
import pygame

game = Game(800, 600, "My Game")

player = Player(game, 100, 300)
ground = SSprites(game, 0, 550, source=pygame.Surface((800, 50)))
ground.image.fill("green")

game.start(player, layer=LAYER_PLAYER)
game.make_solid(ground, layer=LAYER_BACKGROUND)

def logic():
    game.background("skyblue")
    # No need to call player.tick() — the group handles it automatically

game.mainloop(logic)

Complexity Tiers

Core — Game

game = Game(w=800, h=600, title="My Game", icon_path=None)

Note: game.zoom(factor) is discouraged when PhysicSprites are in use — it resizes the window but does not rescale object positions or physics constants.

Note: game.start_garbage_collecter() (old spelling) still works as an alias but is deprecated — prefer start_garbage_collector().

Draw Layers

Sprites are drawn back-to-front by layer number. Lower numbers appear behind higher numbers. Four named constants are provided for convenience:

from pygames.pygames_engine.pygames import LAYER_BACKGROUND, LAYER_DEFAULT, LAYER_PLAYER, LAYER_UI

# LAYER_BACKGROUND = 0  — tiles, sky, scenery
# LAYER_DEFAULT    = 1  — general objects, platforms, enemies
# LAYER_PLAYER     = 2  — the player character
# LAYER_UI         = 3  — score displays, health bars, overlays

You can use any integer — these constants are just a sensible starting point.

game.start(sky, layer=LAYER_BACKGROUND)
game.start(platform, layer=LAYER_DEFAULT)
game.start(player, layer=LAYER_PLAYER)
game.start(health_bar, layer=LAYER_UI)

# Move a sprite to a different layer at runtime
game.set_layer(enemy, LAYER_PLAYER)

# Find out what layer a sprite is on
print(game.get_layer(player))   # 2

# Get all sprites on a specific layer
ui_sprites = game.get_sprites_in_layer(LAYER_UI)

Base Sprite — SSprites

obj = SSprites(game, x, y, image_path=None, source=None)

The base class for all game objects. Accepts an image path, a raw Surface, or defaults to a white square.

Physics — PhysicSprite

obj = PhysicSprite(game, x, y, width=50, height=50, color="red")

Extends SSprites with gravity, velocity, and collision detection.

Vertical and horizontal collisions are resolved in separate passes, which prevents corner-clipping on platform edges.

Player — Player

player = Player(game, x, y, width=40, height=60, color="blue", speed=5,
                left="left", right="right", jump="space")

Extends PhysicSprite with keyboard input. All key bindings are customisable.

When registered with game.start(), the player's input and physics are handled automatically — you no longer need to call player.tick() in your logic function.

Animation — Animator

from pygames.advanced import Animator

anim = Animator(target, animation_speed=100)

Works with sprites that have a .state string and an .animations dict mapping state names to lists of Surface frames.

animation_speed is in milliseconds — 100 means frames advance every 100 ms (~10 fps).

Note: hover() modifies rect.y directly. Do not use it on sprites that also have apply_physics running — the two will conflict.

Removing Sprites

# Remove a sprite from the game entirely
enemy.remove_from_game()   # removes from objects, solids, and any other group

# Or use pygame's built-in directly
enemy.kill()

---

## Example Games

The package includes runnable demos in `pygames/examples/`.

- `pygames/examples/aliens.py` — Alien Invasion demo with shooting, bombs, score, and a clean game-ending sequence.
- `pygames/examples/platformer.py` — Simple platformer demo showing player movement, jumping, and collision with a ground platform.

Run them directly from the repo root:
```bash
python pygames/examples/aliens.py
python pygames/examples/platformer.py

---

## Supported Keys

Pass any of these strings to `game.check_key_pressed()` or as custom key bindings on `Player`:

`"left"`, `"right"`, `"up"`, `"down"`, `"space"`, `"esc"`, `"enter"`, `"shift"`, `"ctrl"`, `"tab"`, `"backspace"`, or any letter/number like `"a"`, `"w"`, `"1"`

---

## Error Handling

| Error | Cause |
|---|---|
| `FileNotFoundError` | Invalid path for image, sound, or icon |
| `TypeError` | Wrong type for width, height, speed, coordinates, or jump force |
| `ValueError` | Negative speed value |
| `NameError` | Invalid colour name or missing sound name |

---

## Logging

Pass `logging=True` to `Game()` or call `game.enable_logging()` at any time. A `logs.txt` file is created in the same directory as your main script. The path is printed to the terminal when the file is first created. Pass a custom path to `enable_logging(log_path)` to write the log elsewhere.

---

## Version

Current release: **v2.4.3**

Inspired by [Pygame Zero](https://pygame-zero.readthedocs.io/), built to be more Pythonic, flexible, and extensible.

## Links

- GitHub: https://github.com/manupolice12-sketch/pygames
- Bug Reports: https://github.com/manupolice12-sketch/pygames/issues
- PyPI: https://pypi.org/project/pygames-simplified/