Revision as of 03:29, 12 September 2017

In Staxel, *.treasure files are used to specify a collection of items. These collections are used in for stuff like shops, block drops etc. Treasure files can also be split into multiple files, which will be explained below at the section, #.

Creating a *.treasure file

Treasure files tend to become quite large as more items are needed but in reality these files don't require much thought. Below is a common case for these files;

{
  "code" : "staxel.treasure.AppleHarvest",
  "entries" : [
    {
      "weight" : 90.0,
      "items" : [
        { "code" : "staxel.item.crops.Apple" }
      ]
    },
    {
      "weight" : 10.0,
      "items" : [
        { 
          "code" : "staxel.item.crops.Apple",
          "quantity" : 2
        }
      ]
    }
  ]
}

Feel free to edit these values however you want. The first property, #"code", is known as the identifier of this treasure. This is basically a unique name that the game can always rely on to find this treasure. The recommendation for this property is to make it the filepath to your file but replace "\" with ".", as the file path is always guaranteed to be unique.

After that property is a single property named "entires". Entries is a List of Blobs. In the example given above there are two blobs given between { and }. In each of these blobs, there are two more properties. The first property is "weight" which is a a decimal number. What happens is that when loaded, all weights are added to each other. This particular weight is divided by the total weight giving you the total chance of getting this blob.

The second property in the entries blob is "items". Items is also a List of Blobs, but these blobs are special. These blobs can differ depending on what item you want to create. There is more information over at Items#Universal Spawning Rules. However the main ones are as follows;

For Tiles and Objects:

{
  "kind" : "staxel.item.Placer",
  "tile" : "tile.code.here"
}

For Clothing and Accessories:

{
  "kind": "staxel.item.Clothing",
  "accessory": "clothing.code.here",
  "palette": "palette.code.here"
}

Palette can be skipped to use the default palette.

And for items themselves

{
  "code": "item.code.here"
}

As an added bonus, you can add the "quantity" property to specify how many items you want to spawn in this spot.

And with that you should now have a working treasure.

How to Add Your Items to an Existing Treasure

Added on the 11th of September, 2017, was the ability to add your own items to existing treasure. This allows you to add your items to be sold in the shops or by the merchants. It can also be used to add items to anything else.

How to do this? It is a very simple procedure:

1. Follow the #Creating a *.treasure file for the items you want to add.
2. When the file has been made, change the code of the file to be the exact same code as the treasure you want to add to. For example if you want to add to the Building stores Blueprint Shelf, you would make the code of your file: "staxel.treasure.storeShelf.BuildingStoreBlueprints")
3. Add a single property to the start of your treasure file:

  "additive": true,

Do it before "entries" and after "code".

And there you have it, your items should now appear in that treasure.

Config Options

"code"

Valid options (String): A unique string which species what this Treasure is.

Default Value: No default value is specified. Always need to provide your own.

A string containing the code of the treasure the blob will be referring to.

"additive"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

This is a property which will specify whether or not this file will "add" it's contents to another file. This other file must have the same exact code.

Using this you can have 5 files with the same code, as long as one, and only one, file has "additive" : False.

"entries"

This is an List Blobs that contains information on each collection of items that can be spawned. This section will commonly look like;

"entries" : [
  {
    "weight": 1.0,
    "items" : []
  },
  {
    "weight": 1.0,
    "items" : [],
    "gate" : { }
  },
]

"weight"

Valid options (Float): A positive decimal number.

Default Value: No default value is specified. Always need to provide your own.

This is how much weight this specific collection will have. The chance to get this pool compared to others is weight / total weight.

"gate"

This is an optional Blob that contains information on when this particular collection should be unlocked.;

"gate" : {
  "totem" : "staxel.totem.Barn",
  "tier" : 0
}

"totem"

Valid options (String): A string containing the code to a Totem file.

Default Value: No default value is specified. Always need to provide your own. (If gate is used.)

This is the totem that needs to exist to unlock this collection.

"tier"

Valid options (Integer): A positive integer number.

Default Value: No default value is specified. Always need to provide your own. (If gate is used.)

This is the tier that the totem needs to be at a minimum. A built Totem is 0 and the upgraded tiers of Totem start at 1.

"items"

This is an List Blobs that contains information on each items that can be spawned. This will commonly look like;

"items" : [
  {
    "kind" : "staxel.item.Recipe",
    "recipe" : "staxel.crafting.recipes.DoorFrame",
    "quantity" : 2
  },
  {
    "kind" : "staxel.item.Recipe",
    "recipe" : "staxel.crafting.recipes.DoorFrame",
    "quantity" : 2
    "gate" : {
      "totem" : "staxel.totem.Barn",
      "tier" : 0
    } 
  }
]

Each blob follows the Items#Universal Spawning Rules of normal items. However there is an extra property which can be used. This is listed below.

"quantity"

Valid options (String): Any valid String.

Default Value: If not specified, will default to 1.

This is the amount of items that will be given / sold.