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

Contributing & Development

We welcome contributions and ideas! If you'd like to work on rpg_map locally, here's how to get started.

Set Up the Development Environment

1. Compile the Rust Extension Locally

   Use maturin to build and install the Rust extension module in your local Python environment:

   maturin develop --features "extension-module"

2. Generate Python Typings ( .pyi )

   The library includes a binary that auto-generates Python type stubs. Run it with:

   cargo run --bin stub_gen --features stubgen

3. Build the Documentation

   The documentation uses Sphinx and can be built locally as follows:

   python3 -venv env && source env/bin/activate
   cd docs
   pip3 install -r requirements.txt
   sphinx-apidoc -o source/ ../ -f
   make html

   The output will be available in the docs/build/html/ directory.

Additional Notes

• The Rust project uses pyo3 to create Python bindings — see Cargo.toml for feature flags and build options.
• Type hints are manually generated via the stub_gen tool, ensuring compatibility with type checkers and IDEs. Interestingly sphinx uses the docs defined in the Rust code though, the pyi file is only for IDE type hinting when using the library.

License

MIT