dungeoneering logo

Virtual tabletop (VTT) for local, in-person RPG sessions

Download the latest version

Consider supporting this project :coffee:

Virtual tabletop (VTT) for local, in-person RPG sessions

dungeoneering is a free and slimmed down virtual tabletop (VTT) that can be used as a combat grid and as a dungeon exploration tool, made for local, in-person tabletop RPG sessions. It can load static and animated maps, has a dynamic lighting system, can be easily used with D&D 5e games, and more.

dungeoneering virtual tabletop screenshot

The main goal here is to make an application with all the basic features needed to run a tabletop RPG session. It should be easy to install, set up, and run and should have a minimalistic, intuitive, and hopefully pretty user interface.

Latest Version

The latest stable version , available for Windows, Linux and macOS, can be downloaded on this page. It’s also available, along with release notes, on the project’s releases page. There’s also a changelog with all notable changes made to this project.


  1. On this page or on the releases page, download the appropriate ZIP file for your operating system.
  2. Extract all files to a folder of your choice — Documents/dungeoneering for example.
  3. Run dungeoneering, dungeoneeringDm, or dungeoneeringPlayers depending on the screen configuration you plan to use. See Single and Dual Screen Modes below.


The application should work with the instructions above. If it doesn’t, create an issue, please.


The macOS ZIP is unsigned, meaning macOS will complain about it. Once you unzip it, right-click on each of the executables and choose Open. If asked, grant access to the Documents folder since that’s where dungeoneering saves its log files on macOS.


To run dungeoneering on Linux, you will need to install GStreamer v0.10. It’s an older version of GStreamer so it might be difficult to find the right packages to install. If you are using Ubuntu 18.04 or 20.04, this script should install everything you need. If you are using another Linux distribution, create an issue please and I will try to help.

How to Use It

Here’s a video showing how to create a scene from scratch in dungeoneering:

If you prefer a text description, read on.

To see how a scene looks like once it’s composed you can load one of the demo scenes that come with the application. Click on the load scene button ( load scene icon ) and choose a scene (*.json files) from the data/scenes folder.

To create a new scene follow the steps below. It might be better to do this when preparing an RPG session and not during it since your players might get bored while they wait.

  1. Click on the map setup button ( map setup icon ) and choose an image or video to use as a map.
  2. Click on the grid setup button ( grid setup icon ) and follow the on-screen instructions to set up a grid over the map you chose.
  3. Add player ( add player token icon ) and DM tokens ( add DM token icon ) using the corresponding buttons.
  4. Set up walls ( walls setup icon ) and doors ( doors setup icon ) using the corresponding buttons and following the on-screen instructions. Walls and doors are used to hide parts of the map and to block token light sources. With these elements in place, you will have a dynamic lighting system, where players will only see parts of the map depending on where their characters are and what they can see.
  5. If it’s a combat scene, first add tokens to the initiative order widget by right-clicking on them, then choosing Settings, and then clicking on the initiative button ( toggle initiative icon ). After that, enable the initiative order widget by clicking on the initiative order button ( initiative order icon ). In this widget, you can drag players and enemies to the position they should occupy based on the initiative they rolled.
  6. Save your scene using the save button ( save scene icon ) so you can load it when needed during your RPG sessions.

And that’s it! Now that you have set up your scene, players and DM will have a virtual tabletop where they can drag their tokens around the map; right click on them to add conditions, light sources, and sight types (e.g., darkvision); pan and zoom the map as needed; players can reveal hidden parts of the map with the dynamic lighting system; and hopefully with all that you and your group will have more fun in your RPG sessions. :)

Single and Dual Screen Modes

If you are going to use a single screen, to be shared by DM and players, run the executable called dungeoneering and you are all set.

If you want to use two separate screens connected to the same computer, one for the DM and another one to be shared by your players, run dungeoneeringDm first and once the application loads, run dungeoneeringPlayers. The two applications should work as a single virtual tabletop now. At startup they should connect to each other and once they do, a scene loaded in the DM app should load in the players’ app as well. After that any changes made in the scene should be replicated in both directions - a token moved by a player should move in the DM app, a condition applied by the DM should show up in the players’ app, same for any other changes made in the scene.

Remember to disable any network software, such as VPN or proxy, before running dungeoneering in dual-screen mode. In this mode, dungeoneering uses network ports to connect the two apps and in my tests, some network software caused problems and didn’t let the two apps connect properly.


dungeoneering code can be loaded, edited, and run directly in Processing IDE. Install Processing (v4.x), go to Sketch > Import Library > Manage Libraries and install “Video Library for Processing 4”. Then clone this repository, open the dungeoneering.pde file in Processing, and press Run (▶).

Bugs can be reported through the project’s issues page. Also, there’s a list of features to implement and known bugs to fix in the TODO list.

Known Issues


Copyright © 2019-2023 Luis Castilho

dungeoneering is licensed under the GPLv3. See LICENSE for details. dungeoneering also uses components from other open-source projects. Their code and license can be found at these links:

The icons used in dungeoneering were either released under a public-domain-like license (CC0) or are free to use with attribution (CC BY 3.0, CC BY 4.0). Icons created by the following authors were used: Andrew Nielsen, Tokka Elkholy, Sweet Farm, HeadsOfBirds, Mike Rowe, Denis, Yu luck, Patrick Morrison, Sergey Demushkin, Maxim Basinski, and AbtoCreative from Noun Project; Delapouite, Lorc, and sbed from Game-icons.net; and Freepik and Good Ware from Flaticon. Thanks for their awesome work and for releasing it under an open license.


There are a few demo scenes bundled with the application. The assets used in these scenes can be found at or created using the following links.


Thanks to my awesome RPG group that supported me in developing this application and was patient enough to playtest it in our sessions. :heart:

Claw token Gruk token Labard token Lander token Naven token Sora token