Presets: Basic Configuration

Moving on

Now that you've got some basic features up and running, let's look at some more quick ways you can operate on simple entities.

Merging vanilla features

One common way to setup your presets is to treat them as overrides for a vanilla-style generator. Cave Generator provides an implicit global variable called VANILLA, which stores all of the default values in a reusable format.

Here's how you can merge all of the fields from VANILLA into your current preset. Notice that you refer to this variable by prefixing it with a $.

$VANILLA: ALL

This statement can be read as merge ALL fields from VANILLA. It will place every key-value pair inside of the variable at this level, including dimensions, tunnels, ravines, and more.

This variable is stored inside of imports/defaults.cave and can be edited to apply changes to every preset that depends on it.

A quick look at variables

You should understand that VANILLA is the only global variable provided by Cave Generator. Any other variable must be imported manually. Here's how that would look:

imports: [
  defaults.cave
]

This statement imports all of the fields inside of imports/defaults.cave into the current preset for use as variables. Now you can use them like this:

imports: [
  defaults.cave
]
$VANILLA: ALL

It's important to keep this statement at the top of your file. This is not a hard requirement for the file to work, but placing it anywhere else means that readers have to scan the entire file before they know where your variables are coming from.

We'll discuss how these imports and merge statements work in greater detail at a later time. For now, this is probably the most common use of imports and merges because it sets your current preset into a vanilla-like state. You'll see a some very similar statements in several of the example presets for this exact reason.

Note:

Because imports is an array with only one element, you can write it in shorthand, like this: imports: defaults.cave. The merge statement, $VANILLA: ALL, is also technically an array, but it is collapsed here to help clarify its purpose; we are not specifying which values to merge.

Working with minimal entities

The last page showed how you can set up a very simple tunnels generator. This object requires no fields because what it spawns comes from caveBlocks, which if empty yields air. Many of the other features require that some sort of state be defined in order to work, as they cannot work without it. Here's an example object containing the most basic form of each object that you can define.

tunnels: [
  {}
]
ravines: [
  {}
]
rooms: { 
  scale: 6
}
caverns: { 
  enabled: true
}
structures: [
  {
    name: fossils/fossil_spine_03
  }
]
caveBlocks: [
  {
    states: [ "stone" ]
  }
]
wallDecorators: [
  {
    states: [ "stone" ]
  }
]
clusters: [
  {
    states: [ "stone" ]
  }
]
stoneLayers: [
  {
    state: stone
    maxHeight: 0
  }
]
largeStalactites: [
  {
    state: stone
  }
]
largeStalagmites: [
  {
    state: stone
  }
]
giantPillars: [
  {
    state: stone
  }
]

Continue reading

Continue to commands.