Configuration Guide¶

Pedre uses the settings.py file for configuration.

Configuration Overview¶

Configure your game by creating a settings.py file in your project root:

SCREEN_WIDTH=1280
SCREEN_HEIGHT=720
WINDOW_TITLE="My RPG Game"
PLAYER_MOVEMENT_SPEED=180.0
TILE_SIZE=32
INTERACTION_PLUGIN_DISTANCE=50
NPC_INTERACTION_DISTANCE=50
PORTAL_INTERACTION_DISTANCE=50
WAYPOINT_THRESHOLD=2
NPC_SPEED=80.0
MENU_TITLE="My RPG Game"
MENU_TITLE_SIZE=48
MENU_OPTION_SIZE=24
MENU_SPACING=50
MENU_BACKGROUND_IMAGE="images/backgrounds/menu.png"
MENU_PRELOD_MUSIC_FILES=["menu_music.ogg"]
INVENTORY_GRID_COLS=10
INVENTORY_GRID_ROWS=4
INVENTORY_BOX_SIZE=30
INVENTORY_BOX_SPACING=5
INVENTORY_BOX_BORDER_WIDTH=1
INVENTORY_BACKGROUND_IMAGE=""
DIALOG_AUTO_CLOSE_DEFAULT=False
DIALOG_AUTO_CLOSE_DURATION=0.5
DIALOG_BOX_WIDTH_PERCENT=0.75
DIALOG_BOX_HEIGHT_PERCENT=0.25
AUDIO_MUSIC_VOLUME=0.5
AUDIO_MUSIC_ENABLED=True
AUDIO_SFX_VOLUME=0.7
AUDIO_SFX_ENABLED=True
CAMERA_LERP_SPEED=0.1
ASSETS_HANDLE="game_assets"
INITIAL_MAP="start.tmx"

Configuration Settings¶

Window Settings¶

Control window and display properties.

Input Settings¶

Input handling and player movement configuration.

Notes:

• PLAYER_MOVEMENT_SPEED controls how fast the player moves per second when movement keys are pressed
• Applied to the normalized movement vector returned by InputPlugin.get_movement_vector(delta_time)
• Movement is frame-rate independent, ensuring consistent speed across different devices
• Typical values range from 100.0 (slow) to 300.0 (fast)
• For more details, see the InputPlugin documentation

Player Settings¶

Player character interaction settings.

Notes:

• INTERACTION_PLUGIN_DISTANCE determines how close the player must be to interact with objects
• Common values: 32 (1 tile), 50 (default, ~1.5 tiles), 64 (2 tiles), 96 (3 tiles)
• Uses Euclidean distance from player center to object center
• For more details, see the InteractionPlugin documentation
• INTERACTION_KEY can be set to any arcade key constant (e.g., "E", "SPACE", "RETURN"). Keys are matched using the matches_key() helper function
• NPC_INTERACTION_DISTANCE determines how close the player must be to interact with NPCs
• PORTAL_INTERACTION_DISTANCE determines how close the player must be to activate portals
• Common values: 32 (1 tile), 50 (default, ~1.5 tiles), 64 (2 tiles), 96 (3 tiles)
• Uses Euclidean distance from player center to portal center
• Creates a circular activation zone around each portal
• Events only fire when player enters the zone (not while standing in it)
• For more details, see the PortalPlugin documentation
• WAYPOINT_THRESHOLD controls pathfinding precision (lower = more precise)

NPC Settings¶

NPC behavior and interaction settings.

Notes:

• NPC_INTERACTION_DISTANCE determines how close the player must be to interact with NPCs
• NPC_MOVEMENT_SPEED is the default speed for all NPCs using pathfinding
• NPC_WAYPOINT_THRESHOLD controls pathfinding precision (lower = more precise turns)
• NPC_INTERACTION_KEY can be set to any arcade key constant (e.g., "E", "F", "RETURN")

Menu Settings¶

Main menu appearance and behavior.

