Prickle

Prickle is a configuration file format based on JSON. This modification enables the use of this format directly in Minecraft! Complete technical documentation can be found on the GitHub page.

Frequently Asked Questions

What advantages does Prickle offer?

Although Prickle is built on JSON, it is enhanced with several useful features including comments and decorators. The format is fully backward compatible with JSON and supports all its capabilities, tools, and syntax highlighting.

Why is it called Prickle?

Prickle is the collective noun for a group of hedgehogs. These animals are among my favorites, and I consider them a fitting metaphor for configuration files. For instance, both might seem intimidating at first but become pleasant after getting to know and understand them.

Why not use existing formats?

Previously, I used JSON for configuration files but encountered several issues such as the lack of comments and default values. Prickle adds these features to JSON while maintaining full backward compatibility. I tried other formats like TOML but was disappointed with many of their Java implementations. They often lack important features, contain serious bugs, and are no longer updated. Since Minecraft already uses JSON for datapacks and commands, this format is familiar to most players.

Format Specifications

In Prickle, property values are wrapped in a JSON object. This allows metadata like comments to be attached to the corresponding property.

For example, a standard JSON file might look like this:

{
  "database_host": "192.168.1.222"
}

The same file in Prickle format would appear as follows:

{
  "database_host": {
    "//": "The IP address of the database to connect to.",
    "value": "192.168.1.222"
  }
}

Comments

The // key is reserved for comments. They serve solely to provide additional context to the reader and do not affect file parsing. Comments can be a JSON string or an array of strings for multi-line comments.

{
  "database_host": {
    "//": [
      "The IP address of the database to connect to.",
      "The port can be defined at the end using :"
    ],
    "value": "192.168.1.222:1273"
  }
}

Decorators

Decorators are named comments conveying a specific attribute of a property. A common example of a decorator is //default, used to display the default value of a property. Like comments, decorators do not influence file parsing; they only describe how the property will be processed.

Prickle files may include the following decorators:

• //default — the default value of the property
• //reference — a resource for additional information, such as a link to a wiki page
• //range — the acceptable value range, e.g., >=5
• //regex — a regular expression the value must match
• //empty-allowed — whether empty values are permitted (default is true)