Metadata-Version: 2.5
Name: sypy-engine-beginner
Version: 0.1.2
Summary: A beginner-friendly 2D game engine built with Python and Pygame
Author: Methuka Koralage
License: MIT License
        
        Copyright (c) 2026 Methuka
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files, to deal in the Software
        without restriction, including without limitation the rights to use, copy,
        modify, merge, publish, distribute, sublicense, and/or sell copies of the
        Software, and to permit persons to whom the Software is furnished to do so,
        subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pygame==2.6.1
Description-Content-Type: text/markdown

# SyPy Engine 2.0

**SyPy Engine** is a modular, beginner-friendly **2D game engine built with Python and Pygame**.

SyPy is designed to give developers the features of a real game engine while keeping the code understandable and fully customizable.

> **Current Version: 2.0**

---

# 🚀 Features

SyPy 2.0 includes a large set of systems for building complete 2D games:

* 🎮 Game loop
* 👤 Entity system
* ⚙️ Physics
* 💥 Collision system
* 🧱 Solid objects
* 🪜 One-way platforms
* 🔄 Moving platforms
* 🎥 Camera system
* 🖼️ Rendering system
* 🎨 Shapes and custom drawing
* 🧍 Character movement
* 🦘 Jumping
* 🖼️ Sprites
* 🎞️ Animations
* 🗺️ Tilemaps
* 🎯 Hitboxes
* 🔔 Triggers
* ✨ Particles
* 🧩 Components
* 🎬 Scenes
* 🎮 Input system
* 🖱️ UI system
* 🔊 Audio system
* 📦 Asset management
* 💾 Save/load
* 🐛 Debug tools
* 📊 Debug information
* 📐 Camera/world coordinate conversion
* 🧱 World boundaries
* 🎨 Render layers
* ⚡ Asset caching
* 🔧 Game-side configuration

---

# 📦 Installation

Install SyPy with pip:

```bash
pip install sypy-engine-beginner
```

Install Pygame if required:

```bash
pip install pygame
```

Then import SyPy:


from engine import Engine


---

# 🎮 Basic Usage

A SyPy game starts with an `Engine`.


from engine import Engine

game = Engine()

game.run()


The engine handles the main game loop while the game controls its own objects and gameplay.

---

# 👤 Entities

Entities are the main objects inside a SyPy game.

```python
player = game.add_entity("player")
```

An entity can contain things such as:

```text
Name
Position
Velocity
Size
Tags
Color
Sprite
Collider
Update function
Components
```

Example:


player.position = [100, 250]
player.velocity = [0, 0]
player.size = [50, 50]
player.tags = ["player"]

Entities can also have custom update logic:


player.set_update(player_update)


---

# ⚙️ Physics

SyPy 2.0 contains a more complete physics foundation.

The physics system handles:

* Velocity
* Gravity
* Acceleration
* Friction
* Movement
* Jumping
* Collision response
* Platforms
* Moving platforms
* One-way platforms

The goal is to allow platformer-style movement without requiring the developer to manually implement every physics calculation.

---

# 💥 Collision System

SyPy uses collision detection to allow entities to interact with the world.

The collision system supports things such as:

* Entity collisions
* Solid collisions
* Hitboxes
* Triggers
* Collision layers
* Collision callbacks
* Platform collisions

Basic collision flow:

```text
Entity
   ↓
Collision Detection
   ↓
Collision Response
   ↓
Physics Update
```

---

# 🧱 Solids

Solids are objects that entities cannot pass through.

Example:


wall.stop_pass(player)


Solids can be used for:

* Floors
* Walls
* Platforms
* Obstacles
* Level geometry

---

# 🪜 Platforms

SyPy supports different platform behaviors.

### Normal platforms

Entities collide with them normally.

### One-way platforms

The player can pass through the platform from below but land on it from above.

### Moving platforms

Platforms can move through the level while interacting with entities.

This makes it possible to create platformer mechanics without implementing platform movement from scratch.

---

# 🎥 Camera

SyPy 2.0 has a dedicated camera system.

The camera separates:

```text
World Coordinates
       ↓
     Camera
       ↓
Screen Coordinates
```

It supports things such as:

* Camera following
* Scrolling
* World-to-screen conversion
* Screen-to-world conversion
* Camera offsets
* Large levels

