Presets: Getting Started

Create a file

The first thing to do is create a new file and extend it with either .cave or .hjson or .json if you want to use the regular JSON syntax. That's it! This is just a regular text file that you can open with any text editor, e.g. Notepad, Notepad++, Sublime, or use the official linter online for the best syntax highlighting available.

Your new preset

The first thing you should know about these presets is that most fields are optional and almost nothing is required. Until you define these values, here is what your empty preset technically looks like right now:

enabled: true
biomes: {}
dimensions: [ 0 ]
biomeBlacklist: false
dimensionBlacklist: false
replaceableBlocks: [ "stone", "dirt" ]
replaceDecorators: true
caveBlocks: []
wallDecorators: []
rooms: { scale: 0 }
tunnels: []
ravines: []
caverns: { enabled: false }
structures: []
clusters: []
stoneLayers: []
largeStalactites: []
largeStalagmites: []
giantPillars: []

All of these settings are designed to either have no functionality or simulate having no functionality. This is intended to give you less to worry about when writing presets so that you don't have to manually specify which features you do and do not want.

Adding features

For the same reason, adding new objects into some of these arrays with no values will provide you with default implementations of them.

Here's a really simple example of how you can add some basic tunnels to your preset:

tunnels: [{}]

You may also want to explicitly clarify that your preset is enabled and make it easier to disable in the future.

enabled: true
tunnels: [{}]

Adding decorations

You can then fill your tunnels with water by adding a caveBlock to whichever height you want.

enabled: true
tunnels: [{}]
caveBlocks: [
  {
    states: [ "water" ]
    maxHeight: 63
  }
]

Keeping your preset neat

You can reduce the number of lines in your file by compressing single element arrays into objects, like this:

enabled: true
tunnels: {}
caveBlocks: {
  states: water
  maxHeight: 63
}

Preset Tester and Syntax Helper

Cave Generator comes with a couple of utilities that print diagnostics in your log. These tools will inform you of which fields have and have not been used in your presets. They will also tell you if you have any unusual values and detect a couple of poor user-ended optimizations.

Make sure to read the log every time you reload your presets or start your game. These can be very helpful in debugging.

Here's an example of a preset which has loaded with no issues:

### Begin testing stone_clusters_test ###
 --- Json diagnostics ---
The following fields were found in stone_clusters_test. If you do not see one, you may have accidentally commented it out.
 * dimensions
 * biomes
 * replaceableBlocks
 * rooms
 * caveBlocks
 * tunnels
 * ravines
 * enabled
 * clusters
No unused fields were detected inside of stone_clusters_test
 --- Logic and syntax diagnostics ---
### stone_clusters_test testing complete ###

And another preset which contains some unused fields:

The following fields were never used by ravine_test. Any field listed below has no effect whatsoever.
 * tunnelsBak
 * tunnelsBak.systemChance
 * tunnelsBak.noiseYReduction
 * oldclusters
 * oldclusters[0].states
 * oldclusters[0].chance

And one more example which contains a few errors:

 --- Logic and syntax diagnostics ---
Poor chance @ largeStalactites[state=minecraft:leaves[check_decay=false,decayable=true,variant=oak]]. Use a value between 0 and 1.
Unnecessary block @ replaceableBlocks. Unless it is placed by a different preset or mod, minecraft:stone[variant=granite] does not exist when this array is used.

Continue reading

Continue to presets: understanding tunnels