Collection Spec

Licensed under the GPL-3.0. Maintained alongside Puzzled on GitHub

You can create your own puzzle collection by creating a JSON file with the following structure. Note that any behavior not explicitly described here is subject to change without prior notice or increased version number. If you want to add new features or define behavior not described here, please open an issue. Usually, when loading a malformed file, the application will show an error message and refuse to load the file. If it does not give an error message, when this specification suggests it should, please open an issue as well.

{
    "puzzled": "1.0.0",
    "name": "Example Puzzle",
    "author": "Puzzled",
    "description": "Fill the board with trominoes.",
    "custom_tiles": {
        "looong": [
            [1, 1, 1]
        ]
    },
    "custom_boards": {
        "3x3": {
            "layout": [
                [0, 0, 0],
                [0, 0, 0],
                [0, 0, 0]
            ]
        }
    },
    "puzzles": [
        {
            "name": "Simple",
            "tiles": [
                "looong",
                "L3",
                [
                    [1, 1],
                    [0, 1]
                ]
            ],
            "board": "3x3"
        }
    ]
}

This file can be loaded by Puzzled to add a new puzzle collection for the user to solve. The fields have the following meaning:

Custom Tiles

Custom tiles can be used to define tiles that are not part of the standard tile set. They can then be referenced in the tiles field of a puzzle by their name. The value of each entry in the custom_tiles map is a tile definition, which is explained in the Tiles section below. You can also override standard tiles by defining a custom tile with the same name. Standard tiles are shown below.

Custom Boards

Custom boards can be used to define boards that you want to reuse in multiple puzzles. They can then be referenced in the board field of a puzzle by their name. The value of each entry in the custom_boards map is a board definition, which is explained in the Board section below.

Puzzles

A puzzle describes a single challenge for the user to solve. It has the following fields:

Tiles

A tile defines a shape that can be placed on the board. Tiles can be defined in three ways: by name, with an array or as a more complex custom object.

Name

A tile can be referenced by its name as a String. Those tiles are either standard tiles (see below) or custom tiles defined in the custom_tiles map.

Example:

"L3"

The following standard tiles are available:

Array

A tile can also be defined by a 2D array of integers. The array represents the shape of the tile, where 1 indicates a filled cell and 0 indicates an empty cell.

For example, the following array defines a Z5 tile:

[
    [1, 1, 0],
    [0, 1, 0],
    [0, 1, 1]
]

Which, as a reminder, looks like this:

Custom Object

Some more extensive tiles need more information than just the shape, so they can be defined as an object with additional fields. This looks like this:

{
    "layout": [
        [1, 1, 0],
        [0, 1, 0],
        [0, 1, 1]
    ],
    "color": "#AABBCC",
    "count": 2
}

The layout must be defined as described in the name or array section above, but additional fields can be added to define additional properties of the tile, like its color.

Board

A board defines the layout on which the puzzle is to be solved. There are two variants of boards, which can be defined in three ways, so pay attention. Boards can be referenced by name, defined as a Simple Board or as an Area Board.

Name

Similar to tiles, a board can be referenced by its name as a String. Standard boards or custom boards defined in the custom_boards map can be referenced this way.

Example:

"my_custom_board"

The following format of standard boards are available:

You can define a simple rectangular board of any size using the following naming scheme: <width>x<height>, where <width> and <height> are positive integers. The following board definitions will result in the same board:

"4x3"

{
    "layout": [
        [0, 0, 0, 0],
        [0, 0, 0, 0],
        [0, 0, 0, 0]
    ]
}

Simple Board

A simple board is defined by a 2D array of integers, where 0 indicates an empty cell where a tile can be placed and 1 indicates a blocked cell where no tile can be placed.

Example:

{
    "layout": [
        [0, 0, 0],
        [0, 1, 0],
        [0, 0, 0]
    ]
}

Here, tiles can be placed in all cells except the one in the center.

Area Board

An area board is a board, where one cell has to be left empty in each area when solving the puzzle. This is the board type used in the original Puzzle A Day.

Example:

{
    "area_layout": [
        [0, 0, 0, -1],
        [-1, 1, 1, 1]
    ],
    "values": [
        ["A", "B", "C", ""],
        ["", "D", "E", "F"]
    ],
    "value_order": [
        [0, 1, 2, -1],
        [-1, 0, 1, 2]
    ],
    "areas": [...],
    "target_template": "{0} and {1}"
}

Area

The area gives additional information about an area on an area board.

Example:

{
    "name": "Day",
    "formatter": {
        "type": "Nth"
    },
    "default_factory": {
        "type": "CurrentDay"
    }
}

Area Formatter

The area formatter takes the raw value from the board and formats it for display to the user.

Plain

Returns the value as is.

{
    "type": "PLain"
}

Nth

Appends “st”, “nd”, “rd” or “th” to the value based on its last character. It is expected that the value ends with a digit.

{
    "type": "Nth"
}

PrefixSuffix

Appends a prefix and/or suffix to the value.

{
    "type": "PrefixSuffix",
    "prefix": "x",
    "suffix": "z"
}

Default Factory

The default factory generates the default target for an area. The product of the default factory MUST be equal to a value on the board in the area the factory is used for.

Fixed

Returns a fixed value.

{
    "type": "Fixed",
    "value": "example"
}

CurrentDay

Returns the current day of the month as a string.

{
    "type": "CurrentDay"
}

CurrentMonthShort

Returns the current month as a three-letter abbreviation. E.g., “Jan” for January, “Feb” for February, etc.

{
    "type": "CurrentMonthShort"
}

CurrentYear2FirstDigit

Returns the first digit of the current 2-digit-year as a string. E.g., “2” for the year 26.

{
    "type": "CurrentYear2FirstDigit"
}

CurrentYear2SecondDigit

Returns the second digit of the current 2-digit-year as a string. E.g., “6” for the year 26.

{
    "type": "CurrentYear2SecondDigit"
}

Progression

The progression field defines how puzzles in this collection are unlocked for the user. This field is available since version 0.3.0 of Puzzled.

Example:

{
    "type": "Any"
}

The following progression types are available:

Preview

The preview field defines whether to show previews of locked puzzles. This field is available since version 0.3.0 of Puzzled.

Example:

{
    "show_board": true,
    "show_tiles": false,
    "show_tile_count": false,
    "show_board_size": false
}