Home

The purpose of this wiki entry is to assist game developers with adding new game pre-sets into the Card Games room on virtualtabletop.io, also known as VTT. This discussion assumes you have a basic familiarity with how to edit games using the advanced editor features of virtualtabletop.io. If not, you should familiarize yourself with the editor features and the basics of widget properties and routines using the VTT wiki and tutorials.

Adding a new game pre-set consists of the following basic steps:

1. In the Card Games room in the Public Library, view the room in the JSON Editor using ctrl-J.

2. Find a game pre-set (a blue and white widget off-screen to the left with an id gameIDx where "x" is a number from 0 to n). Try to find an existing widget that is as close as possible in rules and mechanics of an existing game. Avoid copying the Default widget if possible as there will be a lot of repetition and much to modify.

3. Copy the widget and give it a new text property that is the name of the game.

4. Edit the custom properties on the widget using the guidelines in Game Pre-Sets: Custom Properties.

5. If necessary, make modifications to routines on the widget using the guidelines in Game Pre-Sets: Custom Routines. However, you should not change anything on most of the existing widgets themselves as multiple games already rely on those routines. It is best to off-load any special requirements to the new game widget you are creating. There are already multiple off-ramps on existing buttons to call special routines. And if there is a routine that does not have an off-ramp you need, simply add the following into the JSON of the routine (and change "customNameRoutine" to whatever is appropriate):

  "var gameID = 'gameID' + ${PROPERTY preSet OF preSetsButton}",
  {
    "func": "IF",
    "condition": "${PROPERTY customNameRoutine OF $gameID}",
    "thenRoutine": [
      {
        "func": "CALL",
        "widget": "${gameID}",
        "routine": "customNameRoutine"
      }
    ]
  }

Then add the "customNameRoutine" to the new game type widget you created. There are many examples in this wiki and in the room itself.

6. If necessary, make new buttons or other widgets. If making multiple widgets that can all be used in the same game/group of games, it is best to have one widget be the parent if possible as that simplifies the code. You need to make the widget appear (for your game) and disappear (for all other games) by changing the scale to 1 (or some other positive non-0 value) or 0. You set the scale in your game using the displayArray object. For example, in Differenzler Jass, a dice is displayed at scale 1 using:

"displayArray": [
  [
    "suitDice",
    1
  ]
]

However, when you create new widgets using this method, you must also add a corresponding entry setting the scale to 0 in the "Default" game type widget.

The other way you can add widgets to a room is by adding a widget to the "Item" tray. This is a collection of shapes, symbols, numbers, etc. that are used to indicate various situations during game play. Read more about that at itemsButton.

7. If specialized player aids are appropriate, see the information in playerAidButton.

8. You should also add some instructions for how to use the room when players hover over the name of the game in the upper left using the hintText property.

9. If you need to modify the properties of existing cards or deck, or to create a new deck, see the information in Cards and Decks.

10. Make any necessary changes to the metadata of the room to reflect your new game.

11. When all changes are ready, be sure the room is set to the Default pre-set, all seats are empty, press the Recall & Shuffle button, delete the pile of cards, and finally the Reset Scores button.

12. When you have made the changes, either start a pull request in GitHub (if you know how to do that), or post in the VTT Discord in the public-library channel with a link to a room with your changes and a summary of what you did. If you made a change that should be noted in this wiki (for example, creating a new routine type on a game widget), please let me know.