rpg_map documentation

rpg_map

PyPI version Documentation Status

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:

  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.

    _images/1.png

  2. Add Padding and Convert to Pathfinding Grid Obstacles and map edges are padded and the image is converted into a binary map (1 = path, 0 = obstacle) for pathfinding.

    _images/2.png

  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.

    _images/3.png

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

    _images/4.png

  5. Divide into Grid Squares The image is divided into equal squares based on the grid_size parameter.

    _images/5.png

  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.

    _images/6.png

  7. Fill Transparent Areas Any remaining transparent pixels are filled with a background layer.

    _images/7.png

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

    _images/8.png

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:

Contents: