Using Hjson

Background

Cave Generator presets are written in Hjson, a superset of regular JSON designed to be more human-readable. It might be tempting to view them as scripts, but they are not. Presets are just regular settings files with a lot of settings.

If you are not familiar with JSON, you will save a lot of time by learning that first. This is not the guide for that. Search for a guide online or watch this crash course for basic information on the JSON syntax.

Why Hjson

The reason we are using Hjson instead of regular JSON is because, in theory, it is easier to read for new users. That being said, it is not necessarily easier to write. This because there are some circumstances under which the relaxed syntax guidelines do not work and you have to default back to regular JSON.

Hjson requires fewer tokens than regular JSON and is less picky about whether you're using enough or too many commas.

This converts the following example,

{
  "name": "Person",
  "family": "TheCat",
  "likes": [
    "dogs",
    "chocolate",
    "Jessica from grade school"
  ],
  "description": "An actual human cat.\nHe resides solely in the dark box." 
}

Into something a little simpler:

name: Person
family: TheCat
likes: [
  dogs
  chocolate
  Jessica from grade school
]
description:
  '''
  An actual human cat.
  He resides solely in the dark box.
  '''

Comments

Your presets can be complicated. A very important feature of Hjson is that it enables you to document your files with comments. I encourage you to put these there so that you can remember what everything is for and help other people understand what you've done.

Here's a good example:

# That's me!
name: Person
family: TheCat

# This is just a little info about me,
# what I like, etc. You know how I am.
description:
  '''
  An actual human cat.
  He resides solely in the dark box.
  '''

Special cases

Cave Generator does a few things differently that may be confusing to some users. Some of these features are mostly here for backwards compatibility, but they all help reduce the number of tokens you need to write in your file, theoretically improving readability.

Arrays

In Cave Generator, arrays having only one single element can be written as regular values.

For example,

colors: [
  RED
]

can be simplified as:

colors: RED

Variables

Cave Generator has built in support for declaring variables. Variables are not required for writing presets. They are here to help you organize your files and improve readability. They will be discussed in more detail on a later page.

For now, here is a simple example of how they look:

variables: {
  FOREST_BIOMES: {
    types: [
      FOREST
    ]
  }
}
tunnels: [
  {
    biomes: $FOREST_BIOMES
    other: settings
  }
]

When Hjson doesn't work

Hjson does not technically remove the need for commas. It just gives you the option of using either a comma or a new line. If you don't supply a new line between your values, you need to default back to standard JSON syntax.

For example, to put all of these values on single lines,

colors: [
  RED
  GREEN
  BLUE
]
card: {
  type: VISA
  number: Nice try, Satan.
}

You would write this:

colors: [ "RED", "GREEN", "BLUE" ]
card: { type: "VISA", number: "Nice try, Satan." }

Using regular JSON

Don't want to use Hjson? You can simply write your presets in regular JSON and everything will be parsed as expected. Be aware that if your preset does get updated, it will be rewritten with the regular Hjson syntax. You can avoid this by extending your file with .json instead of .cave or .hjson. If you would like to convert an existing preset to JSON, you can run the command /cave tojson <name>, where <name> is the name of your preset file, with or without the extension. You can also convert any regular JSON file in your presets directory to Hjson by running the command /cave tohjson <name>.

More information

Take a look at hjson.org for more details about the Hjson project and what it can do. There is also a very helpful linter online which can check your syntax for you, highlight special tokens, and display them in regular JSON. You may find it easier to write your presets directly in this window so you can clearly see what is happening as you do.

Continue reading

Continue to presets: features.

Skip to writing presets.