pedre 0.1.0
A Python RPG framework built on Arcade with seamless Tiled map editor integration
License: BSD-3-Clause
Requires Python: >=3.14
Keywords: 2d-game, arcade, game, game-engine, game-framework, rpg, tiled, tilemap

# Pedre

A Python RPG framework built on [Arcade](https://api.arcade.academy/) with seamless [Tiled](https://www.mapeditor.org/) map editor integration. Build Zelda-like games with dialog systems, NPC interactions, inventory management, and event-driven scripting.

## Features

- **Tiled Map Integration** - Load .tmx maps with automatic layer detection and object parsing
- **NPC Plugin** - Animated NPCs with dialog trees, pathfinding, and state management
- **Dialog Plugin** - Multi-page conversations with character names and pagination
- **Event-Driven Scripting** - JSON-based cutscenes and interactive sequences
- **Inventory Management** - Item collection and categorization plugin
- **Portal Plugin** - Map transitions with conditional triggers
- **Save/Load Plugin** - Automatic game state persistence
- **Audio Management** - Background music and sound effects with caching
- **Camera Plugin** - Smooth camera following with optional bounds
- **Particle Effects** - Visual feedback plugin for interactions

## Installation

Install from PyPI:

```bash
pip install pedre
```

Or with uv:

```bash
uv add pedre
```

## Quick Start

```python
from pedre import run_game

if __name__ == "__main__":
    run_game()
```

This will start your game with the default configuration. Configure your game using `settings.py` in your project root:

```python
SCREEN_WIDTH=1280
SCREEN_HEIGHT=720,
WINDOW_TITLE="My RPG",
INITIAL_MAP="my_map.tmx"
```

### Adding NPCs with Dialogs

Create a dialog file `assets/dialogs/village_dialogs.json`:

```json
{
  "merchant": {
    "0": {
      "name": "Merchant",
      "text": [
        "Welcome to my shop!",
        "Take a look around."
      ]
    }
  }
}
```

Place the NPC in your Tiled map's "NPCs" layer with custom properties:

- `name`: "merchant"
- NPC sprite will be automatically loaded and animated

### Creating Interactive Scripts

Create a script file `assets/scripts/village_scripts.json`:

```json
{
  "meet_merchant": {
    "scene": "village",
    "trigger": {
      "event": "npc_interacted",
      "npc": "merchant"
    },
    "actions": [
      {
        "type": "dialog",
        "speaker": "Merchant",
        "text": ["Welcome to my shop!", "Take a look around."]
      },
      {
        "type": "play_sfx",
        "file": "coin.wav"
      }
    ]
  }
}
```

### Adding Portals Between Maps

In Tiled, create a "Portals" object layer and add a rectangle with a `name` property:

- `name`: "to_forest"

Create a matching waypoint in the target map's "Waypoints" layer (Point object named "from_village") where the player should spawn.

Then create a script to handle the portal transition:

```json
{
  "to_forest_portal": {
    "trigger": {"event": "portal_entered", "portal": "to_forest"},
    "actions": [
      {"type": "change_scene", "target_map": "forest.tmx", "spawn_waypoint": "from_village"}
    ]
  }
}
```

This event-driven approach allows conditional portals, cutscenes before transitions, and locked doors with custom failure messages.

## Demo Project

Want to see a complete working example? Check out **[msaizar/pedre-demo](https://github.com/msaizar/pedre-demo)** - a fully functional RPG demo showcasing the framework's features including NPCs, dialogs, inventory, portals, and scripted events.

## Architecture

The framework uses a **plugin-based architecture** with event-driven communication:

- **Views** - Menu, Game, Inventory, Load screens
- **Sprites** - AnimatedPlayer, AnimatedNPC with sprite sheet support
- **Plugins** - Modular plugins for different game aspects:
  - DialogPlugin - Conversation display
  - NPCPlugin - NPC state and interactions
  - PortalPlugin - Map transitions
  - ScriptPlugin - Event-driven actions
  - InventoryPlugin - Item management
  - AudioPlugin - Sound and music
  - SavePlugin - Game persistence
  - And more...

## Development

Want to contribute or run from source?

```bash
# Clone the repository
git clone https://github.com/msaizar/pedre.git
cd pedre

# Install with dev dependencies
uv sync

# Run quality checks
just qa

# Run tests
just test
```

This project uses modern Python tooling:

- **uv** - Fast Python package manager
- **ruff** - Linter and formatter
- **ty** - Type checker
- **pytest** - Testing framework
- **just** - Command runner

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## Documentation

Full documentation is available at **[msaizar.github.io/pedre](https://msaizar.github.io/pedre/)**

## License

BSD 3-Clause License - See [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests.

## Credits

Built with:

- [Python Arcade](https://api.arcade.academy/) - 2D game framework
- [Tiled Map Editor](https://www.mapeditor.org/) - Level design tool