Getting Started with Arcade Tiled RPG¶

This guide will walk you through creating your first RPG game using the Arcade Tiled RPG framework. By the end, you'll have a simple game with a player character, an NPC, dialog system, and map transitions.

Prerequisites¶

Before starting, make sure you have:

• Python 3.14 or higher installed
• uv package manager
• Tiled Map Editor (free and open source)
• Basic knowledge of Python and object-oriented programming

Step 1: Project Setup¶

Install Pedre¶

# Create a new project directory
mkdir my-rpg
cd my-rpg

# Initialize uv project
uv init

# Install pedre package
uv add pedre

Example Project Structure¶

my-rpg/
├── assets/
│   ├── data/inventory-items.json
│   ├── maps/           # Tiled .tmx files
│   ├── images/
│   │   └── characters/ # Sprite sheets
│   ├── audio/
│   │   ├── music/      # Background music
│   │   └── sfx/        # Sound effects
│   ├── dialogs/        # NPC dialog JSON files
│   └── scripts/        # Event scripts JSON files
└── main.py             # Your game entry point

Step 2: Create Your First Map¶

In Tiled Map Editor¶

1. Create a new map:

   • File → New → New Map
   • Orientation: Orthogonal
   • Tile size: 32×32 pixels
   • Map size: 25×20 tiles (800×640 pixels)

2. Create a tileset:

   • Map → New Tileset
   • Name: "terrain"
   • Image: Use any 32×32 tileset (you can find free ones at itch.io)
   • Tile width/height: 32×32

3. Add required layers:

   Create these layers (Layer → New Layer):

   Tile Layers:

   • Floor - Ground tiles (draw your terrain here)
   • Walls - Wall tiles that block movement

   Object Layers:

   • Player - Player spawn point
   • NPCs - NPC spawn points
   • Portals - Map transition zones
   • Waypoints - Named positions for scripting

4. Draw your map:

   • Select the Floor layer
   • Use the tileset to paint ground tiles
   • Select the Walls layer
   • Paint walls around the perimeter

5. Add player spawn point:

   • Select the Player object layer
   • Insert → Point
   • Click somewhere in the center of your map (e.g., at 400, 320)
   • In the Properties panel, add custom properties:
     • sprite_sheet (string): images/characters/player.png
     • tile_size (int): 64
     • idle_up_frames (int): 4
     • idle_up_row (int): 0
     • idle_down_frames (int): 4
     • idle_down_row (int): 1
     • idle_right_frames (int): 4
     • idle_right_row (int): 2
     • walk_up_frames (int): 6
     • walk_up_row (int): 4
     • walk_down_frames (int): 6
     • walk_down_row (int): 5
     • walk_right_frames (int): 6
     • walk_right_row (int): 6
     • spawn_at_portal (bool): false (optional - if true, player spawns at portal waypoints instead of this position)

6. Save your map:

   • File → Save As
   • Save as assets/maps/village.tmx

Note: You'll need a player sprite sheet at assets/images/characters/player.png. The framework expects a sprite sheet with animation frames arranged in rows (idle, walk, etc.). Adjust the frame counts and row indices to match your sprite sheet layout.

Step 3: Create a Simple Game¶

Create a new file main.py in your project root:

"""Simple RPG game using Pedre framework."""

from pedre import run_game

if __name__ == "__main__":
    run_game()

Configure your game settings in settings.py:

SCREEN_WIDTH=1280,
SCREEN_HEIGHT=720,
WINDOW_TITLE="My First RPG",
INITIAL_MAP="village.tmx"

The scene name is automatically derived from the map filename (e.g., village.tmx → scene name "village").

Run Your Game¶

uv run python main.py

You should see your map with a player character! Use arrow keys to move around.

The run_game() function automatically:

• Creates the game window with your configured settings
• Loads the initial map from assets/maps/
• Sets up all game plugins (NPCs, dialogs, scripts, etc.)
• Starts the game loop

Step 4: Add an NPC¶

Create NPC Sprite Sheet¶

For this tutorial, you'll need a character sprite sheet. The framework is flexible and works with various sprite sheet layouts:

• Tile size: Any consistent size (16×16, 32×32, 64×64, etc.)
• Frames: Any number of frames per animation
• Rows: Animations arranged in horizontal rows
• Direction: Only right-facing animations needed (left-facing auto-generated by flipping)

You can create your own or download free sprites from OpenGameArt.org.

Save your NPC sprite sheet as assets/images/characters/merchant.png.

Example sprite sheet layout:

• Row 0: Idle animation frames (e.g., 4 frames)
• Row 1: Walk animation frames (e.g., 6 frames)
• Additional rows can contain other animations like interact or appear

Add NPC to Tiled Map¶