Notes:

• menu_background_image is optional; leave empty for solid color background
• All paths are relative to the assets resource handle

Inventory Settings¶

Inventory grid layout, capacity, and appearance.

Grid Layout Settings¶

Capacity and Display Settings¶

Data and Input Settings¶

Hint Text Settings¶

Notes:

• Total inventory capacity is controlled by INVENTORY_MAX_SPACE, not grid size
• Grid can show fewer items than capacity (e.g., 4×3 grid = 12 slots, but capacity can be higher)
• This allows for scrolling or pagination in custom implementations
• INVENTORY_BACKGROUND_IMAGE is optional; leave empty for semi-transparent default background
• Item definitions in INVENTORY_ITEMS_FILE are loaded on setup
• Key bindings can use single characters (e.g., "V") or arcade key constants
• For more details, see the InventoryPlugin documentation

Dialog Settings¶

Dialog plugin behavior, timing, and appearance.

Behavior Settings¶

Layout Settings¶

Font Settings¶

Text Labels¶

Notes:

• Auto-close behavior: DIALOG_AUTO_CLOSE_DEFAULT controls whether dialogs auto-close by default. The timer starts after the text reveal animation completes. Useful for cutscenes where you want dialogs to automatically advance.
• Text reveal animation: DIALOG_CHAR_REVEAL_SPEED controls how fast text appears (characters per second). Set DIALOG_INSTANT_TEXT_DEFAULT=True to disable the reveal animation globally, or use the instant parameter in show_dialog() for specific dialogs.
• UI toggles: Use DIALOG_SHOW_HELP and DIALOG_SHOW_PAGINATION to control which UI elements are displayed. Hiding these can create a cleaner look for cutscenes.
• Responsive sizing: Dialog box dimensions scale with window size using percentage-based values, constrained by min/max limits for readability
• Width calculation: Actual width = min(DIALOG_BOX_MAX_WIDTH, max(DIALOG_BOX_MIN_WIDTH, window_width × DIALOG_BOX_WIDTH_PERCENT))
• Height calculation: Actual height = max(DIALOG_BOX_MIN_HEIGHT, window_height × DIALOG_BOX_HEIGHT_PERCENT)
• Position: DIALOG_VERTICAL_POSITION of 0.25 means the dialog center is at 25% from the bottom of the screen
• Overlay: Semi-transparent overlay covers the entire screen behind the dialog. Alpha value of 128 = 50% transparency
• Input: DIALOG_KEY_ADVANCE can be set to any arcade key constant (e.g., "RETURN", "E", "SPACE"). Keys are matched using the matches_key() helper function
• Localization: The DIALOG_TEXT_* settings allow you to customize instruction text for different languages or game styles

Audio Settings¶

Audio plugin default values for music and sound effects.

Notes:

• These settings control the initial state of the AudioPlugin when it's initialized
• Volume values are clamped to the range 0.0 to 1.0
• Players can change these values at runtime using the AudioPlugin methods
• Changes made at runtime are not persisted unless explicitly saved
• For more details, see the AudioPlugin documentation

Camera Settings¶

Camera plugin behavior and movement configuration.

Notes:

• CAMERA_LERP_SPEED controls how quickly the camera catches up to its target
• Lower values (e.g., 0.05): Slower, more dramatic camera movement
• Default (0.1): Smooth, balanced camera following
• Higher values (e.g., 0.2): More responsive, tighter camera
• 1.0: Instant following with no smoothing
• The lerp speed determines what fraction of the remaining distance the camera moves each frame
• For more details, see the CameraPlugin documentation

Particle Settings¶

Particle plugin configuration for visual effects.

Notes:

