Skip to content

API Reference

Complete reference for the Pedre framework's Python API.

Overview

The Pedre framework is built on several core architectural components that work together to provide a flexible, event-driven RPG engine. This reference covers the framework's public API for Python developers.

Architecture

graph TD
    Game["<b>Game</b><br/><i>Coordinates lifecycle &amp; plugin initialization</i>"]
    EventBus["EventBus"]
    GameContext["GameContext<br/><i>(plugin registry)</i>"]
    GameView["GameView<br/><i>(arcade.View)</i>"]
    Actions["Actions"]
    Events["Events"]
    Conditions["Conditions"]
    Plugins["Plugins"]
    Validators["Validators<br/><i>(CLI / offline)</i>"]
    ValidationContext["ValidationContext"]

    Game --> EventBus
    Game --> GameContext
    Game --> Actions
    Game --> Events
    Game --> Conditions
    Game --> GameView
    EventBus --> GameContext
    GameContext --> Plugins
    Validators --> ValidationContext

Core Components

Game

Central coordinator for game lifecycle and plugin initialization.

Responsibilities:

  • Initialize plugins in correct order (Actions → Events → Conditions → Plugins)
  • Manage GameView lifecycle (new game, continue, load, exit)
  • Coordinate save/load operations
  • Own long-lived objects (EventBus, GameContext, PluginLoader)

Key Methods:

  • start_new_game(), start_game_or_load(), continue_game()
  • load_game(), exit_game()
  • show_game()

Views

Primary game screen.

GameView:

  • GameView - Main gameplay with all plugins active
  • Managed by the Game coordinator

GameContext

Central registry providing plugins with access to the event bus and other plugins.

Responsibilities:

  • Plugin registration and retrieval
  • Event bus access
  • Dependency injection

Key Methods:

  • get_plugin(name: str) -> BasePlugin | None

EventBus

Publish-subscribe event system for decoupled communication.

Responsibilities:

  • Event subscription and publishing
  • Plugin-to-plugin communication
  • Script trigger handling

Key Methods:

  • subscribe(event_type, callback)
  • publish(event)
  • unsubscribe(event_type, callback)

Validators

Two-phase asset validation system for maps, scripts, dialogs, sprites, NPCs, players, and items. Used by the pedre validate CLI command and can be called programmatically.

Responsibilities:

  • Structural validation of individual asset files (Phase 1)
  • Cross-reference validation between asset types (Phase 2)

Key Classes:

  • ValidationResult — result dataclass with errors, item_count, and metadata
  • Validator — ABC to subclass for custom validators
  • ValidationContext — shared context populated in Phase 1 and read in Phase 2

PluginLoader

Handles dynamic loading, dependency resolution, and lifecycle management for all plugins.

Responsibilities:

  • Instantiate plugins in dependency order (topological sort)
  • Detect circular dependencies
  • Manage plugin lifecycle (setup, reset, cleanup)

Sprites

Animated character sprites for player and NPCs.

Available Sprites:

  • AnimatedPlayer - Player character with 4-directional animation
  • AnimatedNPC - NPC characters with special animations

Game Plugins

Pedre uses a plugin-based architecture where each plugin handles specific functionality. All plugins are documented in the Plugins Reference.

Core Plugins:

See all plugins →

Extension System

Pedre supports adding custom functionality without modifying framework code. See Extending Pedre for details.

Extension Points:

  • Custom Actions - Script commands
  • Custom Events - Trigger types
  • Custom Conditions - Conditional logic
  • Custom Plugins - Complete game features

Usage Patterns

Accessing Plugins

Plugins are accessed through the GameContext:

# In a plugin or action
dialog_plugin = context.get_plugin("dialog")
npc_plugin = context.get_plugin("npc")
audio_plugin = context.get_plugin("audio")

Publishing Events

Events enable decoupled communication:

from pedre.events import DialogClosedEvent

# Publish an event
context.event_bus.publish(DialogClosedEvent(
    npc_name="merchant",
    dialog_level=1
))

Subscribing to Events

Plugins can react to events:

def on_dialog_closed(event: DialogClosedEvent):
    print(f"Dialog closed: {event.npc_name}")

context.event_bus.subscribe(DialogClosedEvent, on_dialog_closed)

Game Lifecycle

Control game flow through the Game coordinator:

# Start a new game
game.start_new_game()

# Continue existing game or load autosave
game.continue_game()

# Show game view
game.show_game()

# Load game from save data
game.load_game(save_data)

Configuration

Game behavior is configured through settings.py. See Configuration Guide for all available settings.

Common Settings:

  • Window size and title
  • Player movement speed
  • Plugin-specific configuration
  • Asset paths

Type System

Pedre uses Python type hints throughout. Key types:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pedre.plugins.game_context import GameContext
    from pedre.events.base import EventBus
    from pedre.plugins.base import BasePlugin

Initialization Flow

1. Game Startup

from pedre import run_game

if __name__ == "__main__":
    run_game()

2. Plugin Loading

The framework automatically:

  1. Loads configuration from settings.py
  2. Creates arcade Window
  3. Creates Game coordinator
  4. Game creates EventBus and GameContext (long-lived objects)
  5. Loads Actions, Events, and Conditions
  6. Loads all plugins via PluginLoader
  7. Sets up event subscriptions
  8. Starts game directly (autoload or new game)

3. Game Loop

Each frame:

  1. Process input
  2. Update plugins (update(delta_time))
  3. Render views (on_draw())
  4. Handle events

Best Practices

Event-Driven Design

Prefer events over direct plugin calls:

# Good: Event-driven
context.event_bus.publish(NPCInteractedEvent(npc_name="merchant"))

# Avoid: Direct coupling
npc_plugin.interact("merchant")
dialog_plugin.show_dialog("merchant", ["Hello!"])

Plugin Dependencies

Access plugins through GameContext, not global imports:

# Good: Via context
def execute(self, context):
    audio = context.get_plugin("audio")
    if audio:
        audio.play_sfx("sound.wav")

# Avoid: Direct import
from pedre.plugins.audio import AudioPlugin
audio = AudioPlugin()  # Creates duplicate instance

Error Handling

Check for plugin availability:

weather = context.get_plugin("weather")
if weather:
    weather.set_weather("rain")
else:
    # Weather plugin not installed
    pass

Next Steps