1. Open village.tmx in Tiled
2. Select the NPCs object layer
3. Insert → Point (or press I)
4. Click where you want the NPC to spawn

5. In the Properties panel for this object, add custom properties:

   • name (string): merchant
   • sprite_sheet (string): images/characters/merchant.png
   • tile_size (int): 32
   • idle_up_frames (int): 4
   • idle_up_row (int): 0
   • idle_down_frames (int): 4
   • idle_down_row (int): 1
   • idle_right_frames (int): 4
   • idle_right_row (int): 2
   • walk_up_frames (int): 6
   • walk_up_row (int): 4
   • walk_down_frames (int): 6
   • walk_down_row (int): 5
   • walk_right_frames (int): 6
   • walk_right_row (int): 6
   • spawn_at_portal (bool): false

6. Save the map

Note: The NPC will spawn at the exact x,y coordinates of the point object. The sprite_sheet property tells the framework which character sprite sheet to load, and the animation properties define how many frames and which rows to use for idle and walking animations.

Create NPC Dialog¶

Create assets/dialogs/village_dialogs.json:

{
  "merchant": {
    "0": {
      "name": "Merchant",
      "text": [
        "Hello, traveler!",
        "Welcome to our village.",
        "Feel free to look around."
      ]
    },
    "1": {
      "name": "Merchant",
      "text": [
        "Back again?",
        "I have nothing new to say."
      ]
    }
  }
}

Dialog Structure:

• Top-level keys are NPC names
• Second-level keys are dialog levels (conversation progress)
• name - NPC name displayed in dialog box
• text - Array of text strings (press SPACE to advance)

Test NPC Interaction¶

Run your game again:

uv run python main.py

Walk up to the NPC and press SPACE. You should see the dialog appear! Press SPACE to advance through pages.

Step 5: Add Interactive Scripts¶

Scripts let you trigger actions when events occur. Let's make the NPC give the player a sound effect after the first conversation.

Create Script File¶

Create assets/scripts/village_scripts.json:

{
  "first_meeting": {
    "scene": "village",
    "trigger": {
      "event": "dialog_closed",
      "npc": "merchant",
      "dialog_level": 0
    },
    "run_once": true,
    "actions": [
      {
        "type": "advance_dialog",
        "npc": "merchant"
      },
      {
        "type": "play_sfx",
        "file": "greeting.wav"
      }
    ]
  }
}

Script Breakdown:

• scene: Only runs in the "village" scene
• trigger.event: Trigger when dialog closes
• trigger.npc: Only if NPC is "merchant"
• trigger.dialog_level: Only at dialog level 0
• run_once: Only execute this script once
• actions: Sequence of actions to execute:
  1. Advance merchant's dialog level by 1 (so next conversation uses level 1 dialog)
  2. Play a sound effect

Add Sound Effect (Optional)¶

If you have a sound file, place it in assets/audio/sfx/greeting.wav. Otherwise, remove the play_sfx action from the script.

Test Scripts¶

Run the game and talk to the merchant. After closing the first dialog, the script will run and increment the merchant's dialog level. Talk to them again and you'll see the level 1 dialog!

Step 6: Add Map Transitions¶

Let's create a second map and a portal to travel between them.

Create Second Map¶

1. In Tiled, create a new map: assets/maps/forest.tmx
2. Use the same settings as before (32×32 tiles, 25×20 map)
3. Add the same layers: Floor, Walls, NPCs, Portals, Waypoints
4. Paint some terrain (make it look different from the village)
5. Select the Waypoints object layer
6. Insert → Point (or press I)
7. Click where you want the player to spawn when entering from village
8. In Properties panel, set Name: from_village
9. Save the map

Add Waypoint in Village Map¶

