Overview
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.
Files are HOCON formatted (a superset 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 the following:
[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
The configuration may be reloaded at any time with sponge plugins reload. If an error occurs, please note that all particle effects and crates will not function until the error is fixed and the config can be reloaded successfully.
Getting Started
This section is designed to introduce you to the core concepts used throughout the TeslaCrate configuration.
Data Types
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 standard four types:
boolean: A true or false value, such astrueandfalse.int: An integer number, such as7,42, and-101double: A decimal number, such as1.0,6.66,.707,4, and-273.15String: A ‘string’ of characters, such as"String","words 'n $ymb0lz", and"13"(note the quotes!). Strings are often surrounded with the double-quote (") to separate them from other data types and allow for special characters, but HOCON supports unquoted Strings as well (with a number of restrictions). Some characters such as the double-quote have special meaning and must be escaped with a backslash (\).
Identifiers
An identifier is used to represent a component (such as an item) in a configuration file. The builder identifier is used to create a component, while the reference identifier is used to insert an existing one.
Builder Identifier
A builder identifier defines a component and assigns its properties. For example, the following builder may be used to create an item representing a stack of wheat.
wheat-item { //Opens an item builder named wheat-item
id="wheat" //Default namespace is minecraft:
quantity=64
}
Builders may also placed inside of others anywhere an identifier is expected. This type of builder is called 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="wheat"
quantity=64
}
}
}
In the example above, we can see how an item builder is being used inside of a reward builder. However, if we have multiple rewards that all have wheat-items, it’s easy to see that this can quickly get out of hand and turn into a lot of copy pasting - and this is a simple item!
Reference Identifier
In many cases, you’ll have components that will be used in multiple places throughout TeslaCrate - you might have two different crates that share a reward, or multiple rewards that have the same item in them. As such, it would be extremely useful if we could build a component once and have TeslaCrate copy it for us rather than doing it itself. For that, we have reference identifiers.
A reference identifier ‘references’ an existing builder that has been declared in one the component configuration files. This is done in the form name=value, where name is the name of the component you’re referencing and value is it’s reference value (see below). As a simple example, let’s create our wheat-item from above and add it to a reward.
//Within items.conf
wheat-item { //Opens an item builder named wheat-item
id="wheat"
}
//In the location of your reward identifier
wheat-reward { //Opens a reward builder named wheat-reward
items {
wheat-item=64 //References wheat-item and..?
}
}
Reference identifiers do add an extra step (and the separate config files can be tricky as well!), but it allows use to use the same component in multiple places throughout the configuration while using an in-line or nested builder limits the scope to one instance.
But wait, what happened with the quantity on our wheat-item? To understand this, let’s talk about reference values.
Reference Values
Remember that a reference identifier has two parts - name and value. The reference value is really what makes references so powerful as it allows you to tweak a component just a bit to match your use case. In the example above, our reference identifier wheat-item=64 used the wheat-item we defined earlier but changed it’s quantity to 64 within that reward. As such, we can now change the quantity of an item without re-building it each time!
The type (and effect) of a reference value is dependent on the type of component that we’re referencing. For items, as we’ve seen, the reference value changes the quantity. In this next example, we’ll use the reference value to change the weight of our wheat-reward component when we add it to a crate.
farming-crate {
rewards {
wheat-reward=10.0 //References wheat-reward and adds it with a weight of 10.0
}
}
As you can see, reference values can be extremely powerful and save you a lot of time (and space!) in your configuration.
Components
A component is a generic term that refers to a command, crate, item, key, or reward. All components have the following properties that may be defined.
component-name {
display-name="String" //The display name of the component, used in 'display like' messages and GUIs.
description="String" //The description of the component
display-item {} //An inline item builder for the display item used in GUIs.
}
In order to uniquely identify a component created using an inline builder (as there may be other components of that name used elsewhere), it is given a verified name that is dependent on the component it is within. For example, the verified name of the ‘cookie’ item below is food-reward:cookie-item, which is what would be used in commands.
food-reward { //Opens a reward builder named food-reward
items {
cake=1 //References an item named cake
cookie { //Opens an item builder named cookie
id="cookie"
}
}
}
Command Component
A command component represents an executable command on the server. The reference value of a command is essentially a placeholder for the command that is replaced when the command is executed.
command-name {
command="String" //The command to be executed. The placeholders <player> and <value> may be used.
source="Server/Player" //The source of the command. (defaults to Server)
value="String" //The default reference value of the command (defaults to <value>)
}
Crate Component
A crate component is one of the fully-built crates in TeslaCrate. Because a crate is the highest level component, it does not have a reference value.
crate-name {
keys {} //A map of key identifiers
announcement="String" //The announcement message, which supports <player>, <crate>, and <reward>.
message="String" //The private message sent. The above placeholders may be used as well.
cooldown=int //The cooldown, in milliseconds, between uses of this crate.
gui="None/Instant/Roulette" //The type of GUI to use.
particles {} //A map of particle identifiers
weight-sum=double //The expected weight sum for all rewards, or the roll-all comparison value.
roll-all=boolean //Whether or not to roll for each reward individually.
roll-min=int //The minimum number of reward rolls to make.
roll-max=int //The maximum number of reward rolls to make.
rewards {} //A map of reward identifiers
}
Key Component
A key component represents a key that can be used to redeem a crate. The reference value of a key is it’s quantity.
key-name {
item {} //An inline item builder for the keys physical item. If not defined, the key is virtual.
quantity=int //The quantity of this key required to open a crate.
}
Item Component
An item component is an item that can be given to the player. The reference value for an item is it’s quantity.
item-name {
id="String" //The id of the item. The default namespace is minecraft.
data=int //The data (or damage) value of the item
keys {} //A map of keys in the form id=value. The default namespace is sponge.
enchantments {} //A map of enchantments in the form id=level. The default namespace is minecraft.
nbt {} //A map of NBT tags in the form tag=value.
quantity=int //The quantity of the item (defaults to 1)
}
Particle Component
A particle component defines a particle effect that can be applied to a crate. Available path types are circle, helix, spiral, and vortex. The reference value of a particle is it’s offset.
particle-name {
type="String" //the type of the animation path for this particle.
particle="String" //the id of the particle, defaults to redstone. The default namespace is minecraft.
color=int //the RGB color (in decimal) of the particle. The particle must support colors.
rainbow=boolean //whether or not to rainbowify the color. The particle must support colors.
animated=boolean //if true, the path with be animated (defaults to true)
precision=int //the number of points in a path at normal speed (defaults to 120)
segments=int //the number of even-spaced particles in this effect (defaults to 1)
speed=float //the speed of the particle (defaults to 1)
shift=float //the phase shift of the particle (defaults to 0)
scale=Vector3f //the relative scale of the particle effect (defaults to [1, 1, 1])
offset=Vector3f //the relative offset from the center of the block (defaults to [0, 0, 0])
}
Reward Component
A reward component represents one of the potential rewards that can be given from a crate and can contain multiple commands or items. The reference value of a reward is it’s weight.
reward-name {
announce=boolean //If true, redeeming this reward will send an announcement if the crate has one set.
commands {} //A map of command identifiers for this reward's commands.
items {} //A map of item identifiers for this reward's items.
weight=double //The weight, which determines the chance of being selected relative to other rewards.
}
Examples
The following sections are independent configuration examples. These have been selected as frequently asked ‘how do I do this…’ type of questions and are targeted to show a specific process within TeslaCrate. Examples are not intended to be a complete configuration.
Item Display Name & Lore
item-name {
keys {
display-name="&eDisplay Name"
item-lore=[
"&6Item Lore"
]
}
}
Item Enchantments
item-name {
enchantments {
"power"=7
}
}
Item NBT
item-name {
nbt {
SpriteName="pixelmon:sprites/pokemon/479" //Requires Pixelmon... duh xD
}
}