Prickle

Prickle is a JSON based config format. This mod allows other mods to use Prickle for their config files! For technical documentation please see the GitHub page.

FaQ

Why is this called Prickle?
Prickle is the collective noun for a group of hedgehogs. Hedgehogs are one of my favourite animals and I think they are a fitting metaphor for config files. For example, they both may seem intimidating at first but can be nice once you get to know and understand them.

Why not use an existing format?
In the past I used standard JSON for my config files but there were several issues such as the lack of comments and default values. Prickle adds these features to JSON while remaining 100% backwards compatible. I have tried several other formats like TOML but I was disappointed with a lot of their Java implementations. They often lack features I found important, has serious bugs, and were no longer being maintained. Minecraft also uses JSON for datapacks and commands, making it a familiar choice for most players.

Format Specifications

In Prickle property values are wrapped in a JSON object. This allows metadata and other properties to be attributed to that property. The actual value that the user edits is held by the value property.

For example in standard JSON a file would look like this.

{
  "database_host": "192.168.1.222"
}

The same JSON as a Prickle file would look like this.

{
  "database_host": {
    "value": "192.168.1.222"
  }
}

Comments

The // key is reserved for comments. Comments are only used to provide additional context to the reader and should never influence how the file is parsed. Comments can be a JSON string or an array of JSON strings for multiline comments.

{
  "database_host": {
    "//": "The IP address of the database to connect to.",
    "value": "192.168.1.0"
  }
  "database_host_backup": {
    "//": [
      "A backup IP address to connect to. This is only",
      "used if the default host can not be reached    "
    ],
    "value": "192.168.1.0"
  }
}

Decorators

Decorators are named comments that convey a specific attribute of the property to the reader. A common example of a decorator is //default which declares the default value for the reader. Like comments, decorators never influence how the file is parsed, they are purely descriptive.

You may encounter some of the following decorators in prickle files.

• //default - The default value of the property.
• //reference - A resource that can be used to learn more, like a wiki/docs page.
• //range - The acceptable range for a numeric value.
• //regex - A regex pattern that the value must match.
• //empty-allowed - If the value can be empty or not.

This project is sponsored by Nodecraft. Use code DARKHAX for 30% off your first month of service!

Prickle is a JSON based config format. This mod allows the format to be used in Minecraft! For technical documentation please see the GitHub page.

FaQ

What benefits does Prickle offer?
Prickle is based on JSON but adds several useful features like comments and decorators. Prickle is 100% backwards compatible with JSON and supports all of its features, tools, and syntax highlighting.

Why is this called Prickle?
Prickle is the collective noun for a group of hedgehogs. Hedgehogs are one of my favourite animals and I think they are a fitting metaphor for config files. For example, they both may seen intimidating at first but can be nice once you get to know and understand them.

Why not use an existing format?
In the past I have used JSON for my config files but there were several issues such as the lack of comments and default values. Prickle adds these features to JSON while remaining 100% backwards compatible. I have tried other formats like TOML but was disappointed with a lot of their Java implementations. They often lack features I feel are important, have serious bugs, and are no longer being maintained. Minecraft already uses JSON for datapacks and commands, making it a familiar choice for most players.

Format Specifications

In Prickle property values are wrapped in a JSON object. This allows metadata like comments to be attributed to that property.

For example a standard JSON file would look like this.

{
  "database_host": "192.168.1.222"
}

The same JSON as a Prickle file would look like this.

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

Comments

The // key is reserved for comments. Comments are only used to provide additional context to the reader and should never influence how the file is parsed. Comments can be a JSON string or an array of strings for multiline comments.

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

Decorators

Decorators are named comments that convey a specific attribute of the property. A common example of a decorator is //default which can be used to display the default value of the property. Like comments, decorators have no influence on how the file is parsed, they only describe how the property will be parsed.

You may encounter some of the following decorators in prickle files.

• //default - The default value of the property.
• //reference - A resource that can be used to learn more, like a link to a wiki page.
• //range - The acceptable range for a value. For example >=5.
• //regex - A regex pattern that the value must match.
• //empty-allowed - If the value can be empty or not. (default is true).

Sponsors

This project is sponsored by Nodecraft. Use code DARKHAX for 30% off your first month of service!