• PARTICLE_ENABLED controls whether particles are active on game start
• Can be toggled at runtime using particle_plugin.toggle()
• Useful for performance optimization on low-end devices
• Color settings define default colors for each particle type
• Colors can be overridden per-action using the color parameter in scripts
• RGB values range from 0 to 255
• Example custom colors:
  • Deep pink hearts: PARTICLE_COLOR_HEARTS = (255, 20, 147)
  • Gold sparkles: PARTICLE_COLOR_SPARKLES = (255, 215, 0)
  • Green trail: PARTICLE_COLOR_TRAIL = (0, 255, 100)
  • Red burst: PARTICLE_COLOR_BURST = (255, 0, 0)
• For more details, see the ParticlePlugin documentation

Scene Settings¶

Scene transition and map loading configuration.

Notes:

• Transition timing: The total transition duration is 2.0 / SCENE_TRANSITION_SPEED seconds
• Default (3.0): ~0.67 seconds total (~0.33s fade out + ~0.33s fade in)
• Faster (5.0): ~0.4 seconds total
• Slower (2.0): ~1.0 second total
• Very fast (10.0): ~0.2 seconds total
• Transition alpha: SCENE_TRANSITION_ALPHA controls the starting transparency for transitions
• 0.0 (default): Starts fully transparent, fades to black
• Higher values create different effects (not recommended to change)
• Map folder: SCENE_MAPS_FOLDER is where the ScenePlugin looks for .tmx files
• Path is relative to the assets directory
• Example: If ASSETS_HANDLE points to "assets/", then "maps" resolves to "assets/maps/"
• Tilemap scaling: SCENE_TILEMAP_SCALING scales the entire loaded map
• 1.0 (default): No scaling
• 2.0: Double size (useful for pixel art)
• 0.5: Half size
• Collision layers: SCENE_COLLISION_LAYER_NAMES defines which Tiled layers become collision walls
• All layers in this list are combined into a single collision wall list
• Layer names are case-sensitive and must match exactly
• Order doesn't matter (all layers are combined)

• Can customize to use fewer or different layer names:

  SCENE_COLLISION_LAYER_NAMES = ["Walls"]  # Only use Walls layer
  

• For more details, see the ScenePlugin documentation

Debug Settings¶

Debug plugin configuration for development overlays.

Notes:

• TILE_SIZE is used by the debug plugin to convert pixel coordinates to tile coordinates
• Debug overlay displays both pixel coordinates and tile coordinates
• Tile coordinates are calculated as: tile_x = int(pixel_x / TILE_SIZE)
• Debug mode is toggled with Shift+D keyboard shortcut
• Shows player position in tile and pixel coordinates
• Shows visible NPC positions in tile and pixel coordinates
• Shows NPC dialog levels
• For more details, see the DebugPlugin documentation

Asset Settings¶

Asset management configuration.

Notes:

• This handle is registered with Arcade's resource system
• Used to load assets with arcade.resources.resolve()
• Should match the handle used when registering your assets directory

Save Plugin Settings¶

Save plugin configuration for game persistence.

Notes:

• SAVE_FOLDER specifies the directory path (relative to project root) where save files are stored
• Directory is created automatically if it doesn't exist
• Save files are JSON format: autosave.json, save_slot_1.json, etc.
• SAVE_QUICK_SAVE_KEY and SAVE_QUICK_LOAD_KEY can be any arcade key constant
• Common values: "F5", "F6", "F7", "F8", "F9"
• Keys are matched using the matches_key() helper function
• Quick save uses the auto-save slot (slot 0)
• Quick load loads from the auto-save slot
• SAVE_SFX_FILE is played on successful save/load operations
• Path is relative to the assets directory
• Only plays if AudioPlugin is enabled
• For more details, see the SavePlugin documentation

Game Settings¶

Core game settings.

Accessing Configuration in Code¶

Configuration is accessed through pedre.conf.settings:

from pedre.conf import settings

# Access settings directly
print(f"Window size: {settings.SCREEN_WIDTH}x{settings.SCREEN_HEIGHT}")
print(f"Player speed: {settings.PLAYER_MOVEMENT_SPEED}")

Example: Complete Configuration¶

Here's a complete example configuration for a game:

