rpg_map documentation

rpg_map

A fast, zero-dependency Python library for visualizing exploration and movement across large pixel-based maps. Built in Rust for speed and efficiency, rpg_map is perfect for turn-based or real-time RPGs, strategy games, and D&D-style map reveals.

Key Features

• Hides unexplored areas of the map

• Reveals areas as they’re explored or passed through

• Draws travel paths using A* pathfinding

• Fast and lightweight with zero Python dependencies

• Operates directly on pixel data

• Customizable visual styles and highlight zones

• Includes examples using static image processing and Pygame

Install

Install via pip:

pip install rpg-map

Documentation

Full documentation and examples available at: https://rpg-map.readthedocs.io/

How It Works

The library uses step-by-step image processing to reveal and annotate the map. Here’s an overview of the process:

Code:

This is the code which was used to generate the final result of the example steps below:

from rpg_map import Travel, Map, MapType, PathStyle, PathProgressDisplayType, PathDisplayType
from PIL import Image

LOCAL_DIR = "../test_assets/map.png"
BACKGROUND_DIR = "../test_assets/background.png"
GRID_SIZE = 20
START, END = (198, 390), (172, 223)
START_X, START_Y = START

image = Image.open(LOCAL_DIR).convert("RGBA")
# get image bytes
image_bytes = list(image.tobytes())
background = Image.open(BACKGROUND_DIR).convert("RGBA")
# get background bytes
background_bytes = list(background.tobytes())
map = Map(
   image_bytes,
   image.size[0],
   image.size[1],
   GRID_SIZE,
   MapType.Limited,
   obstacles=[[(160, 240), (134, 253), (234, 257), (208, 239)]],
)

travel = Travel(map, START, END)
path_bits =  Map.draw_background(
   map.with_dot(START_X, START_Y, (255, 0, 0, 255), 4).draw_path(
      travel,
      1.0,
      2,
      PathStyle.DottedWithOutline((255, 0, 0, 255), (255, 255, 255, 255)),
   ),
   background_bytes
)

# Display the image
image = Image.frombytes("RGBA", (image.width, image.height), path_bits)
image.show()

---

Steps:

1. Draw Obstacles

   The Map class accepts an obstacles parameter which allows you to define N-sided polygons. These are rendered onto the map as solid barriers.

   

2. Add Padding and Convert to Pathfinding Grid

   Obstacles and map edges are padded and the image is converted into a binary map (0 = path, 1 = obstacle) for pathfinding.

   

3. Pathfinding with A*

   The library uses the A* algorithm to find the shortest path from point A to point B. The path is drawn on the map using a customizable style.

   

4. Draw Dots

   Optional dots can be placed on the map (e.g., for points of interest, the player, markers).

   

5. Divide into Grid Squares

   The image is divided into equal squares based on the grid_size parameter.

   

6. Reveal Explored Areas

   A mask overlays the map. Areas near the travel path or manually unlocked via Map.unlock_point are revealed in circular zones.

   

7. Fill Transparent Areas

   Any remaining transparent pixels are filled with a background layer.

   

8. Final Map Output

   The completed map shows explored areas, paths, markers, and hidden regions yet to be discovered.

   

Advanced Features

• You can define special grid points where the reveal radius is larger — perfect for cities or key landmarks.

• The library supports tons of styles for different themes and usecases.

  

Examples

Check out these demos:

• examples/static_poc.py – Generate one image from your code

• examples/pygame_poc – Interactively do pathfinding to wherever you click

• examples/readme.py – The code used to generate the final image in the steps breakdown in this README

Contents:

• rpg_map package
  • Module contents