The TeslaCrate configuration is broken up into three primary sections: The settings file in the main directory, configuration files in the configuration folder, and storage files in the storage folder.

The teslacrate.conf file is HOCON formatted (an extension of JSON), so it is important to ensure spacing, braces, quotes, and everything else in the file is configured properly. If a parsing error exists, you will receive an error similar to-

[com.mcsimonflash.sponge.teslacrate.internal.Config:loadConfig:107]: java.io.IOException: configurate.typesafe.config.ConfigException$Parse: Reader: 42: Expecting close brace } or a comma, got end of file

This section is designed to introduce you to the core concepts used throughout the TeslaCrate configuration.

When working with the configuration, you'll use a variety of different data types as values. Though there are plenty more to explore, here are the main four you need to know.

A boolean value simply encodes true or false. Examples are, well, true and false.

An int, or integer value, is a whole number. Examples are 1, 9, 472, and -42.

A double is a number that has a decimal. Examples are 23.6, 2398.0, 4, and -.38.

A String is essentially a 'string', if you will, of one or more characters. Examples are "String", "a bunch of words and $ymb0lz", and "7". When writing a String as a value, we surround it with the double-quote (") to allow for the use of whitespace and various other characters. In order to use characters that have an alternative meaning (like the double-quote), the character must be escaped.

Within TeslaCrate, an identifier is used to represent an object (such as an item) in a configuration file. There are two main identifiers: The builder identifier, which is used to create an object, and the reference identifier, which used to insert an existing object. Additional information and examples of these can be found below.

A builder identifier defines an object and assigns it's properties. Let's take a look at an example of an item builder that denotes a stack of wheat.

This example shows a builder for an item.

wheat-item { //Opens an item builder named wheat-item
    id="minecraft:wheat"
    quantity=64
}

Builders may also be used inside of other builders anywhere that expects an identifier, as in the following example.

This example shows the use of an inline (or nested) builder.

wheat-reward { //Opens a reward builder named wheat-reward
    items {
        wheat-item { //Opens an item builder named wheat-item
            id="minecraft:wheat"
            quantity=64
        }
    }
}

In the example above, we can see how an item builder is being used inside of a reward builders. Though convenient, the repetitive use of builders can become verbose, inefficient, and difficult to debug. As such, we can instead use references.

A reference identifier is used to insert an existing builder into a section of config and follows the format name=value. Lets take a look at how we might use references in the wheat-reward example above.

This example redefines the builder version of our wheat reward to use references.

//Within items.conf
wheat-item { //Opens an item builder named wheat-item
    id="minecraft:wheat"
    quantity=32
}

//In the location of your reward identifier
wheat-reward {
    items {
        wheat-item=0 //Makes the reference use the default quantity of 32
    }
}

Reference identifiers add a bit of an extra step, but they allow you to reuse a builder (in this case our wheat-item) in multiple places throughout the configuration, while using an in-line or nested builder limits the scope to one instance. However, the real power comes from using reference values.

A reference has two parts: The name, and it's value. The value of the reference is used to modify a variable in the original builder. Let's see how this might come into play when using our wheat-reward in a crate.

This example shows using reference values to set a reward chance versus using a node within a builder.

//With a reference value
farming-crate {
    rewards {
        wheat-reward=10.0 //Sets the weight to 10.0 for this reference
    }
}

//With a builder node
farming-crate {
    rewards {
        wheat-reward {
            weight=10.0
            
            //Whatever commands and items and stuffs.
        }
    }
}

As you can see, reference values can be very powerful and save you a lot of time setting up your configuration!

A component is a generic term that refers to a command, crate, item, key, or reward. All components share a few of the same properties (such as a display-name), which will be covered later on in the configuration section.

The name of a component is used throughout the configuration files and commands to uniquely identify it. Take a look at the example below of a reward.

//In rewards.conf
announcement { //Opens a reward named announcement
    commands {
        broadcast { //Opens a command named broadcast
            command="/broadcast I'm a component!"
        }
    }
}

Here, we have two components - the reward announcement and the command broadcast. However, in order to uniquely identify our broadcast command as belonging to announcement (as there may be another inline command named broadcast in another reward), we define the name of the command to be announcement:broadcast. This name is also called the unique name, while broadcast is referred to as the simple name. The unique name is the 'official' name of the command and will be used in commands.

The core configuration file (teslacrate.conf) contains the main TeslaCrate settings.

Type: boolean

If true, comments will be displayed above nodes that cause errors. This may delete existing comments or cause errors to formatting.

Type: boolean

If true, TeslaCrate will use its custom serializers over Sponge ones. This is generally more user-friendly, however may not support certain features.

Type: String
Default: The unique name

The description for this component used in gui menus and text information.

Type: ItemStack
Default: Varies

The display-item for this component used in gui menus. The default value varies depending on the exact type of the component, but is intended to represent what the component is as best as possible.

Type: String
Default: The simple name

The name used in non-administrative messages and guis.

Type: String

The command to be executed with or without the preceding /. You can use for the name of the player and for the reference value.

Type: boolean
Default: true

True if the command is executed from the server, false for the player.

Type: String
Default: <value>

The default value to be used for this command. If the actual command does not use a reference value (has <value> in it) this node does nothing.

Type: String

The announcement to the server when a player opens a reward. You can use <player> for the player's name, <crate> for the crate's display name, and <reward> for the reward's display-name.

Type: int
Default: 0

The cooldown (int seconds) between uses of this crate. Players with the permission teslacrate.crates.<name>.no-cooldown permission may bypass this check.

Type: boolean
Default: false

Whether to launch a firework when a crate is opened or not.

Choices: instant, none, roulette
Default: none

The gui used when this crate is opened.

Type: String

The message sent to the player when they receive a reward. The same arguments are available here as in announcement.

Choices: circle, helix, none, rings
Default: none

The particle animation around crate locations.

Type: {Key}

A map of keys required to open this crate. The reference value of a key is the quantity.

Type: {Reward}

A map of rewards present in this crate. The reference value of a reward is the weight.

Type: int
Default: 0

The data (or damage) for the item.

Type: String

The item id, in the form mod-id:item-id. If the id does not have a mod id, minecraft will be used.

Type: ???

A map of key ids to values in the form mod-id:key-id=value. If the id does not have a mod id, sponge will be used.

Type: int
Default: 1

The quantity of items, which must be between 1 and the max stack size for the given item (inclusive).

Type: ItemStack

The item used for this key. Declaring an item marks this key as a physical key.

Type: int
Default: 1

The quantity of keys required.

Type: boolean
Default: true

Whether or not this reward should be announced if it is won. The crate must also have an announcement message set.

Type: double
Default: `0.0

Type: {Command}

A map of commands in this reward. The reference value of a command is the value.

Type: {Item}

A map of items in this reward. The reference value of an item is the quantity.

// TeslaCrate - Developed by Simon_Flash
// Config Version - 2.0.0
//
// For reference, check out the TeslaCrate Wiki
// https://github.com/SimonFlash/TeslaCrate/wiki
//
// For support, check out my Discord server
// https://discordapp.com/invite/4wayq37

// Set this to true to convert legacy data from v1.1.3.
"-legacy"=false

// If true, TeslaCrate will use its custom serializers over Sponge ones. This is
// generally more user-friendly, however may not support certain features.
custom-serialization=true

// If true, comments will be displayed above nodes that cause errors.
error-comments=true

broadcast {
    command="broadcast <value>"
    value="Provided by Tesla™Crate® LLC &co All Rights Reserved Simon, Simon, and Simon. YMMV"
}
smite {
    command="smite <player>"
}

tesla {
    display-name="Tesla"
    display-item {
        id="ender_chest"
        keys {
            display-name="&eTesla &6Crate"
            item-lore=[
                "&eOne Crate to rule them all,",
                "&6One Crate to find them...",
                "&eOne Crate to bring them all,",
                "&6And in the darkness bind them.",
                "&0In the land of Minecraft where the Spongies lie..."
            ]
        }
    }
    announcement="&e<player> &6opened a &e<crate>&6 Crate and won <reward>&6!"
    message="&6You opened a &e<crate>&6 Crate and won <reward>&6!"
    firework=true
    particles="rings"
    keys {
        skeleton=1
    }
    rewards {
        advertisement=30
        lightning=60
        wither-kit=10
    }
}

cookies {
    id="cookie"
    quantity=6
}
soul-sand {
    id="soul_sand"
}
wither-skeleton-skulls {
    id="skull"
    data=1
}

public {
    display-name="Public"
    display-item {
        id="name_tag"
        keys {
            display-name="Public Key"
            item-lore="F9A624679DA65201257046996F66DC41FE8B1E5896EF8624C44FC8C9354C4FB42E64A9E70449591DB3F071C7E49AD165296BBFEE958B15F4C3395ECA5714A5287E2F73B93F5C6320DD111C3DD928C5D1205CD1917F040D1F1D9EC"
        }
    }
}
skeleton {
    display-name="Skeleton"
    item {
        id="bone"
        keys {
            display-name="&fSkeleton Key"
            item-lore="&7Unlocks some crates - maybe."
        }
    }
}

advertisement {
    display-name="Advertisement"
    announce=false
    commands {
        broadcast=""
    }
    items {
        cookies=13
    }
}
lightning {
    display-name="Lightning"
    display-item {
        id="blaze_powder"
        keys {
            display-name="&eLightning"
        }
    }
    commands {
        broadcast="The Gods are not entertained"
        smite=""
    }
}
wither-kit {
    display-name="Wither Kit"
    items {
        soul-sand=4
        wither-skeleton-skulls=3
    }
}