# Window settings
SCREEN_WIDTH=1600
SCREEN_HEIGHT=900
WINDOW_TITLE="Mystic Quest"

# Input settings
PLAYER_MOVEMENT_SPEED=200.0

# Player settings
TILE_SIZE=32
INTERACTION_PLUGIN_DISTANCE=60
INTERACTION_KEY="E"
NPC_INTERACTION_DISTANCE=60
PORTAL_INTERACTION_DISTANCE=60
WAYPOINT_THRESHOLD=2

# NPC settings
NPC_MOVEMENT_SPEED=90.0
NPC_WAYPOINT_THRESHOLD=2
NPC_INTERACTION_KEY="E"

# Menu settings
MENU_TITLE="Mystic Quest"
MENU_TITLE_SIZE=56
MENU_OPTION_SIZE=28
MENU_SPACING=55
MENU_BACKGROUND_IMAGE="images/backgrounds/mystic.png"
MENU_PRELOAD_MUSIC_FILES=["music/menu1.ogg", "music/menu2.ogg"]

# Inventory settings
INVENTORY_GRID_COLS=12
INVENTORY_GRID_ROWS=5
INVENTORY_BOX_SIZE=35
INVENTORY_BOX_SPACING=6
INVENTORY_BOX_BORDER_WIDTH=2
INVENTORY_BACKGROUND_IMAGE="images/ui/inventory.png"

# Dialog settings
DIALOG_AUTO_CLOSE_DEFAULT=False
DIALOG_AUTO_CLOSE_DURATION=0.5
DIALOG_KEY_ADVANCE="SPACE"
DIALOG_BOX_WIDTH_PERCENT=0.8
DIALOG_TEXT_FONT_SIZE=18

# Audio settings
AUDIO_MUSIC_VOLUME=0.3
AUDIO_SFX_VOLUME=0.9

# Camera settings
CAMERA_LERP_SPEED=0.15

# Asset settings
ASSETS_HANDLE="mystic_quest_assets"

# Game settings
INITIAL_MAP="starting_village.tmx"

Default Values¶

If you don't specify a setting, pedre.conf.settings uses these defaults:

# Window settings
SCREEN_WIDTH: int = 1280
SCREEN_HEIGHT: int = 720
WINDOW_TITLE: str = "Pedre Game"

# Menu settings
MENU_TITLE: str = "Pedre Game"
MENU_TITLE_SIZE: int = 48
MENU_OPTION_SIZE: int = 24
MENU_SPACING: int = 50
MENU_BACKGROUND_IMAGE: str = ""
MENU_PRELOAD_MUSIC_FILES: list[str] = []
MENU_TEXT_CONTINUE: str = "Continue"
MENU_TEXT_NEW_GAME: str = "New Game"
MENU_TEXT_SAVE_GAME: str = "Save Game"
MENU_TEXT_LOAD_GAME: str = "Load Game"
MENU_TEXT_EXIT: str = "Exit"

# Player settings
PLAYER_MOVEMENT_SPEED: float = 180.0
TILE_SIZE: int = 32
INTERACTION_PLUGIN_DISTANCE: int = 50
INTERACTION_KEY: str = "SPACE"
NPC_INTERACTION_DISTANCE: int = 50
PORTAL_INTERACTION_DISTANCE: int = 50
WAYPOINT_THRESHOLD: int = 2

# NPC settings
NPC_MOVEMENT_SPEED: float = 80.0
NPC_WAYPOINT_THRESHOLD: int = 2
NPC_INTERACTION_KEY: str = "SPACE"

# Asset settings
ASSETS_HANDLE: str = "game_assets"

# Game settings
INITIAL_MAP: str = "map.tmx"

# Scene settings
SCENE_TRANSITION_ALPHA: float = 0.0
SCENE_TRANSITION_SPEED: float = 3.0
SCENE_MAPS_FOLDER: str = "maps"
SCENE_TILEMAP_SCALING: float = 1.0
SCENE_COLLISION_LAYER_NAMES: list[str] = ["Walls", "Collision", "Objects", "Buildings"]

