A lightweight web-based virtual tabletop for running tabletop RPG sessions. Built because I got tired of dealing with bloated VTTs that take forever to set up for simple encounters.

Everything in MiniVTT is a token - your maps, character pieces, monsters, items, whatever. Drag and drop images or videos onto the canvas and you're good to go. The DM gets full control over what players can see and interact with, and everything syncs in real-time across all connected clients.

The interface supports panning and zooming so players can focus on different parts of the scene. Scene switching is instant - click a scene in the DM panel and everyone transitions immediately. Most DM actions are either drag-and-drop or keyboard shortcuts to keep things fast.

1. Features
2. To-Do
3. Showcase
4. Installation
5. Usage
6. Project Structure
7. Built With
8. Security Disclaimer

Real-time sync - Token movements, scene changes, and music playback stay synchronized across all connected clients (DM and players).

Scene management - Create and switch between multiple scenes. Reorder them in the sidebar. Everyone sees the active scene instantly when you switch.

Drag-and-drop everything - Drop images or videos directly onto the canvas to create tokens. Drop audio files to add music tracks.

Token controls - Move, resize, rotate, and layer tokens. Toggle visibility to hide things from players. Give players permission to move specific tokens. All controlled by keyboard shortcuts or mouse interactions.

Hidden tokens - Keep tokens invisible to players until you're ready to reveal them. Good for surprises and fog of war.

Music manager - Upload and play background music. Volume controls sync across all clients.

Pan and zoom - Mouse wheel to zoom, middle-click to pan. Each player can navigate independently while viewing the same scene.

Keyboard shortcuts - Most common DM actions have hotkeys: hide tokens (H), toggle player movement (I), adjust z-index ([/]), duplicate (Ctrl+D), etc.

• Security for websockets and overall application
• Sortable music order in DM panel
• Better documented hotkeys
• Update/Improve DM interface & Multiselect
• Token Rotation
• Snap tokens to grid options

Live Synced Movement

DM Tools & Hidden Tokens

Music Manager

git clone https://github.com/SamsterJam/MiniVTT.git
cd MiniVTT

npm install

npm start

Server runs on port 3000 by default. Navigate to http://localhost:3000 to get started.

Share the URL with your players - one person connects as DM at /dm, everyone else connects as players at the root URL.

Navigate to http://your-host:3000/dm to access the DM interface where you can manage scenes, tokens, and music.

Players connect to http://your-host:3000 and get a simplified view that only shows what the DM reveals.

Click "Create Scene" in the DM panel, give it a name, and select it from the sidebar to make it active.

Drag and drop image or video files onto the canvas. Each file becomes a token you can manipulate.

• Click to select a token
• Drag with mouse or use arrow keys to move
• [ / ] - Move token down/up in the layer order (z-index)
• H - Hide token from players
• I - Toggle whether players can move this token
• Delete - Remove token
• Ctrl+D - Duplicate selected token

Drag audio files into the music drop area or use the Music Manager panel. Playback and volume sync across all clients.

• T - Toggle DM toolbar
• M - Toggle music panel
• Shift+D - Delete current scene (with confirmation)

.
├── app.js                  // Express setup
├── controllers
│   ├── musicController.js
│   ├── sceneController.js
│   └── uploadController.js
├── data
│   └── scenes             // Stored scene data
├── middlewares
│   ├── multerMusic.js     // Music upload handling
│   └── multerUpload.js    // Token upload handling
├── models
│   └── sceneModel.js      // Scene data model
├── public                 // Client-side files
│   ├── css
│   │   ├── dm.css
│   │   └── styles.css
│   ├── dm-login.html
│   ├── dm.html            // DM interface
│   ├── index.html         // Player interface
│   ├── js
│   │   ├── dm.js
│   │   ├── musicManager.js
│   │   ├── panZoomHandler.js
│   │   ├── player.js
│   │   ├── sceneManager.js
│   │   ├── sceneRenderer.js
│   │   ├── tokenManager.js
│   │   └── utils.js
│   ├── music              // Uploaded audio files
│   └── uploads            // Uploaded token images/videos
├── routes.js
├── server.js              // Server entry point
└── socketHandler.js       // WebSocket event handling

• Node.js - Server runtime
• Express - Web framework
• Socket.IO - Real-time communication
• Interact.js - Drag, drop, and resize
• SortableJS - Scene reordering
• Multer - File upload handling

This is an experimental project and hasn't been security audited. If you're running it on anything other than a trusted local network, you should know:

• WebSocket connections are not secured by default
• There's no authentication beyond the DM/player split
• File uploads aren't validated beyond basic type checking
• Anyone with network access can potentially connect

Only run this with people you trust, preferably on a local network. If you need to expose it to the internet, put it behind proper authentication and use HTTPS/WSS.

Use at your own risk.