gTove - a virtual gaming tabletop

'Twas Brillig, and the slithy toves did gyre and gimble in the wabe.

This project is a lightweight web application to simulate a virtual tabletop. Multiple maps and standee-style miniatures can be placed on the tabletop, and everyone connected to the same tabletop can see them and move the miniatures around. To allow users to retain visiblity and ownership of their own data, make the hosting costs as low as possible and to allow other people to fork the project, Google Drive is used to store shared resources such as the images for miniatures and maps, and data for scenarios.

User Version

If you just want to use gTove, it can be accessed here:

https://illuminantgames.com/gtove

Browser Support

At the moment, I'm doing my development in Chrome, with occasional tests in Firefox. Other browsers may or may not work at this stage.

Discord Server

I've created a Discord Server for gTove where people can discuss the application, including discussing bugs (before raising then on Github) and making feature suggestions.

https://discord.gg/rZCCfR9

Basic User Guide

You can access gTove by going here: https://illuminantgames.com/gtove

Getting Started

After giving permission to the app to access your Google Drive (see Permissions below), it will create an empty folder structure at the top level of your Drive (which you can move elsewhere in your Drive if you like). You will be taken to a tutorial tabletop, which will guide you through the basics of navigating and using the app.

After you have finished with the tutorial, press the "Tabletops" button in the left-hand menu to go to the Tabletops browser. Press "Add Tabletop" to create your own tabletop, a shared virtual gaming space that can contain maps and miniatures. You will be given various configuration options for the tabletop, but you can simply "Save" the tabletop to proceed for now - you can return at any time later and Edit the tabletop to explore the tabletop configuration options.

You are the owner of any tabletops you create (making you the Game Master for that tabletop), and you can invite your players to one of your tabletops by sending them the URL that is shown in your browser address bar when you are viewing the tabletop yourself.

The contents of a tabletop can only be changed when the GM is connected, but players can look at the current tabletop by going to the URL at any time. Players accessing an existing tabletop are not prompted by gTove to create the empty folder structure in their Drive, but they must still give gTove permission to access their Drive.

When you use gTove, all of its configuration files, images and directories are created in your Drive, and nowhere else. There is no central gTove server which stores any information... everything is driven from the gTove files saved on the Drive of the currently signed in user.

Viewing the Tabletop

Once you create and select a new tabletop, you will see an empty grid (since you have no maps loaded), and various controls on the left. These controls allow you to toggle various tabletop-wide options like Grid Snap (whether minis snap to the map's grid or not) and Edit Fog (which allows you to cover up sections of the map with a "fog of war", hiding the map underneath from your players), as well as allowing you to switch between "GM view" (where everything is visible) and "player view" (where fog of war is opaque and hidden maps and miniatures are not shown, so you can see what your players will see.)

The left-hand menu can be closed by clicking the × symbol, and revealed again by clicking the ☰ menu symbol.

Adding Maps and Miniatures

To add maps and miniatures to the tabletop, click the buttons marked "Maps" or "Minis" in the left-hand menu. This will open a file browser of the gTove folders on your Drive, where you can upload images and configure how they will appear on to tabletop.

Click "Upload" to add your first image. You can multi-select files when uploading if you want to import many images into gTove at once. You can also paste images that you have copied to your clipboard directly into the file browser for maps and miniatures, but you cannot yet drag-and-drop files.

When an image file is first uploaded, it will be marked as "NEW", and gTove will require you to configure the image before using it on the tabletop.

• For maps, you can set its name, and align a grid over the map so gTove knows what scale to display the map at. Note that you cannot hide parts of the map from players using Fog of War unless the map has a grid defined. You can optionally have gTove show the grid overlay when on the tabletop, if you have a map image which does not have a grid overlay as part of the image itself.
• For miniatures, you can set its name, and also see a preview of what the miniature will look like on the tabletop. The left-hand or top panel shows how the image will be framed in the standee outline - pan and zoom the frame to adjust how much of the image will be visible. The camera in the 3D view can be moved using the gestures described in the "Interacting with the Tabletop" section below, and if you rotate the camera to look top-down, you will switch to configuring how the image will be framed when in flat, top-down mode.

Save the configured version of your image, and you will return to the file browser. Click or tap a map or miniature image that you have configured to drop it on your tabletop.

Note that you should not save images directly into the gTove folders using the Google Drive interface, as gTove will not have permission to modify them.

Interacting with the Tabletop

Back on the tabletop, the gestures or mouse interactions are consistent across the app:

• Single finger tap or left mouse click to select or bring up a menu relating to the thing you clicked or tapped. The options available depend on whether you own the tabletop or not.
  • The miniature menu includes options like making the miniature lie down/stand up, editing its name label, changing its scale, duplicating it or removing it from the tabletop.
  • The map menu includes options such as covering or uncovering the whole map with fog of war (as long as the map has a grid defined for it), repositioning it, or removing it from the tabletop.
  • For the GM, both miniature and map menus include the option to reveal the map or miniature to the players, or to hide a revealed map or miniature. Newly added miniatures are automatically hidden from players, as are newly added maps with no grid defined. If a newly added map has a grid, it is not hidden from players, but is instead completely covered by Fog of War.
• Left click and drag, or drag with a single finger, to pan.
  • Panning a miniature will move it around on the map. Its base will snap vertically to whatever map you drag over, so you can drag it between maps at different elevations if you like.
  • Panning a map or on the background will pan the camera around.
  • If you are repositioning a map, panning will move the map on the tabletop.
• Right click and drag, control-left click and drag, or rotate with two fingers, to rotate.
  • Rotating a miniature will rotate it on its base.
  • Rotating a map or on the background will orbit the camera around the point it's currently looking at, and also elevate between an oblique view or looking top-down on the tabletop.
  • If you are repositioning a map, rotating will rotate it around its centre.
• Middle click and drag, shift-left click and drag (for those without a three-button mouse), or two finger pinch, to zoom.
  • Zooming a miniature will elevate it above or below its base, to represent flying, burrowing or swimming creatures.
  • Zooming a miniature while scaling it will adjust its size.
  • Zooming a map or on the background will cause the camera to zoom in and out.
  • If you are repositioning a map, zooming it will change its elevation.

Connected Users

The Google avatar of the signed in user is visible in the top-right corner. You can click this icon to open a connection menu, which contains a button to sign out of gTove.

If other users connect to the tabletop, a counter will appear on this avatar showing how many users are connected. If the GM is connected, the counter will be green; otherwise, it is orange. Expanding the connection menu allows you to see who is connected.

Building gTove from Source

Note: You don't have to build gTove yourself to use it - simply go to https://illuminantgames.com/gtove and start using it!

If you want to contribute to gTove's development though, you may want to check out the repository and start working with it locally. gTove is a react typescript application, built with create-react-app and then manually converted to typescript (because I didn't use --scripts-version=react-scripts-ts when I first ran create-react-app).

• You need Node.js installed. I'm currently running version 12.16.1
• Check out the repository using your preferred git tool.
• Install yarn: npm install -g yarn (I use yarn, and thus the project has a yarn.lock file rather than a package.lock)
• Change into the top level gTove directory: cd gTove
• Run yarn install
• After dependencies are installed, you can start a development server by running yarn start.

Styling

At this stage, the app is quite minimally styled. Many UI elements are just default HTML buttons, laid out in columns. Once the major functionality is implemented, I'll try get someone who's good at graphic design to come up with a style for the app and add the styling. For now, the emphasis is on functionality.

That said, there are certain user interactions which I'm very happy with. I like the unified mouse/gesture interface with the virtual tabletop, and