# Inventory settings
INVENTORY_GRID_COLS: int = 4
INVENTORY_GRID_ROWS: int = 3
INVENTORY_BOX_SIZE: int = 100
INVENTORY_BOX_SPACING: int = 15
INVENTORY_BOX_BORDER_WIDTH: int = 3
INVENTORY_BACKGROUND_IMAGE: str = ""
INVENTORY_MAX_SPACE: int = 12
INVENTORY_CAPACITY_FONT_SIZE: int = 14
INVENTORY_ITEMS_FILE: str = "data/inventory_items.json"
INVENTORY_KEY_TOGGLE: str = "I"
INVENTORY_KEY_VIEW: str = "V"
INVENTORY_KEY_CONSUME: str = "C"
INVENTORY_HINT_VIEW: str = "[V] View"
INVENTORY_HINT_CONSUME: str = "[C] Consume"
INVENTORY_HINT_FONT_SIZE: int = 12

# Dialog settings
DIALOG_AUTO_CLOSE_DEFAULT: bool = False
DIALOG_AUTO_CLOSE_DURATION: float = 0.5
DIALOG_CHAR_REVEAL_SPEED: int = 20
DIALOG_INSTANT_TEXT_DEFAULT: bool = False
DIALOG_KEY_ADVANCE: str = "SPACE"
DIALOG_SHOW_HELP: bool = True
DIALOG_SHOW_PAGINATION: bool = True
DIALOG_TEXT_NEXT_PAGE: str = "Press SPACE for next page"
DIALOG_TEXT_CLOSE: str = "Press SPACE to close"
DIALOG_TEXT_PAGE: str = "Page"
DIALOG_BOX_WIDTH_PERCENT: float = 0.75
DIALOG_BOX_MAX_WIDTH: int = 800
DIALOG_BOX_MIN_WIDTH: int = 400
DIALOG_BOX_HEIGHT_PERCENT: float = 0.25
DIALOG_BOX_MIN_HEIGHT: int = 150
DIALOG_VERTICAL_POSITION: float = 0.25
DIALOG_OVERLAY_ALPHA: int = 128
DIALOG_BORDER_WIDTH: int = 3
DIALOG_PADDING_HORIZONTAL: int = 20
DIALOG_PADDING_VERTICAL: int = 20
DIALOG_NPC_NAME_OFFSET: int = 30
DIALOG_FOOTER_OFFSET: int = 20
DIALOG_NPC_NAME_FONT_SIZE: int = 20
DIALOG_TEXT_FONT_SIZE: int = 16
DIALOG_INSTRUCTION_FONT_SIZE: int = 12
DIALOG_PAGE_INDICATOR_FONT_SIZE: int = 10

# Audio settings
AUDIO_MUSIC_VOLUME: float = 0.5
AUDIO_MUSIC_ENABLED: bool = True
AUDIO_SFX_VOLUME: float = 0.7
AUDIO_SFX_ENABLED: bool = True

# Camera settings
CAMERA_LERP_SPEED: float = 0.1

# Particle settings
PARTICLE_ENABLED: bool = True
PARTICLE_COLOR_HEARTS: tuple[int, int, int] = (255, 105, 180)
PARTICLE_COLOR_SPARKLES: tuple[int, int, int] = (255, 255, 100)
PARTICLE_COLOR_TRAIL: tuple[int, int, int] = (200, 200, 255)
PARTICLE_COLOR_BURST: tuple[int, int, int] = (255, 200, 0)

# Save plugin settings
SAVE_FOLDER: str = "saves"
SAVE_QUICK_SAVE_KEY: str = "F5"
SAVE_QUICK_LOAD_KEY: str = "F9"
SAVE_SFX_FILE: str = "save.wav"

See Also¶

• Getting Started Guide - Build your first RPG
• API Reference - API Reference