Dynamic Map Renderer

Description

The Dynamic Map Renderer is a web-based application designed for tabletop roleplaying games (TTRPGs). It transforms static map images into dynamic displays, allowing a Game Master (GM) to control the map appearance, apply visual effects (filters), and manage the view presented to players in real-time. This initial release focuses on image-based maps with a retro sci-fi aesthetic - good for Mothership, Traveller, or the Aliens RPG.

Quick Notes

This is the second release and includes the masking/fog of war functionality. I am looking for feedback and suggestions. Much of this was inspired by the amazing work by the Quadra team who created the Tannhauser Remote Desktop for their Warped Beyond Recognition adventure. I just wanted to make a GM-driven client-server tool that would work to spruce up an otherwise bland map.

I grabbed a couple of example maps to show it working. Both seemed pretty widely distributed across various websites - so I don't anticipate anyone will mind. That said, I did not seek permission in advance - so I am happy to remove them if requested!

• USS Pharoah: https://www.failuretolerated.com/mothership-ship-creation-sheet
• The Alexis: from Dead Planet: https://www.drivethrurpg.com/en/product/484228/mothership-dead-planet

This project has been "Vibe coded" - a dirty word for many. This means that while I directed the process, the code itself was primarily generated by Google's Gemini 2.5 Pro (experimental). I claim no ownership over the program or code here and anyone can use it for any purpose without permission. If you use it, letting me know what for would be cool (just for personal interest).

Current Features (v0.2.0)

• Image Map Support: Load and display .png, .jpg, .jpeg, and .webp map files.
• GM Control Interface: Web interface for the GM to manage the session.
• Player View: Separate web view for players, displaying the GM-controlled map.
• Visual Filters: Apply pre-defined visual filters to the map image:
  • Retro Sci-Fi Green [updated in v0.2]
  • Retro Sci-Fi Amber [updated in v0.2]
  • None (does allow inverting image)
• Player View Control: GM can pan (Center X/Y) and zoom (Scale) the view shown to players.
• Auto Saving/Loading: In v0.2 map configurations are auto-saved with each change (selected filter, parameters, view state) per map image. Configs are stored as JSON files in the ./configs/ directory.
• Masking/Fog Of War: GM can hide areas of the map from the players and quickly show them if needed. [new in v0.2]
• Help: Some help to get started shown as the default map on load [new in v0.2]
• Real-time Updates: Player views update instantly via WebSockets (Socket.IO) when the GM makes changes.

Setup Instructions

You will need a working Python 3.xx environment to use this. Further dependencies installed in step 3. You can skip Step 1 and 2 if you just want to download the "Code -> Download ZIP file".

1. Clone the Repository:

   git clone https://github.com/FrunkQ/dynamic-map-renderer.git
   cd dynamic-map-renderer

2. Create & Activate Virtual Environment (Optional but Recommended): While it might work from your existing Python environment, using a virtual environment is recommended to manage dependencies.

   # For Linux/macOS
   python3 -m venv venv
   source venv/bin/activate

   # For Windows
   python -m venv venv
   .\venv\Scripts\activate

3. Install Dependencies:

   pip install -r requirements.txt

   (Requires Python 3.x)
4. Run the Application:

   python app.py

   The server will start, typically on http://127.0.0.1:5000/.

Usage

1. GM View: Open http://127.0.0.1:5000/ in your browser.

   • Upload map images using the "Upload New Map Image" section.
   • Select a map from the "Select Map" dropdown.
   • Choose a filter from the "Select Filter" dropdown.
   • Adjust filter parameters using the sliders/controls that appear.
   • Adjust the Player View using the "Center X/Y" and "Scale" sliders.
   • Mask pasrts of the map by drawing polygons on the map

2. Player View: Share the "Player URL" displayed at the bottom of the GM controls panel with your players. For this version, the URL will always be: http://127.0.0.1:5000/player?session=my-game You can run this in your room on other machines but I tend to use locally on one machine with the player view on a different screen. I made it client/server to be more flexible going forward - other clients will have to use http://<server ip>:5000/player?session=my-game

Directory Structure

• app.py: Main Flask application and WebSocket server.
• requirements.txt: Python dependencies.
• templates/: HTML files for GM (index.html) and Player (player.html) views.
• static/: CSS (style.css) and JavaScript (gm.js, player.js) files.
• maps/: Directory to store map image files. (Create if it doesn't exist or if excluded by .gitignore).
• configs/: Directory to store saved map configuration JSON files. (Create if it doesn't exist or if excluded by .gitignore).
• filters/: Contains subdirectories for each filter, holding config.json and shader (.glsl) files.

Known Issues / Limitations (v0.2.0)

• Hardcoded Session ID: Player sessions currently must use the hardcoded session ID my-game. Custom session IDs are not yet supported.
• No User Management: Assumes a single GM and potentially multiple players connected to the same session.

Future Plans

The following features are planned for future releases:

1. Marker Functionality: Allow placing and managing visual markers/icons/tokens on the map.
2. Sound Features: Integrate sound effects or ambient audio tied to the map or markers (e.g., an Aliens-style motion tracker where sound varies depending upon player location).
3. Player Window Transitions: Add visual transitions (e.g., fades) when the map or filter changes in the player view.
4. User-Defined Session IDs: Allow the GM to create custom, memorable session IDs.

---