easy2d 0.4.2

A practical 2D game framework for Python with scenes, camera, particles, multiplayer networking, CLI host/join tools, and chunked tilemaps

Easy2D

Easy2D is a practical 2D game framework on top of pygame with a clean scene loop, camera system, multiplayer networking helpers, CLI tooling, and performant tilemap rendering for larger worlds.

Why Easy2D

• Fast setup for playable prototypes in minutes
• Scene and object lifecycle that stays organized as projects grow
• Delta-time movement and simple input helpers out of the box
• Built-in multiplayer host/client utilities and quick network setup command
• Chunk-cached tilemap rendering for smoother large maps
• Simple API that can scale from arcade games to block-world builders

Install

pip install easy2d

Quick Start

import pygame
import easy2d as e

class Player(e.Rect):
    def __init__(self):
        super().__init__(100, 100, 28, 28, color=(80, 220, 180), gravity=0.0, floor_y=None)
        self.speed = 240

    def update(self, game):
        dx = dy = 0.0
        if game.key_pressed(pygame.K_a):
            dx -= self.speed * game.delta_time
        if game.key_pressed(pygame.K_d):
            dx += self.speed * game.delta_time
        if game.key_pressed(pygame.K_w):
            dy -= self.speed * game.delta_time
        if game.key_pressed(pygame.K_s):
            dy += self.speed * game.delta_time
        self.move(dx, dy)

class MainScene(e.Scene):
    def __init__(self):
        super().__init__()
        self.player = self.add(Player())

    def update(self, game):
        super().update(game)
        game.camera.follow(self.player, lerp=0.12)

game = e.Game("Easy2D", 960, 540)
game.set_scene(MainScene())
game.run()

Core API

Game

• Main loop, screen, timing, and input state
• delta_time, elapsed_time, fps
• Input helpers: key_pressed, key_just_pressed, mouse helpers

Scene

• Object container with safe add/remove during updates
• Hooks: on_enter, on_exit, handle_event
• Query helpers: find_by_name, find_by_tag, find

GameObject

• Base entity with lifecycle hooks and visibility/active flags
• Properties: x, y, z, active, visible, destroyed

Camera

• World/screen conversion helpers
• Smooth follow with optional world bounds

TileMap

• Sparse tile storage plus chunk-surface caching
• Visible-chunk rendering for better large-map performance
• Helpers: set, remove, fill_rect, world_to_tile, tile_to_world, solid flags

ParticleSystem

• Configurable particle effects with lifespan and gravity

Build Bigger Worlds

Easy2D now supports chunk-cached tile rendering, which is a key building block for games with large tile worlds.

For Minecraft-like workflows, combine:

• TileMap for block placement and chunk rendering
• Camera follow and world/screen conversion
• Mouse world coordinates for place/remove actions
• Scene queries and object tags for gameplay systems

CLI Commands

After install, Easy2D includes a CLI command:

easy2d --help

Useful commands:

# Show multiplayer setup with private/public IP + port
easy2d --multiplayer

# Print current feature scope
easy2d --show-scope

# Choose a different port in the display
easy2d --multiplayer --port 7777

# Start a relay host and wait for clients
easy2d --host --port 5000

# Join a host and send a test packet
easy2d --join 192.168.1.117 --port 5000 --message "hello"

# Run local networking loopback test
easy2d --net-test --port 5000

# List available code examples
easy2d --list-examples

# Write one example file into current folder
easy2d --write-example multiplayer_host
easy2d --write-example multiplayer_join

# Write all example files
easy2d --write-all-examples

The multiplayer command prints:

• Your private IP (for LAN friends)
• Your public IP (for internet friends)
• Port to share
• Quick next steps for port forwarding

This makes onboarding easier for users testing multiplayer quickly.

Current Scope

Easy2D is intentionally lightweight. It does not yet include:

• Full rigidbody physics and collision resolution
• Built-in sprite animation pipeline
• Chunk streaming from disk
• Matchmaking and account services

These can be layered in while keeping the current API stable.

Package

• Name: easy2d
• Python: >=3.8
• Dependency: pygame>=2.5
• License: MIT