Editing JSON - ArnoldSmith86/virtualtabletop GitHub Wiki

If you want step-by-step instructions for how to use Edit Mode, look in the subsections of this page on the sidebar to the right. Also check out the video on our YouTube channel for an Edit Mode Guided Tour at https://www.youtube.com/watch?v=xmdMTWuRO-E. Otherwise, this page contains just a brief overview.

There are two primary ways to enter and modify the JSON for your game: by pressing Ctrl-J or you can click on the blue and white icon on the toolbar that looks like a hammer and wrench and says "Edit Mode." A major advantage of this mode of editing is that changes you make are live and instantaneous in the room.

Edit Mode provides the ability to directly edit the JSON defining all the game elements in a live visual environment. You can add, remove, or edit widgets, execute game elements, and examine debug information that can help you diagnose problems. The images on this page show a mix of light mode and dark mode screen shots.

Overview

From the game screens, pressing either Edit Mode or Ctrl-J will enter the Edit Mode. (Another Ctrl-J will return you to normal game mode as will pressing the X in the blue toolbar at the top.) You will be presented with a screen similar to this (note that the content in red in this graphic is a guide to the sections below describing the different areas, and does not appear in the actual editor): Overview

The room with the Game Area takes up the left-hand portion of the screen. Above it is the Top Toolbar with a blue background and white icons. To its right is the Text Display Area, which is currently empty. Following that is a column of icons and clickable buttons with blue and white text called the Widget Buttons area. This is only displayed when showing JSON. On the far right is the Menu. Each of these areas is described below or, for the individual Menu buttons, in the other subsections of Editing JSON.

When zoomed in, hold the Spacebar and drag with the primary mouse button to pan the Game Area. You can start the drag anywhere, including over a movable widget; the widget will not move and a selection rectangle will not be created.

Top Toolbar

Across the top of the screen are icons that perform a variety of functions. If an icon is greyed out, it is currently not available (most likely due to the widgets you have selected or not selected). The functions of the icons are described below in icon order from left to right.

Start with a new blank room. This will instantly delete everything in the room and create a new blank room. You can undo this by using the History menu, but only if you use the History menu before you leave the room or refresh the browser.

Save changes to the currently loaded game. This feature will open a submenu with several options that allow you to make changes to the game without leaving Edit Mode and going to the Game Shelf:

Save to Active Variant. This immediately saves the game to the current variant. If a game has not yet been saved, this option is not available. This option is also not available for Public Library games.
Save as New Variant (of ...). The button name displays the name of the game you are currently working on. This immediately creates a new variant in that game. If a game has not yet been saved, this option is not available. This option is also not available for Public Library games.
Save as New Game. This button prompts you for the name of the new game and then saves it to the Game Shelf.
Quick Download. This button will download the JSON, and only the JSON and not the assets, of the current variant. This is NOT the method you should use for saving offline versions of games. This is a simple function for limited purposes.
Quick Save. This button will create (if it does not already exist) a saved version called "Quicksave". The variant name will be the date and time (UTC) of the save. Each additional press of the button will create a new variant with the new date and time.
Auto-save every 5 minutes. If checked, this button does the same thing the Quick Save button does, but does so automatically every 5 minutes while you are in the room AND whenever you close out of the editor. This can create many, many Quicksave variants.

Toggle between light and dark mode in the editor. As the description suggests, toggles the background color of the JSON editor portion of the room (on the right) from light to dark.

Toggle fullscreen mode. Does exactly what it says.

Toggles grid lines on and off. When on, you are prompted to choose a pixel size (default is 25px), a color (default is gray), and whether to show thicker lines that divide the room into quarters, thirds, or fifths (default is quarters). When on, the grid lines are also displayed when not in edit mode. All lines are only visible to the user that turned them on and not other players. Grid lines are not visible over a background or other solid widgets. While editing, you can change the opacity of the background/widget to allow the lines to show through or set the layer to -11 or lower.

Close the editor and return to playing the game. Does exactly what it says. Pressing Ctrl-J does the same thing.

Undo the last change. Works in conjunction with the History menu to go back one change for each press of the button (or the hotkey z). It undoes virtually everything, including dragging widgets manually and the routine operations of buttons. The only way to redo something you just undid, however, is to use the History menu.

Toggle between drag to move and drag to select. When you first enter Edit Mode, the primary mouse button (usually the left), continues to operate in "game" mode. This means that you use the primary mouse button to click on buttons in the Game Area to interact with those widgets as if you were not in Edit Mode. The secondary mouse button (usually the right), is how you select and interact with the widgets in Edit Mode. This icon toggles that behavior so the primary and secondary mouse buttons swap roles. If there is a third mouse button/clickable scroll button, clicking it always acts in game mode.