The camera can be configured by the game instead of being permanently hardcoded into the engine.

---

# 🖼️ Rendering

Rendering is separated from the main engine logic.

SyPy's intended rendering order is:

```text
Background
    ↓
Tilemap
    ↓
Entities
    ↓
Effects
    ↓
UI
    ↓
Debug
```

This makes rendering order predictable and allows different systems to draw independently.

---

# 🎨 Shapes

SyPy can render basic shapes without requiring image assets.

Examples include:

* Rectangles
* Borders
* Filled shapes
* Debug shapes
* Placeholder objects

This makes it possible to prototype a game before creating the actual artwork.

---

# 🖼️ Sprites

Entities can use sprites instead of simple shapes.

The engine is designed to support:

* Sprite loading
* Sprite replacement
* Sprite scaling
* Sprite positioning
* Fallback rendering

This means a developer can prototype with rectangles and later replace them with actual artwork.

---

# 🎞️ Animation

SyPy supports animated entities through its animation system.

Animations can be used for:

```text
Idle
Run
Jump
Fall
Attack
Death
```

The animation system is designed to work alongside sprites and entities rather than requiring custom animation code in every game.

---

# 🗺️ Tilemaps

SyPy 2.0 includes a tilemap system for building larger levels.

Tilemaps can contain:

* Tiles
* Layers
* Collision information
* Background layers
* Foreground layers
* Tile properties

Example level structure:

```text
Background
    ↓
Tilemap
    ↓
Collision Layer
    ↓
Entities
    ↓
Effects
```

---

# 🎯 Hitboxes

Hitboxes allow entities to have collision areas separate from their main visual rectangle.

Useful for:

* Attacks
* Damage areas
* Interaction zones
* Enemies
* Projectiles
* Custom collision shapes

---

# 🔔 Triggers

Triggers detect when entities enter or leave an area without necessarily physically blocking them.

Example:

```text
Player enters trigger
        ↓
"Entered trigger!"
        ↓
Run event
```

Triggers can be used for:

* Doors
* Checkpoints
* Cutscenes
* Level transitions
* Enemy activation
* Interaction zones

---

# ✨ Particles

SyPy includes a particle system for visual effects.

Particles can be used for:

* Smoke
* Sparks
* Dust
* Explosions
* Trails
* Magic effects
* Hit effects

Particles are managed separately from normal entities.

---

# 🧩 Components

SyPy 2.0 supports a component-oriented architecture.

Instead of putting every feature directly into an entity, functionality can be separated into components.

Example:

```text
Player
├── Transform
├── Physics
├── Collider
├── Sprite
├── Animation
└── Health
```

This makes complex games easier to organize.

---

# 🎬 Scenes

Scenes allow games to separate different parts of the game.

For example:

```text
Main Menu
    ↓
Level 1
    ↓
Level 2
    ↓
Boss
    ↓
Game Over
```

Scenes can contain their own entities, systems and game state.

---

# 🎮 Input System

SyPy provides a centralized input system for handling player controls.

It is designed to support:

* Keyboard
* Mouse
* Controller/gamepad input
* Key states
* Press/release detection
* Game actions

Game-specific controls should remain configurable by the game.

---

# 🖱️ UI

SyPy has a dedicated UI system separate from the game world.

Planned/available UI elements include:

* Buttons
* Text
* Panels
* Sliders
* Menus
* HUD elements

UI remains fixed to the screen while the camera moves through the world.

---

# 🔊 Audio

The audio system handles game sounds separately from gameplay logic.

It is designed for:

* Sound effects
* Music
* Volume control
* Audio assets
* Background music

---

# 📦 Asset Management

SyPy includes centralized asset management.

Assets can include:

```text
Images
Sprites
Sounds
Music
Fonts
Other resources
```

Asset caching helps prevent repeatedly loading the same resources.

---

# 💾 Save & Load

SyPy supports game data persistence through its save/load system.

Games can store things such as:

* Player progress
* Settings
* Level state
* Game variables
* Save slots

Save functionality remains separate from gameplay logic.

---

# 🐛 Debug System

SyPy includes debugging tools for development.

Debug information can include:

```text
FPS
Entity count
Entity positions
Velocity
Collision boxes
Hitboxes
Triggers
Camera position
Physics information
```

