Metadata-Version: 2.4
Name: ludos
Version: 0.2.0
Summary: Pygame abstraction framework for rapid game development
Project-URL: Homepage, https://github.com/mclarkelauer/ludos
Project-URL: Repository, https://github.com/mclarkelauer/ludos
Project-URL: Issues, https://github.com/mclarkelauer/ludos/issues
Author-email: Matt Clarke-Lauer <mdlauer@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: pygame
Requires-Python: >=3.12
Requires-Dist: pygame-ce>=2.5.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Ludos

Pygame-ce abstraction framework that eliminates boilerplate for rapid game development. Clean separation between input, state, and rendering with extensibility at every layer.

## Install

```bash
pip install ludos
```

## Quick Start

```python
from dataclasses import dataclass
import pygame
from ludos import (
    BaseGameState, BaseScene, EngineConfig, GameEngine,
    KeyBindings, SceneManager, StateManager,
)

@dataclass
class MyState(BaseGameState):
    score: int = 0

class PlayScene(BaseScene):
    def handle_input(self, events, state_manager):
        pass

    def update(self, dt, state_manager):
        pass

    def render(self, surface, state_manager):
        surface.fill((0, 0, 0))

config = EngineConfig(title="My Game", width=800, height=600)
state_manager = StateManager(MyState())
scene_manager = SceneManager()
scene_manager.push(PlayScene())

engine = GameEngine(config)
engine.run(scene_manager, state_manager)
```

## Features

- **State management** — Subclass `BaseGameState` as a dataclass, mutate through `StateManager.update()`
- **Scene stack** — Push/pop/replace scenes with `on_enter`/`on_exit` lifecycle hooks
- **Input mapping** — Map raw pygame keys to semantic actions via `KeyBindings`
- **Display wrapper** — `Window` handles pygame display init and surface management
- **Built-in menu** — `MenuScene` with configurable `MenuConfig` for quick prototyping
- **Error hierarchy** — All errors inherit `LudosError` for unified catching

## Documentation

See the [user guide](docs/guide.md) for full documentation.

## License

MIT
