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/
│   │   ├── content/         # Content registry JSON files
│   │   │   ├── sprites.json
│   │   │   ├── npcs.json
│   │   │   ├── items.json
│   │   │   └── dialogs/     # NPC dialog files, one per scene
│   │   │       └── village.json
│   │   └── scripts/         # Event scripts JSON files
│   ├── maps/                # Tiled .tmx files
│   ├── images/
│   │   └── characters/      # Sprite sheets
│   └── audio/
│       ├── music/           # Background music
│       └── sfx/             # Sound effects
└── 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)
   • No extra Tiled properties are required — the player sprite is defined in sprites.json (see Step 3)

6. Save your map:

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

Step 3: Create a Simple Game¶

Define Your Player Sprite¶

Create assets/data/content/sprites.json to define your player's animations:

{
  "player": {
    "sprite_sheet": "images/characters/player.png",
    "frame_width": 64,
    "frame_height": 64,
    "states": {
      "idle": {
        "directional": true,
        "loop": true,
        "priority": 0,
        "directions": {
          "down":  {"frames": 4, "row": 0},
          "up":    {"frames": 4, "row": 1},
          "right": {"frames": 4, "row": 2}
        }
      },
      "walk": {
        "directional": true,
        "loop": true,
        "priority": 1,
        "directions": {
          "down":  {"frames": 6, "row": 3},
          "up":    {"frames": 6, "row": 4},
          "right": {"frames": 6, "row": 5}
        }
      }
    }
  }
}

Adjust frame_width, frame_height, frame counts, and row indices to match your sprite sheet. Left-facing animations are auto-generated by flipping right-facing frames.

Note: You'll need a player sprite sheet at assets/images/characters/player.png. See Sprites API for the full format.

Create the Game Entry Point¶

Create main.py:

"""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/
• Loads content registry files from assets/data/content/
• Sets up all game plugins (NPCs, dialogs, scripts, etc.)
• Starts the game loop

Step 4: Add an NPC¶

Define the NPC in the Content Registry¶

NPC appearance is configured in JSON files. You'll need a character sprite sheet — save it as assets/images/characters/merchant.png. You can find free sprites at OpenGameArt.org.

Add the merchant's sprite definition to assets/data/content/sprites.json:

{
  "player": { ... },
  "merchant_sprite": {
    "sprite_sheet": "images/characters/merchant.png",
    "frame_width": 64,
    "frame_height": 64,
    "states": {
      "idle": {
        "directional": true,
        "loop": true,
        "priority": 0,
        "directions": {
          "down":  {"frames": 4, "row": 0},
          "up":    {"frames": 4, "row": 1},
          "right": {"frames": 4, "row": 2}
        }
      },
      "walk": {
        "directional": true,
        "loop": true,
        "priority": 1,
        "directions": {
          "down":  {"frames": 6, "row": 3},
          "up":    {"frames": 6, "row": 4},
          "right": {"frames": 6, "row": 5}
        }
      }
    }
  }
}

Create assets/data/content/npcs.json to link the NPC name to its sprite:

{
  "merchant": {
    "sprite_id": "merchant_sprite"
  }
}

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, add one custom property:
   • name (string): merchant
6. Save the map

The NPC spawns at the point's position. All appearance config lives in the JSON files above.

Create NPC Dialog¶

Create assets/data/content/dialogs/village.json:

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

Dialog Structure:

• Keys follow the pattern "{npc_name}/{level}" (conversation progress)
• name - NPC name displayed in dialog box
• text - Array of text strings (press SPACE to advance)
• The scene name comes from the filename stem (village.json → scene "village")

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/data/scripts/village.json:

{
  "first_meeting": {
    "scene": "village",
    "trigger": {
      "event": "dialog_closed",
      "npc": "merchant",
      "dialog_level": 0
    },
    "run_once": true,
    "actions": [
      {
        "name": "advance_dialog",
        "npc": "merchant"
      },
      {
        "name": "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
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
6. Save the map

Wire Up Portals with Scripts¶

Portal transitions are handled through scripts, not Tiled properties. Add to assets/data/scripts/village.json:

{
  "to_forest_portal": {
    "scene": "village",
    "trigger": {"event": "portal_entered", "portal": "to_forest"},
    "actions": [
      {"name": "change_scene", "target_map": "forest.tmx", "spawn_waypoint": "from_village"}
    ]
  }
}

Create assets/data/scripts/forest.json:

{
  "to_village_portal": {
    "scene": "forest",
    "trigger": {"event": "portal_entered", "portal": "to_village"},
    "actions": [
      {"name": "change_scene", "target_map": "village.tmx", "spawn_waypoint": "from_forest"}
    ]
  }
}

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
• Fires the portal_entered event
• Executes the matching script's change_scene action
• 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/content/items.json to define all collectible items. Keys are item IDs:

{
  "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
  },
  "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:

• 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 content registry loads this file automatically 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/data/scripts/forest.json:

{
  "collect_key": {
    "scene": "forest",
    "trigger": {
      "event": "object_interacted",
      "object_name": "treasure_chest"
    },
    "run_once": true,
    "actions": [
      {
        "name": "dialog",
        "speaker": "Info",
        "text": ["You found a Golden Key!"]
      },
      {
        "name": "play_sfx",
        "file": "chest_open.wav"
      },
      {
        "name": "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/data/scripts/village.json:

{
  "merchant_to_market": {
    "scene": "village",
    "trigger": {
      "event": "npc_movement_complete",
      "npc": "merchant",
      "waypoint": "merchant_start"
    },
    "actions": [
      {
        "name": "move_npc",
        "npcs": ["merchant"],
        "waypoint": "market_spot"
      }
    ]
  },
  "merchant_to_well": {
    "scene": "village",
    "trigger": {
      "event": "npc_movement_complete",
      "npc": "merchant",
      "waypoint": "market_spot"
    },
    "actions": [
      {
        "name": "move_npc",
        "npcs": ["merchant"],
        "waypoint": "well_spot"
      }
    ]
  },
  "merchant_to_home": {
    "scene": "village",
    "trigger": {
      "event": "npc_movement_complete",
      "npc": "merchant",
      "waypoint": "well_spot"
    },
    "actions": [
      {
        "name": "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! 🎮