Debug rendering can be enabled while developing and disabled for the final game.

---

# 📐 World Boundaries

Games can define boundaries for their worlds.

These can prevent entities from leaving the playable area.

Example:

```text
┌──────────────────────────┐
│                          │
│        GAME WORLD        │
│                          │
│                          │
└──────────────────────────┘
```

---

# 🎨 Render Layers

SyPy uses separate rendering layers so objects can be drawn in a predictable order.

Example:

```text
0  Background
1  Tilemap
2  Entities
3  Particles
4  Effects
5  UI
6  Debug
```

This prevents systems from fighting over what should appear in front.

---

# 🏗️ Architecture

The engine is separated into independent systems.

Example structure:

```text
engine/
│
├── engine.py
│
├── core/
│   ├── entity.py
│   ├── updater.py
│   ├── solid.py
│   ├── physics.py
│   ├── particle.py
│   └── debug.py
│
├── collisions/
│   └── collisions.py
│
├── camera/
│   └── camera.py
│
├── rendering/
│   └── renderer.py
│
├── scenes/
│
├── tilemaps/
│
├── input/
│
├── components/
│
├── ui/
│
├── audio/
│
├── assets/
│
└── save/
```

The architecture can continue to evolve as the engine grows.

---

# 🧠 Game Configuration

SyPy follows an important rule:

> **The engine provides the systems. The game decides how to use them.**

Game-specific settings should stay inside the game's `main.py` or game project whenever possible.

For example:


player.position = [100, 250]


rather than forcing a specific position into the engine itself.

This allows the same SyPy installation to power completely different games.

---

# ⚡ Performance

SyPy is designed to remain lightweight while still supporting larger games.

Performance-focused systems include:

* Asset caching
* Efficient collision handling
* Spatial collision optimization
* Separated rendering
* Controlled particle updates
* Debug systems that can be disabled

The engine prioritizes understandable code over unnecessary complexity.

---

# 📚 Philosophy

SyPy is built around four main ideas:

### Simple

Creating a basic game should not require understanding hundreds of classes.

### Modular

Each major feature should have its own system.

### Customizable

The developer should control their game rather than fighting the engine.

### Expandable

A small prototype should be able to grow into a complete game.

---

# 🛣️ SyPy 2.0 Roadmap

## Core

* [x] Engine
* [x] Game loop
* [x] Entities
* [x] Physics
* [x] Collision system
* [x] Solids
* [x] Platforms
* [x] Camera
* [x] Rendering

## Gameplay

* [x] Jumping
* [x] One-way platforms
* [x] Moving platforms
* [x] Hitboxes
* [x] Triggers
* [x] Collision layers
* [x] Character movement

## Graphics

* [x] Shape rendering
* [x] Sprites
* [x] Animation
* [x] Render layers
* [x] Camera transformations

## World

* [x] Tilemaps
* [x] Tile layers
* [x] World boundaries
* [x] Collision geometry

## Systems

* [x] Input
* [x] Components
* [x] Scenes
* [x] Particles
* [x] Audio
* [x] UI
* [x] Assets
* [x] Save/load
* [x] Debugging

## Future

* [ ] More advanced physics
* [ ] Better slope support
* [ ] One-way collision improvements
* [ ] More UI components
* [ ] More advanced animation tools
* [ ] Expanded editor/tooling
* [ ] More optimization
* [ ] Larger automated test suite

---

# 📜 Version History

## SyPy 2.0

Major engine expansion.

Added and expanded:

* Entity architecture
* Physics
* Collision system
* Camera
* Rendering
* Platforms
* One-way platforms
* Moving platforms
* Triggers
* Hitboxes
* Tilemaps
* Sprites
* Animation
* Particles
* Components
* Scenes
* Input
* UI
* Audio
* Asset management
* Save/load
* Debugging
* Render layers
* World boundaries

SyPy 2.0 represents the transition from a small Pygame framework into a much more complete 2D game engine.

---

# ❤️ Why SyPy?

SyPy is not trying to hide game development behind a giant editor.

It is a Python engine where you can actually understand what your game is doing.

```text
Python
  ↓
SyPy
  ↓
Pygame
  ↓
Your Game
```

Build it yourself.

Understand it.

Modify it.

Make it yours.

---

# 📄 License

See the project's license file for the current licensing terms.
