Probability editor help

Want to create your own meeples & tokens? Try Woodcutter.

Want to import print & play PDFs? Try Cardcutter.

Modding basics

Probability games are a zip file with a "probability.json" file containing the board game, a collection of 3D models, and a "package.json" file. The zip files are uploaded to https://mod.io/g/probability, and appear in the catalog. An example can be found here.

The editor

The editor main window shows the current state of the live game. The JSON code describes the game pieces and their positions in relation to each other. You can modify the actively-running game, and can export a game file.

Pieces

Each physical item in the game has a JSON representation. For example, a chess piece on a chessboard:

{
    "probability": "2024-01-01",
    "templates": {},
    "children": [
        {
            "locked": true,
            "name": "Chess Board",
            "position": [0, 0, 0],
            "rotation": [0, 0, 0],
            "scale": [35, 35, 35],
            "src": "https://probability.nz/chess/Chess_Board.glb",
            "children": [
                {
                    "name": "White Rook 1",
                    "position": [0, 0.015, 0],
                    "rotation": [0, 0, 0],
                    "scale": [30, 30, 30],
                    "src": "assets/White_Rook.glb"
                }
            ]
        }
    ]
}

All properties are optional, and are as follows:

• src: The path to the model file. GLTF and GLB files are supported
• position: The X/Y/Z (left-right/up-down/back-foward) position of the piece, relative to parent, in meters
• rotation: The X/Y/Z rotation of the piece, in degrees
• scale: The X/Y/Z scale of the piece, generally used to correct the model's size
• name: Some sort of descriptive text to make identifying the piece easier
• template: The name of a template to inherit properties from
• color: A HTML color to apply to the piece (or null for default)
• locked: whether this piece can be moved or interacted with
• children: an array of pieces sitting on top of this piece

Templates

Templates are a way to define reusable pieces of configuration. They can inherit from other templates, and share syntax with pieces, minus a "children" property.

{
    "probability": "2024-01-01",
    "templates": {
        "defaults": {
            "scale": [0.1, 0.1, 0.1],
        },
        "redToken": {
            "template": "defaults",
            "name": "Red token",
            "src": "redToken.glb"
        }
    },
    "children": [
        { "template": "redToken", "position": [0.0, 0, 0] },
        { "template": "redToken", "position": [0.1, 0, 0] },
        { "template": "redToken", "position": [0.2, 0, 0] }
    ]
}

Models

Probability supports the GLTF and GLB formats. Models can be converted using a tool such as Convert3D.

Game boards are usually around 0.3m-0.4m wide and should have a similar size to real-life; your models should all be similarly sized, however the "scale" property can help with this.

Model files should be included in the zip file of a published mod. However, while developing a game, you may wish to host them on a web server and include their URLs directly. An example of such a host is Cloudflare Pages.

Publishing a game

Once you have finished building a game, you can make it available for others to play via the catalog.
An example chess game is available here (zip file). There is also a Checkers example.

Clicking "Export" in the editor will create a JSON file containing the game data, suitable for packaging. Models are not included in the JSON file, and should be added to a separate folder in your game project, with their URLs updated.

You will also need a "package.json" file with the following:

{
    "name": "Your Game Name",
    "version": "0.0.0",
    "main": "probability.json",
}

A finished mod should have the following files:

• package.json: describes what is in the mod
• probability.json: exported from the tool; describes the game
• assets/: a folder with GLTF/GLB models

probability.json

The "probability.json" file exported by the tool is similar to a game state, except instead of a children prop, there is a states prop. The states prop can contain multiple game setups, for example boards arranged for different numbers of players.

{
    "probability": "2024-01-01",
    "templates": {
        "token": { src: "token.glb" }
    },
    "states": [
        {
            "name": "1 player setup",
            "children": [
                {
                    "name": "Game board",
                    "src": "gameboard.glb",
                    "children": [
                        { template: "token" }
                    ]
                }
            ]
        },
        {
            "name": "2 player setup",
            "children": [
                {
                    "name": "Game board",
                    "src": "gameboard.glb",
                    "children": [
                        { template: "token" },
                        { template: "token" }
                    ]
                }
            ]
        }
    ]
}

The "probability" prop describes the gamefile version, and must always equal "2024-01-01".

Mod.io specific notes

Icons

The first image in the "Media" gallery will be used as an icon. This image should be square (1:1 ratio) and have a minimum size of 400x400. Note that the "Content listing image" is not used.

Usernames

Underscores ("_") in usernames are converted to spaces (" ").