1. Open assets/maps/village.tmx
2. Select the Waypoints object layer (create it if it doesn't exist)
3. Insert → Point (or press I)
4. Click where you want the player to spawn when returning from forest
5. In Properties panel, set Name: from_forest
6. Save the map

Add Portal in Village Map¶

1. Still in assets/maps/village.tmx
2. Select the Portals object layer
3. Insert → Insert Rectangle
4. Draw a rectangle at the edge of your map (this is the portal zone)
5. In Properties panel:
   • Set Name: to_forest
   • Add custom property target_map (string): forest.tmx
   • Add custom property spawn_waypoint (string): from_village
6. Save the map

Add Return Portal in Forest Map¶

1. Open assets/maps/forest.tmx
2. Select the Portals object layer
3. Insert → Insert Rectangle
4. Draw a rectangle where you want the return portal
5. In Properties panel:
   • Set Name: to_village
   • Add custom property target_map (string): village.tmx
   • Add custom property spawn_waypoint (string): from_forest
6. Save the map

Test Portals¶

Run the game and walk into the portal rectangle. You should transition to the forest map! Walk into the return portal to go back.

The framework automatically:

• Detects portal collisions
• Saves your game state
• Loads the new map
• Spawns the player at the target waypoint

Step 7: Add Inventory Items¶

The inventory plugin allows you to define collectible items and track their acquisition. Items are defined in a JSON file and can be collected through interactive objects or scripts.

Define Inventory Items¶

Create assets/data/inventory_items.json to define all collectible items:

{
  "items": [
    {
      "id": "golden_key",
      "name": "Golden Key",
      "description": "A mysterious golden key found in the forest.",
      "icon_path": "images/items/golden_key_icon.png",
      "category": "key_items",
      "acquired": false
    },
    {
      "id": "forest_photo",
      "name": "Forest Photo",
      "description": "A beautiful photo of the forest clearing.",
      "icon_path": "images/photos/forest_thumb.png",
      "image_path": "images/photos/forest.jpg",
      "category": "photos",
      "acquired": false
    }
  ]
}

Item Fields:

• id (required): Unique identifier for the item
• name (required): Display name shown in inventory
• description (required): Item description text
• icon_path (optional): Path to inventory icon/thumbnail image
• image_path (optional): Path to full-size image for viewable items (e.g., photos, documents)
• category (optional): Category for organization (default: "general")
• acquired (optional): Whether item starts collected (default: false)

The inventory plugin automatically loads this file on startup. Items with image_path can be clicked in the inventory to view the full image.

Add Interactive Object in Tiled¶

1. Open assets/maps/forest.tmx
2. Create a new Object Layer named Interactive
3. Insert → Insert Rectangle
4. Draw a small rectangle where the item should be
5. In Properties panel:
   • Set Name: treasure_chest
   • Add custom property type (string): item
   • Add custom property item_name (string): golden_key
   • Add custom property message (string): You found a Golden Key!
6. Save the map

Create Collection Script¶

Add to assets/scripts/forest_scripts.json:

{
  "collect_key": {
    "scene": "forest",
    "trigger": {
      "event": "object_interacted",
      "object_name": "treasure_chest"
    },
    "run_once": true,
    "actions": [
      {
        "type": "dialog",
        "speaker": "Info",
        "text": ["You found a Golden Key!"]
      },
      {
        "type": "play_sfx",
        "file": "chest_open.wav"
      },
      {
        "type": "emit_particles",
        "particle_type": "sparkles",
        "interactive_object": "treasure_chest"
      }
    ]
  }
}

View Inventory¶

Run the game, go to the forest, and interact with the treasure chest (press SPACE near it). Then press I to open the inventory and see your collected item!

Step 8: Advanced: NPC Movement¶

Let's make an NPC walk to different locations.

Add Waypoints¶

1. Open assets/maps/village.tmx
2. Select the Waypoints object layer
3. Add three points:
   • Name: market_spot (somewhere in the map)
   • Name: well_spot (another location)
   • Name: home_spot (another location)
4. Save the map

Create Movement Script¶

Add to assets/scripts/village_scripts.json:

{
  "merchant_to_market": {
    "scene": "village",
    "trigger": {
      "event": "npc_movement_complete",
      "npc": "merchant",
      "waypoint": "merchant_start"
    },
    "actions": [
      {
        "type": "move_npc",
        "npcs": ["merchant"],
        "waypoint": "market_spot"
      }
    ]
  },
  "merchant_to_well": {
    "scene": "village",
    "trigger": {
      "event": "npc_movement_complete",
      "npc": "merchant",
      "waypoint": "market_spot"
    },
    "actions": [
      {
        "type": "move_npc",
        "npcs": ["merchant"],
        "waypoint": "well_spot"
      }
    ]
  },
  "merchant_to_home": {
    "scene": "village",
    "trigger": {
      "event": "npc_movement_complete",
      "npc": "merchant",
      "waypoint": "well_spot"
    },
    "actions": [
      {
        "type": "move_npc",
        "npcs": ["merchant"],
        "waypoint": "home_spot"
      }
    ]
  }
}

The NPC will walk between the three waypoints in a loop. Each script triggers when the NPC completes movement to the previous waypoint. The framework uses A* pathfinding to navigate around walls!

Next Steps¶

Congratulations! You've created your first RPG with:

• ✅ Custom Tiled maps
• ✅ Player movement and collision
• ✅ NPCs with dialog systems
• ✅ Event-driven scripting
• ✅ Map transitions with portals
• ✅ Collectible items and inventory
• ✅ NPC pathfinding and movement

Learn More¶

• Plugins Reference - Deep dive into each plugin
• Tiled Integration - Advanced Tiled features
• Scripting Guide - All available actions and events
• API Reference - Complete API documentation

Happy game dev! 🎮