Toggle between the normal view and a zoomed out view that allows you to see widgets that are hidden off screen. In many rooms, some widgets are maintained offscreen and out of the view of the players. This button zooms out to display an expanded area outside of the regular playing surface. By setting sufficiently large or small values of x/y in individual widgets, they can be located even outside of the area visible using the zoomed out view.

Add a new widget. Opens a pop-up screen to allow you to add a new widget (same as pressing the hotkey a).

Delete the selected widgets. All currently selected widgets will be deleted (same as pressing the hotkey Delete).

Align the selected widgets to the left. All selected widgets will be aligned to the lowest x value of the widgets (same as pressing the hotkey ArrowLeft).

Align the selected widgets to the center. All selected widgets will be aligned to the average x value of the widgets.

Align the selected widgets to the right. All selected widgets will be aligned to the highest x value of the widgets (same as pressing the hotkey ArrowRight).

Align the selected widgets to the top. All selected widgets will be aligned to the lowest y value of the widgets (same as pressing the hotkey ArrowUp).

Align the selected widgets to the center. All selected widgets will be aligned to the average y value of the widgets.

Align the selected widgets to the bottom. All selected widgets will be aligned to the highest y value of the widgets (same as pressing the hotkey ArrowDown).

Equalize the spacing between the selected widgets horizontally (same as pressing the hotkey h). Use this to create an even horizontal distribution across the selected widgets. This uses the far left and the far right widgets as anchor points that will not be moved.

Equalize the spacing between the selected widgets vertically (same as pressing the hotkey v). Use this to create an even vertical distribution across the selected widgets. This uses the topmost and the bottommost widgets as anchor points that will not be moved.

Change the layering of the selected widgets so that the bottom and right most widgets are on top. You can optionally use this when duplicating widgets. (Depending on the direction of the duplication, widgets may otherwise be hidden because of the widget layering. This changes the z-value so the bottom and right most widgets are on top.)

Group the selected widgets by inserting an invisible parent widget. Each of the selected widgets will become the child (in the same relative position) of a newly created parent widget.

Open tutorials

Open wiki

Feedback. Opens the same feedback window as the Feedback button on the game toolbar, so you can send a suggestion or a bug report without leaving Edit Mode (see Troubleshooting).

Menu (Right Sidebar)

When clicking on a Menu button in the Right Sidebar, the Text Area will be filled with information based on which button you press. If you Ctrl-Shift-click (on PC; Mac not tested), the menu item you select will display on top of and cover the game area. This is a good way to view very detailed JSON or debug information. Also, if you click and hold and drag the menu label to the left, you will see dotted red lines dividing the Text Area into 4 separate areas. You can drop the menu label being dragged into one of those areas and customize your workspace. For example, in the image below, the JSON (including the blue and white buttons that are part of the JSON Editor) are in the top left, debug output in the top right, widget tree in the bottom left, and history in the bottom right. Finally, the size of the Text Area in relation to the Game Area can be changed by placing the mouse over the right edge of the visible room Game Area until the cursor changes to a double-ended arrow. Then drag that dividing line to resize the Game Area.

Each of those buttons has its own subsection listed under this page in the sidebar:

Edit Widgets — build decks and cards, and change a widget's properties without editing JSON directly.
History — review the changes made in the room and return it to an earlier state.
JSON — the JSON editor itself. Because it is the heart of Edit Mode, that subsection also describes the overall screen layout, the Top Toolbar, the Menu, how widgets are selected, and the Widget Toolbar.
Widgets — add widgets to the room and keep a personal collection of frequently used widgets.
Debug — the execution details of recently activated routines and the game validation table.
Assets — download and compress the images used by the game.
Toolbox — copy widgets between rooms, and search and replace.
Game Settings — board size and shape, legacy modes, UI settings, and Global Room CSS.

Alternative Editing Methods

You can edit the JSON in an offline text editor, or some programming developer tool that color codes various features. This would be useful, for example, in cutting and pasting significant amounts of code between JSON files or for mass searching and replacing of properties or names. You can get access to the JSON in by unzipping a downloaded .vtt file using a zip extractor; the JSON file will be extracted into your current directory.
If the game is already loaded into a room, you can dynamically extract the JSON from the room using curl:

curl https://virtualtabletop.io/state/fpxb > ~/json.txt

where fpxb is the room ID. After editing, you can return it to the room using

curl -X PUT -H "Content-Type: application/json" --data-binary @json.txt https://virtualtabletop.io/state/fpxb

(Note that if you use curl, you have to save the room in order to have your changes to the JSON persist.)

You can use a VSCode extension that has limited documentation and support at https://github.com/ArnoldSmith86/virtualtabletop-misc/tree/main/vscode-extension.