Latest revision as of 01:44, 9 November 2020

In Staxel, *.tile files are a file which allows an object to be placed into the world. There are three different types; objects, materials and tile state entities. The three different types are used in different situations;

Objects - Used for all basic objects.
Materials - Used for all blocks that should be placed often. Contains more logic with combining surround tiles into a cohesive texture. Also features more LOD enhancements than normal objects.
Tile State Entities - Basic objects that are extended to have extra properties. These include animations, interactiveness and other features.

These objects are all defined by the same file and work similarly to each other for the most part.

Creating a Tile-Object

In Staxel, everything that is placeable is known as a Tile. There are two different main types of Tiles that can be placed in the worlds.

Materials: Tiles that follow this strict design. An example of this is; Media:Qubicle.png. This allows tiles to render at a very far distances.
Tile Objects: Everything else.

This tutorial will be focusing on the second option. This option covers everything from a fences to plants, from tables to barrels and everything else in between. Blocks such as Dirt, Wood and stone are not covered in this tutorial but in #Creating a Material.

Before you start this tutorial, be sure to head through Modding#Getting Started with Staxel Modding.

If you are working with the Staxel Launcher then after going through the setup tutorial, then open it up and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them.

If you ever do come to see "Begin Update", remove the files from the \mods\ before starting. Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Make sure that all files are already ready in the \mods\ folder.

Creating the Model

Creating the model is the hardest part of this section. After having gone through the setup tutorial, you will have chosen a modelling program. Before creating a model, you will need to setup the size of the model. In Qubicle, select the box and then size box in the right bar. The following window will appear;

This shows you how many voxels your object will take. In Staxel, a single Tile has the size 16 x 16 x 16. For this tutorial, try to keep the size of the object at or below 24 x 24 x 24 however you can go up to 80 x 80 x 80. If you do go above 24 x 24 x 24, you will just need to do an extra step later.

While the above points out how to see/change the size in Qubicle, all other programs will have a similar ways to change the max size of the model. Beyond this, it's to you to make what you want. Here are some tips that might help you out.

The specifics of this step will vary on what type of modelling software that you use, however here are some general tips.

Try looking up an object and try recreating that. It can be helpful to view it from the object from different angles.
Voxel art is not a highly common practice and therefore there aren't many tutorials. However many pixel art tutorials will help with understanding how to create voxels as the same underlying principles still apply in 3D.
Keep in mind the size of the object. The player is roughly 2-3 blocks high, 1-1.5 blocks wide. Sizing is easily lost when working on an object by itself.
If working with programs that let you place voxels outside the box, make sure that all voxels are inside of the box before exporting. (Needed for VoxelShop, which if certain settings are used, will only output what is inside the box.)

Once you are done, you will need to "export" or save the file. Most programs will have their own format for storing voxel models. For example Magica Voxel stores them as *.vox and Voxel Studio stores them as *.vsd. Staxel uses only one format, the *.qb file created by Qubicle. As this is a popular format, most software available have a way to "export" to a *.qb file. So when your model is done, be sure to export to *.qb.

Adding the Tile Object to Staxel

As mentioned in the Setup, there are two main ways of adding the model to Staxel. Both of these ways were mentioned in Modding#Getting Started with Staxel Modding.

Adding the Tile Object via Asset Manager

Follow Modding#Using the AssetManager to Create Mods to open up the Asset Manager. With the Asset Manager open, head to View -> Tiles and Objects -> Tile Assets. When the new window is open head to Asset -> Add -> New Asset and the following window will show up.

First click on the button Asset Path and navigate upwards to the /content/ folder. Once there, open the /mods/ folder and create a new folder. Name this new folder to what you want the mod to be called and then open this new folder. When you open this folder give the asset a name and click save. After this is done, click the kind dropdown and change it to "Object". After this press OK.

After the asset is created, it will have been automatically selected. With that it is now time to tell the game what you want to do with this tile. The following set of steps highlight the important properties, however you can mess with any property.

Click on Categories. And then click on the [...]. You can now add a bunch of terms you want to be able to search for your object. For example; Add in "blue" if the object is blue.
Click on Components. And then click on the [...]. Click on Pricing and edit these values. These will determine how expensive the object will be. After this you can now change what can be used to break your object. You should see a thing saying "Mineable". This allows you to break the object with a Pick axe. If you don't want that, click on "mineable" then click the remove button. If you want to add a different way, click on "Add: ", then click on either "axeable" for Axes, "hammerable" for hammers, "mineable" for pick axes, "scytheable" for scythes, "shovelable" for shovels and finally "sweepable" for brooms. Close this window when you are done.
If you made an object larger than 16 x 16 x 16 (Or 24 x 24 x 24), then click on the arrow next to Component, Click on the arrow next to size and then edit the x,y and z. These values says how many tiles in each direction does this take up. For example if your object is 24 voxels, then set y to 2.
Scroll down and Click on Voxels. And then click on the [...]. Now with the open file window open, head to the model you made in #Creating the Model and open that.
Scroll down and Click on Attach to Above. And then click on the dropdown arrow and select the appropriate action. Do the same for Attach to Side and Attach to Below. These make the object try to move upwards/downwards/to the side depending on other tiles around.
Click on Attachment Directions. And then click on the drop down arrow. This determines the directions other objects can be placed on this object. For example; selecting "yp" will allow you to place the another object ontop of this object. Crtl + Click to select multiple directions.
Click on Placement Directions. And then click on the drop down arrow. This determines in what directions this object can be placed. For example; selecting "yn" will allow you to place the object ontop of other objects. Crtl + Click to select multiple directions.

With that, hit Crtl+S to save the file. And then go to File -> All Assets -> Build and Validate Assets. If this succeeds, then HURRAY! you have a new tile in the game. If it fails, try and read the error to see what you have done wrong. If you are confused then go to the #Modding channel on Discord and ask there.

Adding the Tile Object via Text Files

Follow Modding#Using a Text Editor to Create Mods in order to be properly set up for this step.

Move the Model to the mods folder and create a text file, with the same name as the model, and rename its extension to *.tile. After creating this file, open it up in the text editor of your choice by right clicking the file and choosing open. You may want to force set the default program as well. Once this file is open copy the following template into the file.

{
  "__inherits": "staxel/tileObject/base.config",
  "code": "staxel.tileObject.office.Computer",
  "voxels": "staxel/tileObject/office/Computer.qb",
  "randomizePosition": false,
  "categories": [
    "computer",
    "office",
    "furniture",
    "misc",
    "decoration",
    "desk",
    "white"
  ],
  "pricing": {
    "value": 2000.0,
    "sellPrice": 1200.0
  },
  "searchable": true
}

If you have a tile that is larger than 1 square, you will need to include a "compound" section in there as well. More information listed below.

Change the path listed beside "voxels" to be along the lines of mods/YourModName/YourTileName.qb as this tells the game where to find your tile. Next change the "code" to be the same but replace "/" with ".".

If your tile is greater than 16 x 16 x 16, add the following to the file, making sure that comma's are place before any new line.

  "compound" : {
    "size" : {
      "x" : 1,
      "y" : 1,
      "z" : 1,
    }
  }

Edit the x,y and z values as these values says how many tiles in each direction does this take up. For example if your object is 24 voxels, then set y to 2.

After you have done editing the file, head to gamedata/bin/ folder, and start up Staxel.ContentBuilder.exe. When this has started up, click "Validate Resources" and wait until the progress bar has done. And with that you should have a working item. If you are confused then go to the #Modding channel on Discord and ask there.

A small explanation of the *.tile file

Feel free to skip this explanation if you "Just want to get the damn thing done!"

"__inherits" : Simply put, this tells the game to grab information from another file. Simply leaving this alone is fine, however you could replace "base" with the name of any config tile found in the same folder. (That is staxel/tileObject/.) This allows for very simple files that don't have 20 different things in them all the time.

"code" : This line is basically the ID of the tile. It tells the game what to call the tile. To accomplish this, the easiest way is just make path that is required to get to the directory, starting from \mods\ and with every "\" being replaced with a ".". For example If the path was "\mods\Awesome\plant", a good code will be "mods.Awesome.plant". (A code of "bob" could work but not guaranteed to be unique.)

"voxels" : This is the path to the model that you have created. In our case you would put in something like "mods/modname/tilename.qb"

"randomizePosition" : Randomise position makes it so the tile will shift slightly every time you place it. Allowing for variation if the tiles gets place a lot.

"categories" : This is a list of stuff that the game can use to categorise your object. These are mostly used in searching for the object, however certain key phrases are used to sort the object in creative/shipping catalogue. These phrases can be descriptors of what the object is, or what colour it is.

"pricing" : This property is what is known as a Component. Components are optional extras that can be added to files in order to provide more functionality to it. This particular one is the Pricing Component which allows the player to buy or sell the tile. "value" is the price you buy at and "sellPrice" is the price you sell at. A large number of these can found at Category:Component Modding.

Why is my object not placing on anything other than the ground?

This is a common issue that arises when creating mods. The config called "base", that was inherited above, has a specific setting which only allows placing on top of an object. This however can be "fixed" though, by adding another line, and editing it to your preference, in your *.tile file. This line is as follows;

"placementDirections" : ["xn", "xp"],

What this option does is that it takes a direction specified in the list, and allows you to place it in that direction. Simple as that. Now to allow it to be in the directions you want, you will need to understand what "xp" means. In the simplest terms, the first letter is the "axis", or direction, in which you want to travel in. Remember that there are three planes, "x", "y" and "z" for anything 3D. The second letter is whether you want to go forward or backwards in the direction. This is expressed as positive "p" or negative "n". There is also one last entry that can be added, "all". This setting makes it so it can be placed in any direction, although this is not recommended if your object doesn't attach to things in every direction.

For example, if you want to attach an object to the ceiling, you can add the entry "yp". "y" being the upwards direction and "p" being up.

If you don't know which direction to choose, for example knowing whether it's "x" or "z", or whether it's positive or negative; just try a direction out and see if it works. If it's off by 90 degrees then you have the wrong axis, or if it's off by 180 degrees you have travelled in the wrong direction on the same axis.

With that, your object should be placing in the right spots.

As a side note, there is an option which specifies the opposite direction, "What directions can other objects be attached to this object?". This is specified as "attachmentDirections" and uses the same settings as "placementDirections".

Creating a Material

This tutorial will be similar to the previous tutorial about objects. In theory, a material is the same as an object. Yet in the game materials have several upsides and downsides which make them different to objects.

Feel free to skip the list below if you don't care what these changes are.

Advantages

Disadvantages

Materials have the ability to have "merging" areas. These areas are used to connect the material to other bits of material, allowing you to have connected textures.
Materials will render as simpler cubes at lower levels of LOD. This keeps your object visible for longer than a normal object, yet allows the game to optimise it.
Gives a simple way of having a block be larger than a cube (16x16x16) without specifing the size.

Materials take up more hard drive space than a normal object. This is because the file itself stores more voxels than before.
Cannot be larger than 32 voxels in width or length. Even more than 24 in any direction can be a pain for the user to work with.

Creating a material

Follow #Creating a In-game object tutorial to create an object. This object, should at minimum be a 16x16x16 block but larger sizes are fine so long as they aren't too much larger (Keep it below 24 voxels in any one direction) should be the same amount of voxel in the width and length. Height should not be much larger than 20-24 either.

After you have done this, head to gamedata/bin/ and start up Staxel.ContentBuilder.exe, and then click the "Material from tile" button. Navigate to your tile that you have just built and open that up. It will then create another file that appends ".material.qb". This file is now the file that the game can use as a material. Feel free to rename this file, and/or get rid of the original file.

As a quick check, open up the material file in your favourite voxel editor and check if it was what you wanted before continuing. As a note this new file is very large. Some editors may have troubles with either displaying the entire file, such as MagicaVoxel, or may appear to not run smoothly. We recommend Qubicle when modifying these Material tiles as they handle them fairly well.

If you want to know more about how material QB's are set up and how to manually edit them try this tutorial on editing and creating materials.

Loading the material in the game

Before starting this step, open up the Staxel launcher and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them. If you ever do come to see "Begin Update", remove the files from the \mods\ before starting.

Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Go to the \mods\ folder inside your Staxel installation and create a new folder with the name you want to call the mod. Once that is done, move the material file that you created before in that folder that was created.

The next thing to do is to create a file with the extension *.tile, a good practice would be to name it the same as the model. After creating this object open it up in the text editor of your choice by right clicking the file and choosing open. You may want to set the default program to Notepad or whatever program you want to as this will avoid the need to right click every time. Once this file is open copy the following template into the file.

{
  "__inherits": "staxel/tile/Shovelable.config",
  "voxels": "mods/modname/modmaterial.qb",
  "code": "mods.modname.modmaterial",
  "categories": ["block"],
  "pricing": {
    "value": 10.0,
    "sellPrice" : 6.0
  }
}

Change the temporary names of the stuff inside the text and then save the file. After you have done this, head to gamedata/bin/ and start up Staxel.ContentBuilder.exe.

When this has started up, click Validate Resources and wait until the progress bar has done. Congratulations, you have now added a material to Staxel.

To change what tool you want the user to use, change the file inherited to be "Mineable", "Axeable" or "Hammerable" instead of "Shovelable". To see an explanation of these variables go to #A small explanation of the *.tile file.

Useful Components

Due to the large number of components that can be used with Tiles, this section resides at Tiles/Components instead.

A couple of mentions however;

Pricing Component: Allows your tile to be bought and sold
Tool Components: Specify what tools can be used for this tile. This includes Components for breaking Tiles.

Config Options

"code"

Valid options (String): A unique string which identifies what Tile/Tileobject this is.

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

This option is required to uniquely identify any object or resource. This string must be unique to all other codes, but does not have any other requirements.

"kind"

Valid options (String): One of the following. "material", "aliased", "object", "aliasedObject" or "nothing"

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

This is the type of tile you would like to have. Each type has its own different properties. What each type does is as follows;

Material: This type is used for all full tiles. These tiles have the ability to change their look depending based on the tiles surrounding them (i.e. A prebuilt Auto-Tiling made specifically for tiles.). Tiles such as Dirt, Stone, Housing Bricks etc use this kind.
Aliased: This type is the version of Material that will change it's look during different seasons. Acts the same as Material, but requires the component Season Variants.
Object: This is for all tiles that do not act the same as Dirt or Stone. This is used for objects such as vases, tables or clocks. There is more freedom with Objects when compared to Materials but Objects are not as heavily optimised.
Aliased Object: This type is the version of Object that will change it's look during different seasons. Acts the same as Object, but requires the component Season Variants.
Compound: A special type of tile. This is used for a very specific tile, that is used to help Objects that are larger than one tile. This type is not useful for the vast majority of modding.
nothing: This is another special type. This is used on "Sky" tiles and is used to assume a completely empty tile. Again this type is not useful for the vast majority of modding.

Catalogue/Inventory Options

These are options that are used specifically for the Shipping Catalogue / Creative Menu and Inventory.

"categories"

Valid options (List of String): A list of valid strings.

Default Value: If not specified, will not have any user defined categories.

This is a list of strings which are used to identify what the tile actually is. These terms can all be searched for in the Catalogue/Creative Menu, but are also used in Totems and Achievements. Certain categories will appear under certain tabs in either menu. These include:

"block", "door", "floor"/"flooring", "flower", "furniture", "light", "plant", "tool", "window", "misc", "red", "orange", "yellow", "green", "blue", "purple", "pink", "white", "black" and "brown"

"descriptionImage"

Valid options (String): A string containing the path to an image file.

Default Value: If not specified, will not show an image in the description.

This is an image that will show up in the description window.

"searchable"

Valid options (Bool): True or False

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

This option specifies if the object whether the object will show up when it is searched for in the shop catalogue or the creative inventory. This is useful for objects with auto tiling info, as you only want a single version of that tile appearing.

"stackSizeLimit"

Valid options (Integer): Any valid positive integer.

Default Value: If not specified, will generally default to 999 items per stack.

This is the number of tiles that you can hold in a single slot of your inventory, or in a Dock.

Engine Options

These properties are mainly used by the engine and may not see much visual changes to the tiles.

"canBeGifted"

Valid options (Bool): True or False

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

Allows the tile to be given as a gift to a Villager NPC.

"CanBreakDuringFestival"

Valid options (Bool): True or False

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

Allows the tile to be broken during a Festival.

"canGrowFlowers"

Valid options (Bool): True or False

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

This option specifies if flowers, can grow on top of the block during world generation. This is also useful on tiles used in structures, which will allow randomised flowers to spawn to make the floor less barren.

"totemCeiling"

Valid options (Bool): True or False

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

This option specifies if the tile will act as a ceiling. This is useful to determine if the tile will be classified as a ceiling when detected by a totem.

"compound"

Compound is a (Blob) that contains variables specific for saying how large this tile is. This mainly sees use for TileObjects that are more than 1 tile in size. It is commonly written as:

"compound": {
  "size": {
    "x": 3,
    "y": 2,
    "z": 2
  },
  "specification": "CCC CCC CCC CXC"
}

This option is useless for Materials, as they should not be two tiles in size while they can be larger than one.

"size"

Valid options (Vector 3 - Integer): { "x": 0, "y": 0, "z": 0 }

Default Value: If not specified, will default to { "x": 1, "y": 1, "z": 1 }.

This is the size of the tile that is being represented. This should closely link to the models' size, with every 16 voxels in a single direction being a single tile. This size can differ from the models' size by up to, but not including, 1 tile in size. (i.e. If the model is 31 voxels wide, you can have either 1 or 2 tiles wide, but if it is 32 voxels wide, it must be 2 tiles wide.)

"specification"

Valid options (String): A string with X*Y*Z characters that are "X", "C" or "E". (Spaces and newlines are not counted as characters.)

Default Value: If not specified, this will default to a specification that includes an "X" as close to the bottom center as possible, and have values of "C" in every other tile.

Note: You do not need to mess with this property unless you need to do 1 of 2 things:

You want to specify some empty tiles within the object itself.
You want to change the positioning of the Core Tile "X" in order to make placement feel more natural.

This option specifies to the game how it should handle each tile in an object. Starting from the top layer, at the x = 0 and z = 0, it will read through each character in the string and apply it to the specific tile in the model. The order goes "Start at the top. Go down x, then increment z, go down x again. Once z is finished, decrement y and start again."

There are different options for each character which have specific effects;

"X" specifies the origin of the object. Every object must have 1 "X". All "X" follow the "C" specification as well. Although multiple can be applied (thus spawning multiple versions of the object) it is not recommended to have more than one "X".
"C" specifies that nothing should be placed in this tile. Set this for tiles in which the object actually occupies in the object.
"E" specifies that an object can be placed in this tile. Set this for any tile that is completely (or almost completely) empty.

For example: Lets take the lamp example from #size Lets say that the lamp, that has the size {"x": 2, "y": 4, "z": 1 } follows a pattern like;

 [*]
 [*]
 [*]
 [*] [*]

An appropriate specification variable for this is "CE CE CE XC" (Eight Characters used.)

For more in depth information precede to either This Guide or this collection of thoughts.

"interactActionTrigger"

Valid options (String): A string containing the code to a Entity Action.

Default Value: If not specified, will not play any action when interacting with this object.

This specifies a specific Entity Action that should be played upon interacting with this Tile. Entity Actions are most commonly animations, for the player, that get played.

"interactVerb"

Valid options (String): A string containing a Translation code.

Default Value: If not specified, will default to the normal interaction verb, "controlHint.verb.default.Interact" (Will display "Interact" in English.)

This is the translation string that will be used in order to make the right text appear in the control hints. This will only appear if the tile is actually interactable.

"mapping"

Valid options (Integer): Any valid positive integer.

Default Value: If not specified, will generally default to 0. 0 dynamically creates the tileid per world.

A fixed ID for the tiles in the world. For example the "sky" or blocks of nothing have a set ID of 1. Do not change this value from 0 unless you know what you are doing.

"merchantKind"

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

Default Value: If not specified, will not convert this this tile to a merchant home.

This option will, for all intents and purposes, turn this tile into a home for the Merchant that was specified. When this tile is place, the merchant will spawn and when it is broken the Merchant will disappear. This is used on tiles that also act as Totems.

Object Options

These are options meant for Tile Objects (i.e. Kind is "object" or "aliasedObject") only.

"variants"

Valid options (List of String ): A list of strings containing the path to a model file. Can also optionally contain "?size={16,16,16}?offset={0,0,0}" to only specify a section inside that file.

Default Value: If not specified, will rely on "voxels" to provide the model. Will override "voxels" if used.

A list of alternative models to use instead of the base model described in "voxels". The game will randomly choose a model from this list and not the "voxels" parameter upon placing the object. Use this if more than 1 tile look is used.

The optional parameter mentioned above can link multiple variants to the same file. What it does is take a section that is as large as "size" which is offsetted by "offset".

If you're making a Material see #"alts".

"voxels"

Valid options (String ): A string containing the path to a model file.

Default Value: If not specified, will rely on "variants" to provide the model. Will be overrided by "variants" if used.

The model to use to represent the object. If "variants" is not specified, this will be the only model used. Use this if only 1 tile look is used.

Material Options

These are options meant for Tile Objects (i.e. Kind is "material" or "aliased") only.

"layout"

Valid options (String ): Path to a config file containing a Tile Layout

Default Value: No default value is specified. Always need to provide your own. Will override "voxels" if used. However it is not recommended to change this from "tilelayout.config"

A list of alternative models to use instead of the base model described in "voxels". The game will randomly choose a model from this list and not the "voxels" parameter upon placing the object. Use this if more than 1 tile look is used.

The optional parameter mentioned above can link multiple variants to the same file. What it does is take a section that is as large as "size" which is offsetted by "offset".

"voxels"

Valid options (String ): A string containing the path to a model file.

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

The model to use to represent the object. This file is going to be fairly large. It should have a width of 304, a height of 112 and a depth of 48. Use other tiles as a reference to what should be in this file.

There is a converter provided in the Content Builder which will greatly speed up the editing of these files. This option will be written up at a later period of time.

Pathfinding Options

These are all the options that are made available for Pathfinding.

"frontSide"

Valid options (Vector 3 - Integer): { "x": 0, "y": 0, "z": 0 }

Default Value: If not specified, will default to { "x": 0, "y": 0, "z": 0 }. This is the automatic option.

This property sets a tile that will act as the "front side" of this tile. This is then specifically used as a place that NPC's will attempt to pathfind towards. (This avoids villagers pathfinding into blocks.)

"pathFindingNoCollision"

Valid options (Bool): True or False

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

This is whether or not this tile will be considered to be a "block" for pathfinding purposes. Objects such as Tall Grass, should have this set to false.

"pathFindingPenalty"

Valid options (Integer): Any positive integer number or -1.

Default Value: If not specified, will default to -1. -1 is the automatic penalty, which will adjust when building.

This allows you to fine tune how Villagers will use this object to pathfind on or through. If this block has a lower penalty than usual, such as the cobble pathway blocks, then villagers will prefer to walk on this block.

As mentioned in default value, if a value of -1 is used then it will automatically adjust the penalty. By default the penalty will follow these rules in order;

If the Kind = "compound", then penalty will equal 100.
Else if the Kind = "object", and the object has collision but does not have pathfinding collision (See #"pathFindingNoCollision") then it will have a penalty of 100.
Else if the Kind = "Object", but does not follow the above, the penalty will be 15.
Else if the Kind = "nothing", then penalty will equal 1.
Else if the the object has collision but does not have pathfinding collision then it will have a penalty of 10
Else the penalty will be 3.

Physics Options

These are all the options that are made available for adjusting how the player collides with the tile.

"bouncyness"

Valid options (Float): -1 and below to avoid bouncing, -1 to 0 for lower to normal bouncing, higher then 0 for more extreme bouncing.

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

This option describes how much a tile will bounce you back when colliding with it. The maths behind it is Bounce Vector * (Tile.Bouncyness + 1).

"collision"

Valid options (Bool): True or False

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

This option specifies whether or not a player, or other entities, can collide with the tile in question. Commonly flowers don't have collision, while most other objects do.

Tile Placement Options

These are all the options that affect tile placement.

"attachmentDirections" / "placementDirections"

Valid options (List of String ): A list of combinations which have one of (x,y,z) AND one of (p,n) (i.e. "xp" or "yn"), OR only have "all".

Default Value: If not specified, will default to having "all" sides be Attachable or Placeable.

"placementDirections" is the list of directions that the tile can be placed onto. For each options, they must have a direction (x, y or z. The three planar directions.) and whether to check in the positive or negative direction. (p or n respectively). Alternatively you can just use "all" to allow the object to be placed in any direction.

The complement of "placementDirections" is the "attachmentDirections" option, which specifies which directions objects can be placed on the specified object.

For example: Giving "placementDirections" ["yn", "yp"] will allow the object to be placed on the top or bottom of any object but not the sides while giving "attachmentDirections" ["yn", "yp"] will allow any other object to be placed on the top or bottom of this object.

"attachToAbove" / "attachToBelow" / "attachToSide"

Valid options (Bool): True or False

Default Value: If not specified, "attachToBelow" will default to True while the others will default to False.

Note: Do not use this on materials.

These options specifies if the object will try and align itself. Above and Below will attach themselves to the bottom/top of a block so that the object is flush with the other block. Side will attempt to attach to the block behind the object. These affects are recursively done for up to 3 objects?

For example: If you have a lantern, setting to "attachToAbove" true will properly attach to the ceiling, while setting to false may leave it floating in mid-air.

"floats"

Valid options (Bool): True or False

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

This specifies whether or not this tile can float in the air without destroying itself.

"orientationVariants"

Valid options (Bool): True or False

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

This option specifies if the object should be rotated randomly upon placement. If set to true on a pile of stone, it will place the stone in any of the 4 orientations when placed down. If false, allows the player to rotate the book themselves.

"randomizePosition" / "radomizeVerticalPosition"

Valid options (Bool): True or False

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

This option specifies if the object should be given a random horizontal/vertical displacement when it is placed.

For example: If set to true on a book tile, it will place the book and give it an offset of a few voxels in the x and z direction, while if false, it will always be in the standard position.

"variantsRandomizeVerticalPosition"

Valid options (List of Bool ): A list of bools for every single Alt. (Including voxels.)

Default Value: If not specified, will assume all will be false.

This option specifies if each alternative model for the object should be given a random vertical displacement when it is placed. The first object in the list affects the first alternative model. The second affects the second etc.

"wallPushOut"

Valid options (Bool): True or False

Default Value: If not specified, "attachToBelow" will default to True while the others will default to False.

Note: Do not use this on materials.

These options specifies if the object will try to make sure it will not collide with walls. This is useful for furniture

Rendering Options

These are all the options that affect only how the tile looks and not any other feature.

"alts"

Valid options (List of String ): A list of strings containing the path to a model file. Can also optionally contain "?size={16,16,16}?offset={0,0,0}" to only specify a section inside that file.

Default Value: If not specified, will rely on "voxels" to provide the model. Can be used in conjunction with "voxels".

A list of alternative models to use instead of the base model described in "voxels". The game will randomly choose a model from this list and the "voxels" parameter upon placing the object. Use this if more than 1 tile look is used.

The optional parameter mentioned above can link multiple variants to the same file. What it does is take a section that is as large as "size" which is offsetted by "offset".

If you're making a tileObject see #"variants".

"altsCount"

Valid options (Integer): Any valid positive integer.

Default Value: If not specified, will either default to 1 if there is no #"variants" property or however many "variants" are present if it is.

This represents how many different options there are. If only "alts" and "voxels" are used, this number should be the number of alternative models plus the base voxel. If "variants" are used then it should be the number of variants only.

For example: If the file contains "voxels" and 3 "alts" then altscount should equal 4. If the file contains 3 "variants" then it should be 3.

"aoFloor"

Valid options (Bool): True or False

Default Value: If not specified, will default to True. (Probably)

This tells the game whether to render a placed tile object with shadows as if it's been set on the ground. If your object has shadow "banding" then this is "True".

Changing this value will require a content re-build.

"emmisiveColor"

Valid options (Colour): A hexadecimal string that is is in ARGB format. (2 characters for Alpha, Red, Green, Blue)

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

The color in which an object with the option #"light" higher than 0 will emit when it is placed down.

For example: A light that has an emmisiveColor property of "FFFF0000" will emit a strong red light.

"light"

Valid options (Float): Any valid positive decimal number.

Default Value: If not specified, will not emit light.

Specifies how much light is to be emitted from the object. If set to 0, no light will be emitted

For example: Setting this option to 10.0 will let the object emit the same amount of light as an indoor lamp.

"open"

Valid options (Bool): True or False

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

A rendering option. Should only be true if the object is completely empty, like an air block. For all other cases, this is false.

"palette"

Valid options (String): A valid path to a *.colorcorrection file

Default Value: If not specified, will not have any colour correction.

This is an option that specifies to the game that it can overlay colours on top of the model. It points at another file which acts as a collection for images which define colours which will be used to vary colours. Most files don't need this, however if a tile is repeated often, such as the ground, it can be a handy thing to include.

"priority"

Valid options (Float): Any valid positive decimal number.

Default Value: If not specified, will not emit light.

This rendering option specifies this objects order to being rendered. Currently this is only used on objects of the "material" kind. The material with the higher priority will display over the top of the object with lower priority.

"smoothRecolorationOnPlace"

Valid options (Bool): True or False

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

This option will make the tile recolour itself to match the tiles nearby it. Should only be used if a palette is defined.

"solid"

Valid options (Bool): True or False

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

Should only be true if the object is completely full, such as a dirt block. Most materials will have this option true while most objects should not have this option.

Sound Options

These options include all ways of adding sound to a tile. Look at Sound for finding out what a Sound/Sound Group is and how it is defined.

"damageSoundGroup"

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

Default Value: If not specified, will not play any sounds when breaking.

This option specifies what group of sounds to play when the object is hit/destroyed.

"placeSoundGroup"

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

Default Value: If not specified, will not play any sounds when placing.

This option specifies what group of sounds to play when the object is placed.

"stepSoundGroup"

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

Default Value: If not specified, will not play any sounds when walking on/in tile.

This option specifies what group of sounds to play when the object is stepped on.

Tile State Entity Options

All these options require the block to be a Tile State Entity. Tile state entities, allow the player to directly affect the tile and also supports animations based on the entity's model and it's layers.

"animation"

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

Default Value: If not specified, will not have any animations specified.

This sets a Bone Animation file that is to be loaded alongside this tile. These animations can then be used by the Tile State Entity in order to adjust how the tile will move. The Layer names for #"voxels" needs to match with those specified in the animation.

"customRendererVoxels"

Valid options (String): A string containing the path to a model file.

Default Value: If not specified, will not have any custom voxels specified. If specified, will also force #"useCustomRendering" to True.

This option specifies another set of voxels that are to be used instead of #"voxels" or similar. These are generally used when placed down although can be used in differing circumstances. So usage of this property depends on how you use it.

"dockDefinition"

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

Default Value: If not specified, will not have any docks, interactable areas, and cannot be used for crafting or storage.

This is Dock Definition that is to be used alongside this tile. This allows use of the game's storage and crafting systems within this tile. It requires that #"tileStateKind" is set to "staxel.tileState.Dock" or similar in order to work.

"prefetchTileState"

Valid options (Bool): True or False

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

This option specifies whether or not the Tile State will be fetched immediately on place or replace. This should be used on tiles that need to be activated without the player actually looking at them. This includes Spawners, Totems and other Tile State Entities.

"spawnAction"

Valid options (String): A string containing the code to a Entity Action.

Default Value: If not specified, will not play any actions upon placing.

This option specifies what action is played when the object is spawned into the world, either by loading it up in the world or by placing the object. Useful for setting a Tile's State on startup (Like the Mixing Station's mixer.)

"tileStateKind"

Valid options (String): A string containing a specific tile state kind.

Default Value: If not specified, this tile will not be a Tile State Entity.

This option specifies what type of Tile State Entity this tile will be. This is mostly used for crafting stations and other interactable objects. This is not to be included on Tiles and objects that do not need any extra functionality.

"useCustomRendering"

Valid options (Bool): True or False

Default Value: If not specified, will default to false. Is always True if #"customRendererVoxels" is non-empty.

Whether or not a custom rendering style should be used. Certain Tile State Kinds will need this value to be enforced while others can just use normal rendering.

Usage Options

"autoTileInfo"

Auto Tile Info is a property which influences how Tiles are placed within the world. Using this property allows you to create fences that will turn at corners, and torches that always stick to a wall.

This property has it's own page, including how to use it, at Auto-Tiling.

"interactEffect"

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

Default Value: If not specified, will not play any effect on interaction.

This is the effect that will play when the Tile is interacted with. Also allows the tile to be interacted with.

"representativeTile"

Valid options (String): A string containing the code to another tile file.

Default Value: If not specified, will just give this tile instead of another tile.

This will set the tile that you will receive when pressing g on the tile and/or when using the Spawn On Break Component. This is most useful when using #"autoTileInfo" as this allows you to only need one tile which has auto tiling on it.

"unbreakable"

Valid options (Bool): True or False

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

This option specifies whether a person can break the object after it is placed in the world. Should never be set to true, unless there is something that is set to remove this tile. This option does override the need to add any components for breaking the tile.

@@ Line 9: / Line 9: @@
-= Creating a In-game object =
+= Creating a Tile-Object =
-There are two types of physical objects that can be placed in the world. The first of these types is known as an object. This covers everything from a fence to plants. The only things not covered by this are known as "Materials". Materials are everything that makes a full block, that is to say objects like dirt and wood fall under this category. This tutorial will cover how to implement an object into Staxel.
+In Staxel, everything that is placeable is known as a Tile. There are two different main types of Tiles that can be placed in the worlds.
+* '''Materials''': Tiles that follow this strict design. An example of this is; [[Media:Qubicle.png]]. This allows tiles to render at a very far distances.
+* '''Tile Objects''': Everything else.
+This tutorial will be focusing on the second option. This option covers everything from a fences to plants, from tables to barrels and everything else in between. Blocks such as Dirt, Wood and stone are not covered in this tutorial but in [[#Creating a Material]].
+'''Before you start this tutorial, be sure to head through [[Modding#Getting Started with Staxel Modding]].'''
+If you are working with the Staxel Launcher then after going through the setup tutorial,  then open it up  and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them.
+If you ever do come to see "Begin Update", remove the files from the <code>\mods\</code> before starting. Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Make sure that all files are already ready in the <code>\mods\</code> folder.
-'''Be sure that before starting, you go through [[Modding#Setting up for Mod Creation]] to avoid pain that may arise during the creation of your mod'''
 == Creating the Model ==
-The specifics of this step will vary on what type of modelling software that you use, however here are some general tips.
+Creating the model is the hardest part of this section. After having gone through the setup tutorial, you will have chosen a modelling program. Before creating a model, you will need to setup the size of the model. In Qubicle, select the box and then size box in the right bar. The following window will appear;
-* Keep the Bounding Box, the box which tells you where you can build, in increments of '''<tt>16</tt>'''. (Such as '''<tt>16x16x16</tt>''', '''<tt>16x32x16</tt>''', '''<tt>48x48x48</tt>''' etc) This allows you to allign the block within the tile.
+[[File:Resizer.png]]
-* Keep in mind the size of the object. The player is roughly 2.5-3 blocks high, 1.5-2 blocks wide, something like sizing can be easily lost when working on an object by itself.
-* The maximum size of an object is 5 blocks in each direction, this is to avoid issues with the block that could appear in game. If you want to make something larger than this, try seeing how you can break the block up into simpler parts. Can you break a section that has a repeating pattern into a single block? Do you want to let players choose the pattern instead?
+This shows you how many voxels your object will take. In Staxel, a single Tile has the size <code>16 x 16 x 16</code>. For this tutorial, try to keep the size of the object at or below <code>24 x 24 x 24</code> however you can go up to <code>80 x 80 x 80</code>. If you do go above <code>24 x 24 x 24</code>, you will just need to do an extra step later.
+While the above points out how to see/change the size in Qubicle, all other programs will have a similar ways to change the max size of the model. Beyond this, it's to you to make what you want. Here are some tips that might help you out.
+The specifics of this step will vary on what type of modelling software that you use, however here are some general tips.
-Now if you are having trouble with creating a model there are a couple of things that can help:
-* As voxel art is not a highly common practice (though it is becoming more common), many pixel art tutorials will help with understanding how to create voxels as the same underlying principles still apply in 3D.
 * Try looking up an object and try recreating that. It can be helpful to view it from the object from different angles.
+* Voxel art is not a highly common practice and therefore there aren't many tutorials. However many pixel art tutorials will help with understanding how to create voxels as the same underlying principles still apply in 3D.
+* Keep in mind the size of the object. The player is roughly 2-3 blocks high, 1-1.5 blocks wide. Sizing is easily lost when working on an object by itself.
+* If working with programs that let you place voxels outside the box, make sure that all voxels are inside of the box before exporting. (Needed for VoxelShop, which if certain settings are used, will only output what is inside the box.)
-Once you are done, you will need to do one thing. Most programs will have their own format for storing voxel models. For example Magica Voxel stores them as '''<tt>*.vox</tt>''' and Voxel Studio stores them as '''<tt>*.vsd</tt>'''. Staxel uses only one format for now, the '''<tt>*.qb</tt>''' file created by Qubicle. As this is a popular format, most of the software avaliable have a way to <tt>"export"</tt> to a '''<tt>*.qb</tt>''' file. So when your model is down, be sure to export the file to the right type, otherwise you will run into issues later. Don't forget about the folder that was setup in the steps before. It's a lot easier to keep track of things when they are all in the same folder.
+Once you are done, you will need to "export" or save the file. Most programs will have their own format for storing voxel models. For example Magica Voxel stores them as '''<tt>*.vox</tt>''' and Voxel Studio stores them as '''<tt>*.vsd</tt>'''. Staxel uses only one format, the '''<tt>*.qb</tt>''' file created by Qubicle. As this is a popular format, most software available have a way to <tt>"export"</tt> to a '''<tt>*.qb</tt>''' file. So when your model is done, be sure to export to '''<tt>*.qb</tt>'''.
-== Adding the Model to Staxel ==
+== Adding the Tile Object to Staxel ==
+As mentioned in the Setup, there are two main ways of adding the model to Staxel. Both of these ways were mentioned in [[Modding#Getting Started with Staxel Modding]].
-Before starting this step, open up the Staxel launcher and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them. If you ever do come to see "Begin Update", remove the files from the <code>\mods\</code> before starting.
+=== Adding the Tile Object via Asset Manager ===
+Follow [[Modding#Using the AssetManager to Create Mods]] to open up the Asset Manager. With the Asset Manager open, head to <code>View -> Tiles and Objects -> Tile Assets</code>. When the new window is open head to <code>Asset -> Add -> New Asset</code> and the following window will show up.
+[[File:Asset Manager - New Tile Asset.png]]
-Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Go to the <code>\mods\</code> folder inside your Staxel installation and create a new folder with the name you want to call the mod. Once that is done, move the '''<tt>*.qb</tt>''' file that you created before in that folder that was created.
+First click on the button Asset Path and navigate upwards to the <code>/content/</code> folder. Once there, open the <code>/mods/</code> folder and create a new folder. Name this new folder to what you want the mod to be called and then open this new folder. When you open this folder give the asset a name and click save. After this is done, click the kind dropdown and change it to "Object". After this press OK.
-The next thing to do is to create a file with the extension '''<tt>*.tile</tt>''', a good practice would be to name it the same as the model. After creating this object open it up in the text editor of your choice by right clicking the file and choosing open. You may want to set the default program to Notepad or whatever program you want to as this will avoid the need to right click every time. Once this file is open copy the following template into the file.
+After the asset is created, it will have been automatically selected. With that it is now time to tell the game what you want to do with this tile. The following set of steps highlight the important properties, however you can mess with any property.
+# Click on Categories. And then click on the [...]. You can now add a bunch of terms you want to be able to search for your object. For example; Add in "blue" if the object is blue.
+# Click on Components. And then click on the [...]. Click on Pricing and edit these values. These will determine how expensive the object will be. After this you can now change what can be used to break your object. You should see a thing saying "Mineable". This allows you to break the object with a Pick axe. If you don't want that, click on "mineable" then click the remove button. If you want to add a different way, click on "Add: ", then click on either "axeable" for Axes, "hammerable" for hammers, "mineable" for pick axes, "scytheable" for scythes, "shovelable" for shovels and finally "sweepable" for brooms. Close this window when you are done.
+# If you made an object larger than <code>16 x 16 x 16</code> (Or <code>24 x 24 x 24</code>), then click on the arrow next to Component, Click on the arrow next to size and then edit the x,y and z. These values says how many tiles in each direction does this take up. For example if your object is 24 voxels, then set y to 2.
+# Scroll down and Click on Voxels. And then click on the [...]. Now with the open file window open, head to the model you made in [[#Creating the Model]] and open that.
+# Scroll down and Click on Attach to Above. And then click on the dropdown arrow and select the appropriate action. Do the same for Attach to Side and Attach to Below. These make the object try to move upwards/downwards/to the side depending on other tiles around.
+# Click on Attachment Directions. And then click on the drop down arrow. This determines the directions other objects can be placed on this object. For example; selecting "yp" will allow you to place the another object ontop of this object. Crtl + Click to select multiple directions.
+# Click on Placement Directions. And then click on the drop down arrow. This determines in what directions this object can be placed. For example; selecting "yn" will allow you to place the object ontop of other objects. Crtl + Click to select multiple directions.
+With that, hit Crtl+S to save the file. And then go to <code>File -> All Assets -> Build and Validate Assets</code>. If this succeeds, then HURRAY! you have a new tile in the game. If it fails, try and read the error to see what you have done wrong. If you are confused then go to the #Modding channel on Discord and ask there.
+=== Adding the Tile Object via Text Files ===
+Follow [[Modding#Using a Text Editor to Create Mods]] in order to be properly set up for this step.
+Move the Model to the mods folder and create a text file, with the same name as the model, and rename its extension to '''<tt>*.tile</tt>'''. After creating this file, open it up in the text editor of your choice by right clicking the file and choosing open. You may want to force set the default program as well. Once this file is open copy the following template into the file.
 <pre>
 {
-   "__inherits": "staxel/tileObject/Base.config",
+   "__inherits": "staxel/tileObject/base.config",
-   "voxels": "mods/modname/modelname.qb",
+  "code": "staxel.tileObject.office.Computer",
-   "code": "mods.modname.modelname",
+   "voxels": "staxel/tileObject/office/Computer.qb",
+   "randomizePosition": false,
    "categories": [
-     "cat1",
+     "computer",
-     "cat2",
+     "office",
+    "furniture",
+    "misc",
+    "decoration",
+    "desk",
+    "white"
    ],
    "pricing": {
-     "value": 20.0
+     "value": 2000.0,
-   }
+    "sellPrice": 1200.0
+   },
+  "searchable": true
 }
 </pre>
-''If you have a tile that is larger than 1 square, you will need to include a '''<tt>"compound"</tt>''' section in there as well. Look at [[Modding Configs#"compound"]] for more info.''
+''If you have a tile that is larger than 1 square, you will need to include a '''<tt>"compound"</tt>''' section in there as well. More information listed below.''
-Change the temporary names of the stuff inside the text and then save the file. After you have done this, head to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''.
+Change the path listed beside "voxels" to be along the lines of <code>mods/YourModName/YourTileName.qb</code> as this tells the game where to find your tile. Next change the "code" to be the same but replace "/" with ".".
+If your tile is greater than <code>16 x 16 x 16</code>, add the following to the file, making sure that comma's are place before any new line.
+<pre>
+  "compound" : {
+    "size" : {
+      "x" : 1,
+      "y" : 1,
+      "z" : 1,
+    }
+  }
+</pre>
+Edit the x,y and z values as these values says how many tiles in each direction does this take up. For example if your object is 24 voxels, then set y to 2.
-When this has started up, click '''<tt>Validate Resources</tt>''' and wait until the progress bar has done. Congratulations, you have now added a tile to Staxel.
+After you have done editing the file, head to <code>gamedata/bin/</code> folder, and start up <code>Staxel.ContentBuilder.exe</code>. When this has started up, click "Validate Resources" and wait until the progress bar has done. And with that you should have a working item. If you are confused then go to the #Modding channel on Discord and ask there.
 === A small explanation of the *.tile file ===
 Feel free to skip this explanation if you "Just want to get the damn thing done!"
-'''<tt>"__inherits"</tt>''' : Simply put, this tells the game "Hey if I'm missing something, look in this file for the stuff." In our case, simply leaving this alone is fine, however you could replace <tt>"base"</tt> with the name of any config tile found in the same folder. (That is <code>"staxel/tileObject/"</code>.) In essence this is used to remove a number of redundent text that would need to appear in every block.
+'''<tt>"__inherits"</tt>''' : Simply put, this tells the game to grab information from another file. Simply leaving this alone is fine, however you could replace <tt>"base"</tt> with the name of any config tile found in the same folder. (That is <code>staxel/tileObject/</code>.) This allows for very simple files that don't have 20 different things in them all the time.
-'''<tt>"code"</tt>''' : This line is basically the ID of the tile. It tells the game what to call the tile. Just like in Minecraft, each tile code must be unique to each other. To accomplish this, the easiest way is just make path that is required to get to the directory, starting from <code>\mods\</code> and with every <tt>"\"</tt> being replaced with a <tt>"."</tt>. For example If the path was <code>"\mods\Awesome\plant"</code>, a good code will be <code>"mods.Awesome.plant"</code> however it isn't necessary. (A code of <code>"bob"</code> could work but might not be unique)
+'''<tt>"code"</tt>''' : This line is basically the ID of the tile. It tells the game what to call the tile. To accomplish this, the easiest way is just make path that is required to get to the directory, starting from <code>\mods\</code> and with every <tt>"\"</tt> being replaced with a <tt>"."</tt>. For example If the path was <code>"\mods\Awesome\plant"</code>, a good code will be <code>"mods.Awesome.plant"</code>. (A code of <code>"bob"</code> could work but not guaranteed to be unique.)
 '''<tt>"voxels"</tt>''' : This is the path to the model that you have created. In our case you would put in something like <code>"mods/modname/tilename.qb"</code>
-'''<tt>"categories"</tt>''' : This is a list of stuff that the game can use to categorise your object. These are mostly used in searching for the object, however certain key phrases are used to sort the object in creative/shipping catalogue. A list of those categories are mentioned at [[Modding Configs#"categories"]]
+'''<tt>"randomizePosition"</tt>''' : Randomise position makes it so the tile will shift slightly every time you place it. Allowing for variation if the tiles gets place a lot.
-'''<tt>"pricing"</tt>''' : This property sets how much it would cost in the shipping catalogue. Keeping this the same is fine.
+'''<tt>"categories"</tt>''' : This is a list of stuff that the game can use to categorise your object. These are mostly used in searching for the object, however certain key phrases are used to sort the object in creative/shipping catalogue. These phrases can be descriptors of what the object is, or what colour it is.
+'''<tt>"pricing"</tt>''' : This property is what is known as a Component. Components are optional extras that can be added to files in order to provide more functionality to it. This particular one is the [[Pricing Component]] which allows the player to buy or sell the tile. "value" is the price you buy at and "sellPrice" is the price you sell at. A large number of these can found at [[:Category:Component Modding]].
 == Why is my object not placing on anything other than the ground? ==
-This is a common issue that arises when creating mods. The config that was inherited above, has a specific setting which only allows placing on top of an object. This however can be "fixed" though, by adding another line, and editing it to your preference, in your '''<tt>*.tile</tt>''' file. This line is as follows;
+This is a common issue that arises when creating mods. The config called "base", that was inherited above, has a specific setting which only allows placing on top of an object. This however can be "fixed" though, by adding another line, and editing it to your preference, in your '''<tt>*.tile</tt>''' file. This line is as follows;
 <pre>
@@ Line 87: / Line 150: @@
 For example, if you want to attach an object to the ceiling, you can add the entry '''<tt>"yp"</tt>'''. '''<tt>"y"</tt>''' being the upwards direction and '''<tt>"p"</tt>''' being up.
-If you don't know which direction to choose, for example knowing whether it's '''<tt>"x"</tt>''' or '''<tt>"z"</tt>''', or whether it's positive or negative; just try a direction out and see if it works. If it's off by 90 degrees then you have the wrong axis, or if it's off by 180 degrees you have traveled in the wrong direction on the same axis.
+If you don't know which direction to choose, for example knowing whether it's '''<tt>"x"</tt>''' or '''<tt>"z"</tt>''', or whether it's positive or negative; just try a direction out and see if it works. If it's off by 90 degrees then you have the wrong axis, or if it's off by 180 degrees you have travelled in the wrong direction on the same axis.
 With that, your object should be placing in the right spots.
@@ Line 93: / Line 156: @@
 As a side note, there is an option which specifies the opposite direction, "What directions can other objects be attached to this object?". This is specified as '''<tt>"attachmentDirections"</tt>''' and uses the same settings as '''<tt>"placementDirections"</tt>'''.
-= Creating a material =
+= Creating a Material =
 This tutorial will be similar to the previous tutorial about objects. In theory, a material is the same as an object. Yet in the game materials have several upsides and downsides which make them different to objects.
@@ Line 108: / Line 172: @@
 |
 * Materials take up more hard drive space than a normal object. This is because the file itself stores more voxels than before.
-* Cannot be larger than 32 voxels in width or length. Even more than 24 in any direction can be a pain to work with.
+* Cannot be larger than 32 voxels in width or length. Even more than 24 in any direction can be a pain for the user to work with.
 |}
 == Creating a material ==
-Follow [[#Creating a In-game object]] tutorial to create an object. This object, should at minimum be a 16x16x16 block but larger sizes are fine so long as they aren't too much larger (Keep it below 28 voxels in any one direction) should be the same amount of voxel in the width and length. Height should not be much larger than 20-24 either.
+Follow [[#Creating a In-game object]] tutorial to create an object. This object, should at minimum be a 16x16x16 block but larger sizes are fine so long as they aren't too much larger (Keep it below 24 voxels in any one direction) should be the same amount of voxel in the width and length. Height should not be much larger than 20-24 either.
 After you have done this, head to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>''', and then click the '''"Material from tile"''' button. Navigate to your tile that you have just built and open that up. It will then create another file that appends <tt>'''".material.qb"'''</tt>. This file is now the file that the game can use as a material. Feel free to rename this file, and/or get rid of the original file.
-As a quick check, open up the material file in your favourite voxel editor and check if it was what you wanted before continuing.
+As a quick check, open up the material file in your favourite voxel editor and check if it was what you wanted before continuing. As a note this new file is very large. Some editors may have troubles with either displaying the entire file, such as MagicaVoxel, or may appear to not run smoothly. We recommend Qubicle when modifying these Material tiles as they handle them fairly well.
+If you want to know more about how material QB's are set up and how to manually edit them try [[User:Toketsupuurin/MaterialTutorial|this tutorial on editing and creating materials.]]
 == Loading the material in the game ==
 Before starting this step, open up the Staxel launcher and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them. If you ever do come to see "Begin Update", remove the files from the <code>\mods\</code> before starting.
@@ Line 137: / Line 201: @@
    "categories": ["block"],
    "pricing": {
-     "value": 10.0
+     "value": 10.0,
+    "sellPrice" : 6.0
    }
 }
@@ Line 149: / Line 214: @@
-= Configuration Options =
+= Useful Components =
-This is a list of all options that you can add into a tile, complete with information on what they do.
+Due to the large number of components that can be used with Tiles, this section resides at [[Tiles/Components]] instead.
+A couple of mentions however;
+* [[Pricing Component]]: Allows your tile to be bought and sold
+* [[Tiles/Components#Components for Specific Tools|Tool Components]]: Specify what tools can be used for this tile. This includes Components for breaking Tiles.
-== Engine ==
-=== "code" ===
-'''Valid options (String): <code>Any valid string. Common to make the string the path to the model but with periods [.] replacing slashes [/] </code>'''
-This option is required to uniquely identify any object or resource. This path '''must''' be unique to all other codes, but does not have any other requirements.
+= Config Options =
+== "code" ==
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A unique string which identifies what Tile/Tileobject this is.</code>'''
-For example: Having the code <code> "mods.fountain.fountain"</code> creates an object that has the handle "mods.fountain.fountain"
+'''Default Value:''' No default value is specified. Always need to provide your own.
-=== "kind" ===
+This option is required to uniquely identify any object or resource. This string '''must''' be unique to all other codes, but does not have any other requirements.
-'''Valid options (String): <code>"object", "material", "nothing"</code>'''
-This option specifies what type of item is being specified by your file. In this case, it tells the game whether to treat the model as if its a material, where it shall construct the look in game based on how it's placed, verses an object which it will not care about the model.
+== "kind" ==
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>One of the following. "material", "aliased", "object", "aliasedObject" or "nothing"</code>'''
-=== "canGrowFlowers" ===
+'''Default Value:''' No default value is specified. Always need to provide your own.
-'''Valid options (bool): <code>Either true or false</code>'''
-This option specifies if flowers, can grow on top of the block during world generation. Helpful when a block is used in Structures.
+This is the type of tile you would like to have. Each type has its own different properties. What each type does is as follows;
+* [[Tile/Material|Material]]: This type is used for all full tiles. These tiles have the ability to change their look depending based on the tiles surrounding them (i.e. A prebuilt Auto-Tiling made specifically for tiles.). Tiles such as Dirt, Stone, Housing Bricks etc use this kind.
+* [[Tile/Aliased|Aliased]]: This type is the version of Material that will change it's look during different seasons. Acts the same as Material, but requires the component [[Season Variants]].
+* [[Tile/Object|Object]]: This is for all tiles that do not act the same as Dirt or Stone. This is used for objects such as vases, tables or clocks. There is more freedom with Objects when compared to Materials but Objects are not as heavily optimised.
+* [[Tile/Aliased Object|Aliased Object]]: This type is the version of Object that will change it's look during different seasons. Acts the same as Object, but requires the component [[Season Variants]].
+* [[Tile/Compound|Compound]]: A special type of tile. This is used for a very specific tile, that is used to help Objects that are larger than one tile. This type is not useful for the vast majority of modding.
+* [[Tile/Nothing|nothing]]: This is another special type. This is used on "Sky" tiles and is used to assume a completely empty tile. Again this type is not useful for the vast majority of modding.
+== Catalogue/Inventory Options ==
+These are options that are used specifically for the Shipping Catalogue / Creative Menu and Inventory.
+=== "categories" ===
+'''Valid options ([[Modding_Key_Terms#List|List]] of [[Modding_Key_Terms#String|String]]): <code>A list of valid strings.</code>'''
+'''Default Value:''' If not specified, will not have any user defined categories.
+This is a list of strings which are used to identify what the tile actually is. These terms can all be searched for in the Catalogue/Creative Menu, but are also used in [[Totems]] and [[Achievements]]. Certain categories will appear under certain tabs in either menu. These include:
+<code>"block", "door", "floor"/"flooring", "flower", "furniture", "light", "plant", "tool", "window", "misc", "red", "orange", "yellow", "green", "blue", "purple", "pink", "white", "black" and "brown"</code>
+=== "descriptionImage" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the path to an image file.</code>'''
+'''Default Value:''' If not specified, will not show an image in the description.
+This is an image that will show up in the description window.
+=== "searchable" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
+'''Default Value:''' If not specified, will default to False.
+This option specifies if the object whether the object will show up when it is searched for in the shop catalogue or the creative inventory. This is useful for objects with auto tiling info, as you only want a single version of that tile appearing.
+=== "stackSizeLimit" ===
+'''Valid options ([[Modding_Key_Terms#Integer|Integer]]): <code>Any valid positive integer.</code>'''
+'''Default Value:''' If not specified, will generally default to 999 items per stack.
+This is the number of tiles that you can hold in a single slot of your inventory, or in a [[Docks|Dock]].
+== Engine Options ==
+These properties are mainly used by the engine and may not see much visual changes to the tiles.
+=== "canBeGifted" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
+'''Default Value:''' If not specified, will default to True.
+Allows the tile to be given as a gift to a [[Villager NPCs|Villager NPC]].
+=== "CanBreakDuringFestival" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
+'''Default Value:''' If not specified, will default to True.
+Allows the tile to be broken during a [[Festivals|Festival]].
+=== "canGrowFlowers" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
+'''Default Value:''' If not specified, will default to False.
+This option specifies if flowers, can grow on top of the block during world generation. This is also useful on tiles used in structures, which will allow randomised flowers to spawn to make the floor less barren.
+=== "totemCeiling" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
+'''Default Value:''' If not specified, will default to False.
+This option specifies if the tile will act as a ceiling. This is useful to determine if the tile will be classified as a ceiling when detected by a totem.
 === "compound" ===
-Compound is a container for multiple variables. It is written as:
+Compound is a ([[Modding_Key_Terms#Blob|Blob]]) that contains variables specific for saying how large this tile is. This mainly sees use for TileObjects that are more than 1 tile in size. It is commonly written as:
 <pre>"compound": {
    "size": {
      "x": 3,
-     "y": 1,
+     "y": 2,
      "z": 2
    },
-   "specification": "\n\tCC XC CC\n\t"
+   "specification": "CCC CCC CCC CXC"
 }</pre>
-This option is primarily for objects that don't fit into a 1x1 tile space, such as a lamp post or a table. The size and specification variables are explained below.
+This option is useless for Materials, as they should not be two tiles in size while they can be larger than one.
 ==== "size" ====
-Size is another multiple variable container. It is written as:
+'''Valid options ([[Modding_Key_Terms#Vector 3|Vector 3]] - [[Modding_Key_Terms#Integer|Integer]]): <code>{ "x": 0, "y": 0, "z": 0 }</code>'''
-<pre>"size": {
-  "x": 3,
-  "y": 1,
-  "z": 2
-},</pre>
-The variables of x, y and z are integer inputs stating how many tiles the object occupies in the x,y and z directions. If the object is not a multiple of 16, you will need to round upwards to the next multiple of 16.
+'''Default Value:''' If not specified, will default to  { "x": 1, "y": 1, "z": 1 }.
-For example: Lets say we have a lamp post that is 4 tiles high, 1 tile in length and 2 tiles in width we would then have a parameter of <code>{"x" : 1, "y" : 4, "z" : 2}</code>
+This is the size of the tile that is being represented. This should closely link to the models' size, with every 16 voxels in a single direction being a single tile. This size can differ from the models' size by up to, but not including, 1 tile in size. (i.e. If the model is 31 voxels wide, you can have either 1 or 2 tiles wide, but if it is 32 voxels wide, it must be 2 tiles wide.)
-==== "specification" ====
-'''Valid options (String): <code>A string comprised of "X", "C" or "E" that has exactly the same number of characters as the number of tiles the object occupies. (Not counting whitespace. E.g. spaces, tabs and newlines.)</code>'''
+==== "specification" ====
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string with X*Y*Z characters that are "X", "C" or "E". (Spaces and newlines are not counted as characters.)</code>'''
-''You do not need to add a specification, unless you want to allow an empty tile to be built in.''
+'''Default Value:''' If not specified, this will default to a specification that includes an "X" as close to the bottom center as possible, and have values of "C" in every other tile.
-This option specifies to the game how it should handle each tile in an object. Starting from the top layer, at the x = 0 and z = 0, it will read through each character in the string and apply it to the specific tile in the model. The order goes "Go down x, then increment z, go down x again. Once z is finish decrement y and start again". The different options are;
+Note: You do not need to mess with this property unless you need to do 1 of 2 things:
+# You want to specify some empty tiles within the object itself.
+# You want to change the positioning of the Core Tile "X" in order to make placement feel more natural.
+This option specifies to the game how it should handle each tile in an object. Starting from the top layer, at the x = 0 and z = 0, it will read through each character in the string and apply it to the specific tile in the model. The order goes "Start at the top. Go down x, then increment z, go down x again. Once z is finished, decrement y and start again."
+There are different options for each character which have specific effects;
 *<code>"X"</code> specifies the origin of the object. Every object must have 1 <code>"X"</code>. All <code>"X"</code> follow the <code>"C"</code> specification as well. Although multiple can be applied (thus spawning multiple versions of the object) it is not recommended to have more than one <code>"X"</code>.
 *<code>"C"</code> specifies that nothing should be placed in this tile. Set this for tiles in which the object actually occupies in the object.
 *<code>"E"</code> specifies that an object can be placed in this tile. Set this for any tile that is completely (or almost completely) empty.
-For example: Lets take the lamp example from [[#size]] Lets say that the lamp follows a pattern like;
+For example: Lets take the lamp example from [[#size]] Lets say that the lamp, that has the size  {"x": 2, "y": 4, "z": 1 } follows a pattern like;
 <pre> [*]
   [*]
   [*]
   [*] [*]</pre>
-An appropriate specification variable for this is <code>"CE CE CE CX"</code>
+An appropriate specification variable for this is <code>"CE CE CE XC"</code> (Eight Characters used.)
 For more in depth information precede to either [http://forums.playstaxel.com/threads/invalid-tutorial-delete.401/ This Guide] or [http://forums.playstaxel.com/threads/collision-musings.389/ this collection of thoughts].
-=== "pathFindingNoCollision" ===
+=== "interactActionTrigger" ===
-'''Valid options (bool): <code>Either true or false</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Entity Action]].</code>'''
-This option allows the pathfinding system to ignore the tile for pathfinding purposes.
+'''Default Value:''' If not specified, will not play any action when interacting with this object.
-=== "interactEffect" ===
+This specifies a specific Entity Action that should be played upon interacting with this Tile. Entity Actions are most commonly animations, for the player, that get played.
-'''Valid options (String): <code>Any valid effect code.</code>'''
-This will set the tile that you will receive when breaking or pressing g on the tile. This is available because when you place an object with auto-tile info, it can turn into another item with no info on what original tile was placed. By default, it will give the tile that is being made.
+=== "interactVerb" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing a [[Translation]] code.</code>'''
-=== "mapping" ===
+'''Default Value:''' If not specified, will default to the normal interaction verb, "controlHint.verb.default.Interact" (Will display "Interact" in English.)
-'''Valid options (Unsigned Int): <code>Any positive number.</code>'''
-A fixed ID for the tiles in the world. For example "sky" or blocks of nothing have a set ID of 1. Do not change this value from 0 unless you know what you are doing.
+This is the translation string that will be used in order to make the right text appear in the control hints. This will only appear if the tile is actually interactable.
-=== "pathFindingPenalty" ===
+=== "mapping" ===
-'''Valid options (Int): <code>Any positive or negative number.</code>'''
+'''Valid options ([[Modding_Key_Terms#Integer|Integer]]): <code>Any valid positive integer.</code>'''
-This option allows you to change how much NPC's prefer using this block as part of their path when compared to other blocks. Negative numbers are prefer to use (Lower penalty), while positive numbers are for avoiding (Higher penalty).
+'''Default Value:''' If not specified, will generally default to 0. 0 dynamically creates the tileid per world.
-== "dockInfo" ==
+A fixed ID for the tiles in the world. For example the "sky" or blocks of nothing have a set ID of 1. Do not change this value from 0 unless you know what you are doing.
-This option specifies a bunch of options for interacting with a tile.
-A Dock file includes;
-<pre>
-"dockInfo" : {
-  "allowStacksForAllSites" : false,
-  "craftingKeyword" : "",
-  "nameTagOffset" : { "x" : 0.0, "y" : 0.6, "z" : 0.0 },
-  "sites" : [ ],
-  "validDockables" : [ ],
-  "validCategories : [ ]
-}</pre>
-=== "allowStacksForAllSites" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
-An option to allow every site to allow stacking up to the stackSizeLimit.
+=== "merchantKind" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Merchant]] file.</code>'''
+'''Default Value:''' If not specified, will not convert this this tile to a merchant home.
-=== "craftingKeyword" ===
-'''Valid options (String): <code>Any valid string.</code>'''
-A word to describe what is done at the crafting station. For example, the baking station has "bake". Can be left empty for non-crafting objects.
+This option will, for all intents and purposes, turn this tile into a home for the Merchant that was specified. When this tile is place, the merchant will spawn and when it is broken the Merchant will disappear. This is used on tiles that also act as [[Totems]].
-=== "nameTagOffset" ===
+== Object Options ==
-'''Valid options (Vector 3F): <code> "nameTagOffset" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 } </code>
+These are options meant for Tile Objects (i.e. Kind is "object" or "aliasedObject") only.
-An option to set the nametag of the object in a different position. A value of 1, means that the nametag has moved 1 tile in that direction.
+=== "variants" ===
+'''Valid options ([[Modding_Key_Terms#List|List]] of [[Modding_Key_Terms#String|String]] ): <code>A list of strings containing the path to a model file. Can also optionally contain "?size={16,16,16}?offset={0,0,0}" to only specify a section inside that file.</code>'''
+'''Default Value:''' If not specified, will rely on "voxels" to provide the model. Will override "voxels" if used.
-=== "sites" ===
+A list of alternative models to use instead of the base model described in "voxels". The game will randomly choose a model from this list and not the "voxels" parameter upon placing the object. Use this if more than 1 tile look is used.
-Sites are a list of places in which you can interact with the object. A site for example may be the place where you store your objects in a wardrobe or where you interact with on a baking station.
-Sites are made of a seperate blob with it's own properties. These properties are as follow;
+The optional parameter mentioned above can link multiple variants to the same file. What it does is take a section that is as large as "size" which is offsetted by "offset".
-<pre>
-{
-  "siteName" : "oven",
-  "location" : { "x" : 0.0, "y" : 0.35, "z" : 0.0 },
-  "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0 },
-  "allowStacks" : true,
-  "compact" : false,
-  "craftTypeRestriction" : ["bake"],
-  "dockOneAtATime" : false,
-  "disallowManualDocking" : false,
-  "interactActionTrigger" : true,
-  "unDockEffect" : false,
-  "dimensionOverride" : { "x" : 0.0, "y" : 0.35, "z" : 0.0 },
-  "colliderOffset" :  { "x" : 0.0, "y" : 0.35, "z" : 0.0 }
-}
-</pre>
-==== "siteName" ====
+If you're making a Material see [[#"alts"]].
-'''Valid options (String): <code>Any valid string.</code>'''
-A string to name the site in question.
-==== "location" ====
+=== "voxels" ===
-'''Valid options (Vector 3F): <code> "location" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 } </code>
+'''Valid options ([[Modding_Key_Terms#String|String]] ): <code>A string containing the path to a model file.</code>'''
-Sets the location where the site will be. A unit of 1 is one block in that direction.
+'''Default Value:''' If not specified, will rely on "variants" to provide the model. Will be overrided by "variants" if used.
-==== "rotation" ====
+The model to use to represent the object. If "variants" is not specified, this will be the only model used. Use this if only 1 tile look is used.
-'''Valid options (Vector 3F): <code> "rotation" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 } </code>
-Sets the rotation of the site. A unit of 1 is one rotation?
-==== "allowStacks" ====
+== Material Options ==
-'''Valid options (Bool): <code>Either true or false</code>'''
+These are options meant for Tile Objects (i.e. Kind is "material" or "aliased") only.
-Allows the site to take more than one object. Overrides "allowStacksForAllSites" in DockInfo.
+=== "layout" ===
+'''Valid options ([[Modding_Key_Terms#String|String]] ): <code>Path to a config file containing a Tile Layout</code>'''
-==== "colliderOffset" ====
+'''Default Value:''' No default value is specified. Always need to provide your own. Will override "voxels" if used. However it is not recommended to change this from "tilelayout.config"
-'''Valid options (Vector 3F): <code> "colliderOffset" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 } </code>
-This offsets the collision of the site to be in a different spot than the place where it is docked.
+A list of alternative models to use instead of the base model described in "voxels". The game will randomly choose a model from this list and not the "voxels" parameter upon placing the object. Use this if more than 1 tile look is used.
-==== "compact" ====
+The optional parameter mentioned above can link multiple variants to the same file. What it does is take a section that is as large as "size" which is offsetted by "offset".
-'''Valid options (Bool): <code>Either true or false</code>'''
-This option sets it so that items placed in this space, gets rendered at a smaller size?
-==== "craftTypeRestriction" ====
+=== "voxels" ===
-'''Valid options (List of Strings): <code>Any valid string.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]] ): <code>A string containing the path to a model file.</code>'''
-A word to describe what is done at the site. Similar to Crafting Keyword. Can also use "combine".
+'''Default Value:''' No default value is specified. Always need to provide your own.
-==== "dimensionOverride" ====
+The model to use to represent the object. This file is going to be fairly large. It should have a width of 304, a height of 112 and a depth of 48. Use other tiles as a reference to what should be in this file.
-'''Valid options (Vector 3F): <code> "dimensionOverride" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 } </code>
-Resizes the collision box to by multiplying each dimension with what is here. x of 2 will double the size in the x direction.
+There is a converter provided in the Content Builder which will greatly speed up the editing of these files. This option will be written up at a later period of time.
-==== "dockOneAtATime" ====
-'''Valid options (Bool): <code>Either true or false</code>'''
-Allow the site to only place only one object at a time. Does not affect the amount that can stack on the object.
+== Pathfinding Options ==
+These are all the options that are made available for Pathfinding.
-==== "disallowManualDocking" ====
-'''Valid options (Bool): <code>Either true or false</code>'''
-Stop the player from placing objects in this dock. Still allows objects to be in the dock, from crafting, cooking etc.
+=== "frontSide" ===
+'''Valid options ([[Modding_Key_Terms#Vector 3|Vector 3]] - [[Modding_Key_Terms#Integer|Integer]]): <code>{ "x": 0, "y": 0, "z": 0 }</code>'''
-==== "failedReactionCode" ====
+'''Default Value:''' If not specified, will default to { "x": 0, "y": 0, "z": 0 }. This is the automatic option.
-'''Valid options (String): <code>Any valid reaction code.</code>'''
-A reaction to use when the crafting fails.
-==== "interactActionTrigger" ====
+This property sets a tile that will act as the "front side" of this tile. This is then specifically used as a place that NPC's will attempt to pathfind towards. (This avoids villagers pathfinding into blocks.)
-'''Valid options (String): <code>A valid code for an entityAction</code>'''
-An option to specify an action to trigger when the tile is interacted with.
-==== "sludgeLevels" ====
+=== "pathFindingNoCollision" ===
-'''Valid options (List of Strings): <code>Any valid paths that lead to models.</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-An ordered list of models to be used when crafting. Each entry represents one level/step in a recipe?
+'''Default Value:''' If not specified, will default to False.
-==== "unDockEffect" ====
-'''Valid options (String): <code>Any valid effect code.</code>'''
-The effect that gets triggered when removing an item from this site. Useful for Player Animations.
+This is whether or not this tile will be considered to be a "block" for pathfinding purposes. Objects such as Tall Grass, should have this set to false.
-=== "validDockables" / "validCategories" ===
+=== "pathFindingPenalty" ===
-Valid Dockables/Categories are a list of items with extra properties you can place in sites. Valid dockables are concerned with individual items, denoted by "code" and Valid Categories are concerned with types of item determined by "categories"
+'''Valid options ([[Modding_Key_Terms#Integer|Integer]]): <code>Any positive integer number or -1.</code>'''
-ValidDockables are made of a seperate blobs with their own properties. These properties are as follow;
+'''Default Value:''' If not specified, will default to -1. -1 is the automatic penalty, which will adjust when building.
-<pre>
-{
-  "code" : "",
-  "renderOverride : "",
-  "offset" : { "x" : 0.0, "y" : 0.0, "z" : 0.0},
-  "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0},
-  "placeSoundGroup" : "",
-  "effectTrigger" : ""
-  "effect" : "",
-  "unDockable" : true,
-  "Sites" : [ "a", "b" ],
-  "group" : "base",
-  "asSludge" : true,
-  "undockItem" : { "code" : "staxel.item.Null" }
-}
-</pre>
-ValidCategories are also made of a seperate blobs with their own properties. These properties are as follow;
-<pre>
-{
-  "category" : "",
-  "offset" : { "x" : 0.0, "y" : 0.0, "z" : 0.0},
-  "rotation" : { "x" : 0.0, "y" : 0.0, "z" : 0.0},
-  "placeSoundGroup" : "",
-  "effectTrigger" : ""
-  "effect" : "",
-  "unDockable" : true,
-  "Sites" : [ "a", "b" ],
-  "group" : "base",
-  "asSludge" : true,
-  "undockItem" : { "code" : "staxel.item.Null" }
-}
-</pre>
-==== "code" ====
+This allows you to fine tune how Villagers will use this object to pathfind on or through. If this block has a lower penalty than usual, such as the cobble pathway blocks, then villagers will prefer to walk on this block.
-'''Valid options (String): <code>Any valid string that leads to an item.</code>'''
-A string containing the code of the item the blob will be referring to.
+As mentioned in default value, if a value of -1 is used then it will automatically adjust the penalty. By default the penalty will follow these rules in order;
-==== "category" ====
+* If the Kind = "compound", then penalty will equal 100.
-'''Valid options (String): <code>Any valid string that references something in an items "categories" property.</code>'''
+* Else if the Kind = "object", and the object has collision but does not have pathfinding collision (See [[#"pathFindingNoCollision"]]) then it will have a penalty of 100.
+* Else if the Kind = "Object", but does not follow the above, the penalty will be 15.
+* Else if the Kind = "nothing", then penalty will equal 1.
+* Else if the the object has collision but does not have pathfinding collision then it will have a penalty of 10
+* Else the penalty will be 3.
-Any items that have the string provided in their "categories" property are valid for this.
-==== "offset" ====
-'''Valid options (Vector 3F): <code> "offset" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 } </code>
-Sets the offset of the item to be from the site. A unit of 1 is one block in that direction.
+== Physics Options ==
+These are all the options that are made available for adjusting how the player collides with the tile.
-==== "rotation" ====
+=== "bouncyness" ===
-'''Valid options (Vector 3F): <code> "rotation" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 } </code>
+'''Valid options ([[Modding_Key_Terms#Float|Float]]): <code>-1 and below to avoid bouncing, -1 to 0 for lower to normal bouncing, higher then 0 for more extreme bouncing.</code>'''
-Sets the offset of the rotation when compared to the site. A unit of 1 is one rotation?
+'''Default Value:''' No default value is specified. Always need to provide your own.
-==== "placeSoundGroup" ====
-'''Valid options (String): <code>Any valid "code" string that points to a Sound Group.</code>'''
-This option specifies what group of sounds to play when the object is destroyed.
+This option describes how much a tile will bounce you back when colliding with it. The maths behind it is <code>Bounce Vector * (Tile.Bouncyness + 1)</code>.
-For example: Setting this to <code>"staxel.sounds.damage.Grass"</code> will make the block play grass sounds when destroyed.
+=== "collision" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-==== "effect" ====
+'''Default Value:''' No default value is specified. Always need to provide your own.
-'''Valid options (String): <code>Any valid "code" string that points to an effect.</code>'''
-This option specifies the effect which will be played upon doing an action with this item.
-==== "effectTrigger" ====
+This option specifies whether or not a player, or other entities, can collide with the tile in question. Commonly flowers don't have collision, while most other objects do.
-'''Valid options (String): <code>Any valid "code" string that points to an effect.</code>'''
-This option specifies the trigger that will be applied to the object upon doing an action. Commonly "staxel.effect.DockItem".
+== Tile Placement Options ==
+These are all the options that affect tile placement.
-==== "unDockable" ====
+=== "attachmentDirections" / "placementDirections"  ===
-'''Valid options (Bool): <code>Either true or false</code>'''
+'''Valid options ([[Modding_Key_Terms#List|List]] of [[Modding_Key_Terms#String|String]] ): <code>A list of combinations which have one of (x,y,z) AND one of (p,n) (i.e. "xp" or "yn"), OR only have "all".</code>'''
-Whether or not, the player can pick up the item again after placing it.
+'''Default Value:''' If not specified, will default to having "all" sides be Attachable or Placeable.
-==== "sites" ====
-'''Valid options (List of Strings): <code>Any valid string, the correspends to any of the site names.</code>'''
-This option specifies what sites this dockable can affect. You can also have "all" to affect all sites.
+"placementDirections" is the list of directions that the tile can be placed onto. For each options, they must have a direction (x, y or z. The three planar directions.) and whether to check in the positive or negative direction. (p or n respectively). Alternatively you can just use "all" to allow the object to be placed in any direction.
-==== "group" ====
+The complement of "placementDirections" is the "attachmentDirections" option, which specifies which directions objects can be placed on the specified object.
-'''Valid options (String): <code>Any valid string.</code>'''
-Not entirely sure here.
+For example: Giving "placementDirections" <code>["yn", "yp"]</code> will allow the object to be placed on the top or bottom of any object but not the sides while giving "attachmentDirections" <code>["yn", "yp"]</code> will allow any other object to be placed on the top or bottom of this object.
-==== "asSludge" ====
-'''Valid options (Bool): <code>Either true or false</code>'''
-Whether or not, when the item dock, does it affect the sludge levels of the object.
+=== "attachToAbove" / "attachToBelow" / "attachToSide" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-==== "undockItem" ====
+'''Default Value:''' If not specified, "attachToBelow" will default to True while the others will default to False.
-'''Valid options (Item Blob): <code>An item which is created upon undocking.</code>'''
-An item to override what was placed in the dock upon picking up. Commonly used to override failed dishes with null items in order to avoid giving players failed dishes.
+Note: Do not use this on materials.
-==== "requiresActionCookie" ====
-This is a small blob that is contained within a group or dockable. It contains the following two values:
-<pre>
-"requiresActionCookie" : {
-  "name" : "",
-  "value" : ""
-}
-</pre>
-This blob updates the value with the name of "name" with the new value in "value". Used to state the container state in the Baking Station.
-== Tile Placement ==
-=== "alts" ===
-'''Valid options (String Array): <code>Any path pointing to a *.qb file. Starting at, but not including, the "content" folder</code>'''
-A list of alternative models to use instead of the base model described in "voxels". The game will randomly choose a model from this list and the "voxels" parameter upon placing the object.
-For example: If you put <code>[ "staxel/tile/grass/Grass-alt2.qb", "staxel/tile/grass/Grass-alt3.qb", "staxel/tile/grass/Grass-alt4.qb" ]</code>, then when you place the tile, it will choose between the one specified in "voxels" and alt 2, 3 or 4 upon placing.
-=== "altsCount" ===
-'''Valid options (Int): <code>The number of alts + voxel combined</code>'''
-This represents how many different options there are. Should be the number of alternative models plus the base voxel.
-For example: If using the example from [[#"alts"]], you should place the number <code>4</code> here.
-=== "attachToAbove" / "attachToBelow" / "attachToSide" ===
-'''Valid options (bool): <code>Either true or false</code>'''
 These options specifies if the object will try and align itself. Above and Below will attach themselves to the bottom/top of a block so that the object is flush with the other block. Side will attempt to attach to the block behind the object. These affects are recursively done for up to 3 objects?
-For example: If you have a lantern, setting to "attachToAbove" true will properly attach to the cieling, while setting to false may leave it floating in mid-air.
+For example: If you have a lantern, setting to "attachToAbove" true will properly attach to the ceiling, while setting to false may leave it floating in mid-air.
-=== "attachmentDirections" / "placementDirections" ===
+=== "floats" ===
-'''Valid options (String Array): <code>A combination of one of (x,y,z) AND (p,n), OR just "all"</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-"placementDirections" is the list of directions that the tile can be placed onto. For each options, they must have a direction (x, y or z. The three planar directions.) and whether to check in the positive or negative direction. (p or n respectively). Alternatively you can just use "all" to allow the object to be placed in any direction.
+'''Default Value:''' If not specified, will default to False.
-The complement of "placementDirections" is the "attachmentDirections" option, which specifies which directions objects can be placed on the specified object.
+This specifies whether or not this tile can float in the air without destroying itself.
-For example: Giving "placementDirections" <code>["yn", "yp"]</code> will allow the object to be placed on the top or bottom of any object but not the sides while giving "attachmentDirections" <code>["yn", "yp"]</code> will allow any other object to be placed on the top or bottom of this object.
 === "orientationVariants" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-This option specifies if the object should be rotated randomly upon placement. (Right?)
+'''Default Value:''' If not specified, will default to False.
-For example: If set to true on a book tile, it will place the book in any of the 4 orientations when placed down, while if false, allows the player to rotate the book themselves.
+This option specifies if the object should be '''rotated''' randomly upon placement. If set to true on a pile of stone, it will place the stone in any of the 4 orientations when placed down. If false, allows the player to rotate the book themselves.
 === "randomizePosition" / "radomizeVerticalPosition" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
+'''Default Value:''' If not specified, both will default to False.
 This option specifies if the object should be given a random horizontal/vertical displacement when it is placed.
@@ Line 533: / Line 575: @@
 === "variantsRandomizeVerticalPosition" ===
-'''Valid options (List of Bools): <code>Either true or false for each model specified in alts. Needs to be the same length as Alts.</code>'''
+'''Valid options ([[Modding_Key_Terms#List|List]] of [[Modding_Key_Terms#Bool|Bool]] ): <code>A list of bools for every single Alt. (Including voxels.)</code>'''
-This option specifies if the object should be given a random vertical displacement when it is placed. The first object in the list affects the first alternative model. The second affects the second. This
+'''Default Value:''' If not specified, will assume all will be false.
-For example: If set to true on a book tile, it will place the book and give it an offset of a few voxels in the x and z direction, while if false, it will always be in the standard position.
-=== "representativeTile" ===
+This option specifies if each alternative model for the object should be given a random vertical displacement when it is placed. The first object in the list affects the first alternative model. The second affects the second etc.
-'''Valid options (String): <code>Any valid tile code.</code>'''
-This will set the tile that you will receive when breaking or pressing g on the tile. This is avaliable because when you place an object with auto-tile info, it can turn into another item with no info on what original tile was placed. By default, it will give the tile that is being made.
+=== "wallPushOut" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-== "autoTileInfo" ==
+'''Default Value:''' If not specified, "attachToBelow" will default to True while the others will default to False.
-AutoTileInfo is always a list of blobs. These blobs contain information about what block to override or what block to look for in what place. Each blob in the list is constructed like so:
-<pre>
-"autoTileInfo" : [
-  {
-    "lookFromOverride" : "",
-    "DirectionsToLookIn" : [
-      {
-        "direction" : "",
-        "secondDirection" : "",
-        "tilesToLookFor" : [],
-        "tileCategoriesToLookFor" : [],
-        "rotationToLookFor": 0
-      }
-    ],
-    "results" : [
-      {
-        "tileToPlace" : "",
-        "direction" : "",
-        "secondDirection" : "",
-        "rotation" : ""
-      }
-    ],
-    "onTileRemoval" : false
-}
-</pre>
-=== "Common Terms" ===
+Note: Do not use this on materials.
-==== "direction" ====
-'''Valid options (String): <code>up, down, front, back, left, right, none</code>'''
-Forces the object to go look in this direction. So giving this up, makes the tile look one tile upwards.
-==== "secondDirection" ====
+These options specifies if the object will try to make sure it will not collide with walls. This is useful for furniture
-'''Valid options (String): <code>up, down, front, back, left, right, none</code>'''
-Forces the object to go look in this direction after heading in "direction". So giving this up, makes the tile look one tile upwards. Therefore if both "direction" and "secondDirection" is up, then it will look for two tiles upwards.
-==== "lookFromOverride" ====
+== Rendering Options ==
-'''Valid options (String): <code>up, down, front, back, left, right, none</code>'''
+These are all the options that affect only how the tile looks and not any other feature.
-Sets the initial spot to be in the specified direction, rather than the tile itself.
-==== "onTileRemoval" ====
+=== "alts" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
+'''Valid options ([[Modding_Key_Terms#List|List]] of [[Modding_Key_Terms#String|String]] ): <code>A list of strings containing the path to a model file. Can also optionally contain "?size={16,16,16}?offset={0,0,0}" to only specify a section inside that file.</code>'''
-Updates the tiles on removing the tile?
+'''Default Value:''' If not specified, will rely on "voxels" to provide the model. Can be used in conjunction with "voxels".
+A list of alternative models to use instead of the base model described in "voxels". The game will randomly choose a model from this list and the "voxels" parameter upon placing the object. Use this if more than 1 tile look is used.
-=== "directionsToLookIn" ===
+The optional parameter mentioned above can link multiple variants to the same file. What it does is take a section that is as large as "size" which is offsetted by "offset".
-This is a list of directions that will be looked in to see if objects are in certain blocks first. Uses direction and secondDirection to navigate to the tile.
-==== "tilesToLookFor" ====
+If you're making a tileObject see [[#"variants"]].
-'''Valid options (String): <code>Any valid code that points towards a tile or tileObject.</code>'''
-This is a list of tiles it will look for. If it contains any of these then it will succeed and cause "results" to run.
-==== "tileCategoriesToLookFor" ====
+=== "altsCount" ===
-'''Valid options (String): <code>Any valid string that points that is a category in tile or tileObject.</code>'''
+'''Valid options ([[Modding_Key_Terms#Integer|Integer]]): <code>Any valid positive integer.</code>'''
-This is a list of categories inside of the tile's categories that it will look for. If it contains any of these then it will succeed and cause "results" to run.
+'''Default Value:''' If not specified, will either default to 1 if there is no [[#"variants"]] property or however many "variants" are present if it is.
-==== "rotation" ====
-'''Valid options (Int): <code>A number between 0-3 representing rotation</code>'''
-If it finds the right tile, then it will then search for what direction it is in, if this is present. This is relative to the tile that is being placed. If this succeeds after it has found a tile, then results will run. If it fails, results won't run.
+This represents how many different options there are. If only "alts" and "voxels" are used, this number should be the number of alternative models plus the base voxel. If "variants" are used then it should be the number of variants only.
+For example: If the file contains "voxels" and 3 "alts" then altscount should equal 4. If the file contains 3 "variants" then it should be 3.
-=== "directionsToLookIn" ===
-This is a list of resulting objects that will be placed if it succeeds in looking for tiles. This uses direction and secondDirection in order to specify where the tile is placed.
-==== "tileToPlace" ====
+=== "aoFloor" ===
-'''Valid options (String): <code>Any valid string that points that is a category in tile or tileObject.</code>'''
-This points to the specific tile or tileObject to be placed when succeeding.
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-==== "rotation" ====
+'''Default Value:''' If not specified, will default to True. (Probably)
-'''Valid options (Int): <code>A number between 0-3 representing rotation</code>'''
-This is the rotation that the tile will be placed in. This is relative to the tile being placed.
+This tells the game whether to render a placed tile object with shadows as if it's been set on the ground. If your object has shadow "banding" then this is "True".
+Changing this value will require a content re-build.
-== Physics and Lighting ==
-=== "bouncyness" ===
-'''Valid options (Float): <code>-1 and below to avoid bouncing, -1 to 0 for lower to normal bouncing, higher then 0 for more extreme bouncing</code>'''
-This option describes how much a tile will bounce you back when colliding with it. The maths behind it is <code>Bounce Vector * (Tile.Bouncyness + 1)</code>.
+=== "emmisiveColor" ===
+'''Valid options ([[Modding_Key_Terms#Colour|Colour]]): <code>A hexadecimal string that is is in ARGB format. (2 characters for Alpha, Red, Green, Blue)</code>'''
+'''Default Value:''' No default value is specified. Always need to provide your own.
-=== "collision" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
-This option specifies whether or not a player, or other object, can collide with the tile in question. Commonly flowers don't have collision, while most other objects do.
+The color in which an object with the option [[#"light"]] higher than 0 will emit when it is placed down.
+For example: A light that has an emmisiveColor property of <code>"FFFF0000"</code> will emit a strong red light.
-=== "emmisiveColor" ===
-'''Valid options (String): <code>A hexadecimal string that is is in ARGB format. (2 chars for Alpha, Red, Green, Blue) </code>'''
-The color in which an object with the option [[#"light"]] higher than 0 will emit when it is placed down.
+=== "light" ===
+'''Valid options ([[Modding_Key_Terms#Float|Float]]): <code>Any valid positive decimal number.</code>'''
-For example: A light that has an emmisiveColor property of <code>"FFFF0000"</code> will emit a strong red light.
+'''Default Value:''' If not specified, will not emit light.
-=== "light" ===
-'''Valid options (Float): <code>Any positive decimal number.</code>'''
 Specifies how much light is to be emitted from the object. If set to 0, no light will be emitted
@@ Line 656: / Line 654: @@
-=== "unbreakable" ===
+=== "open" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-This option specifies whether a person can break the object after it is placed in the world. Should never be set to true, unless there is some code to remove this object. This option overrides the need to add any components for breaking the tile.
+'''Default Value:''' If not specified, will default to False.
-== Rendering Options ==
-=== "open" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
 A rendering option. Should only be true if the object is completely empty, like an air block. For all other cases, this is false.
-=== "solid" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
-Should only be true if the object is completely full, such as a dirt block. Most materials will have this option true while most objects should not have this option.
+=== "palette" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A valid path to a *.colorcorrection file</code>'''
+'''Default Value:''' If not specified, will not have any colour correction.
-=== "smoothRecolorationOnPlace" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
-This option will make the tile recolour itself to match the tiles nearby it. Used when a palette is defined.
-=== "palette" ===
-'''Valid options (String): <code>A valid path to a *.colorcorrection file</code>'''
 This is an option that specifies to the game that it can overlay colours on top of the model. It points at another file which acts as a collection for images which define colours which will be used to vary colours. Most files don't need this, however if a tile is repeated often, such as the ground, it can be a handy thing to include.
@@ Line 687: / Line 673: @@
 === "priority" ===
-'''Valid options (int): <code>Any valid integer.</code>'''
+'''Valid options ([[Modding_Key_Terms#Float|Float]]): <code>Any valid positive decimal number.</code>'''
-This rendering option specifies this objects order to being rendered. Currently this is only used on objects of the "material" kind. The object with the higher priority will display over the top of the object with lower priority.
+'''Default Value:''' If not specified, will not emit light.
+This rendering option specifies this objects order to being rendered. Currently this is only used on objects of the "material" kind. The material with the higher priority will display over the top of the object with lower priority.
-== Shop / Inventory Options ==
-These options specify how the shop and inventory will handle this tile.
-=== "categories" ===
+=== "smoothRecolorationOnPlace" ===
-'''Valid options (String Array): <code>Any valid string, although the following strings are used in the menu sorting, "block", "door", "floor"/"flooring", "flower", "furniture", "light", "plant", "tool", "window", "misc", "red", "orange", "yellow", "green", "blue", "purple", "pink", "white", "black" and "brown"</code>
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-This options allows for you to specifiy a number of strings that a person can search for, that will turn up the object in question. Several categories are applied when using the buttons in the catalogue or creative mode inventory.
+'''Default Value:''' If not specified, will default to False.
-For example: If you give an item the category "road", the player is then able to search for "road" which will return the item in question.
+This option will make the tile recolour itself to match the tiles nearby it. Should only be used if a palette is defined.
-=== "descriptionImage" ===
-'''Valid options (String): <code>A valid path to an image</code>'''
-This option specifies an image that will be placed at the end of a description in the catalogue and creative inventory.
+=== "solid" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
+'''Default Value:''' If not specified, will default to False.
-=== "searchable" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
-This option specifies if the object whether the object will show up when it is searched for in the shop catalogue or the creative inventory. Useful for objects that have auto tiling info such as fences. (As such only one object appears in the shopping menu)
+Should only be true if the object is completely full, such as a dirt block. Most materials will have this option true while most objects should not have this option.
+== Sound Options ==
+These options include all ways of adding sound to a tile. Look at [[Sound]] for finding out what a Sound/Sound Group is and how it is defined.
-=== "stackSizeLimit" ===
-'''Valid options (int): <code>Any valid integer.</code>'''
-This is the number of a tile you can hold in 1 slot in your inventory. Left at 999 for consistency with other items.
+=== "damageSoundGroup" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Sound]] file.</code>'''
+'''Default Value:''' If not specified, will not play any sounds when breaking.
-== Sound Options ==
-These options include all ways of adding sound to a tile. Look at [[Sound]] for finding out what a Sound/Sound Group is and how it is defined.
-=== "damageSoundGroup" ===
+This option specifies what group of sounds to play when the object is hit/destroyed.
-'''Valid options (String): <code>Any valid "code" string that points to a Sound Group.</code>'''
-This option specifies what group of sounds to play when the object is destroyed.
-For example: Setting this to <code>"staxel.sounds.damage.Grass"</code> will make the block play grass sounds when destroyed.
+=== "placeSoundGroup" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Sound]] file.</code>'''
+'''Default Value:''' If not specified, will not play any sounds when placing.
-=== "placeSoundGroup" ===
-'''Valid options (String): <code>Any valid "code" string that points to a Sound Group.</code>'''
 This option specifies what group of sounds to play when the object is placed.
-For example: Setting this to <code>"staxel.sounds.damage.Grass"</code> will make the block play destroying grass sounds when the tile is placed.
 === "stepSoundGroup" ===
-'''Valid options (String): <code>Any valid "code" string that points to a Sound Group.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Sound]] file.</code>'''
-This option specifies what group of sounds to play when the object is stepped on.
+'''Default Value:''' If not specified, will not play any sounds when walking on/in tile.
-For example: Setting this to <code>"staxel.sounds.damage.Grass"</code> will make the block play destroying grass sounds when a person is walking over the object.
+This option specifies what group of sounds to play when the object is stepped on.
+== Tile State Entity Options ==
+All these options require the block to be a Tile State Entity. Tile state entities, allow the player to directly affect the tile and also supports animations based on the entity's model and it's layers.
-== Tile State Options ==
-All these options require the block to be a Tile State Entity. Tile state entities however, allow the player to directly affect the tile and also supports animations based on the entity's model and it's layers.
 === "animation" ===
-'''Valid options (String): <code>A valid path to a .bvh animation</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Bone Animation]] file.</code>'''
-An option that specifies what animations should be used on the model. This requires that layernames are the same in the model and animations.
+'''Default Value:''' If not specified, will not have any animations specified.
-=== "customRendererVoxels" ===
+This sets a Bone Animation file that is to be loaded alongside this tile. These animations can then be used by the Tile State Entity in order to adjust how the tile will move. The Layer names for [[#"voxels"]] needs to match with those specified in the animation.
-'''Valid options (String): <code>A valid path to a model</code>'''
-An option to specify the use of a set of voxels while the object is placed?
-=== "interactActionTrigger" ===
+=== "customRendererVoxels" ===
-'''Valid options (String): <code>A valid code for an entityAction</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the path to a model file.</code>'''
-An option to specify an action to trigger when the tile is interacted with.
+'''Default Value:''' If not specified, will not have any custom voxels specified. If specified, will also force [[#"useCustomRendering"]] to True.
-=== "prefetchTileState" ===
-'''Valid options (Bool): <code>Either true or false</code>'''
-This options decides whether or not the TileState of a block is gotten on Server Start.
+This option specifies another set of voxels that are to be used instead of [[#"voxels"]] or similar. These are generally used when placed down although can be used in differing circumstances. So usage of this property depends on how you use it.
-=== "spawnAction" ===
+=== "dockDefinition" ===
-'''Valid options (String): <code>Any valid "code" string that points to a Entity Action.</code>'''
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Docks|Dock]] file.</code>'''
-This option specifies what action is toggled on when the object is spawned into the world, either by loading it up in the world or by placing the object.
+'''Default Value:''' If not specified, will not have any docks, interactable areas, and cannot be used for crafting or storage.
-=== "tileStateKind" ===
+This is Dock Definition that is to be used alongside this tile. This allows use of the game's storage and crafting systems within this tile. It requires that [[#"tileStateKind"]] is set to "staxel.tileState.Dock" or similar in order to work.
-'''Valid options (String): <code>"object", "material", "nothing"</code>'''
-This option specifies what type of tilestate that your tile supports. This is mostly used for crafting stations and other interactable objects. This is not to be included on "dumb" objects such as stone.
+=== "prefetchTileState" ===
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-== Other Options ==
+'''Default Value:''' If not specified, will default to false.
-=== "merchantKind" ===
-'''Valid options (String): <code>Any valid "code" string that points to a Merchant File.</code>'''
-This option specifies when specifies converts the tile Object into a Merchant Vendor block. This essentially makes the tile invisible and spawns the appropriate merchant with their appropriate stall. Do not use this on files that you want to stay in the world.
-== Components ==
+This option specifies whether or not the Tile State will be fetched immediately on place or replace. This should be used on tiles that need to be activated without the player actually looking at them. This includes Spawners, Totems and other Tile State Entities.
-=== "apiary" ===
-This is the component for making your tile an apiary.
-This component can be added to your file by placing the text below into your file;
-<pre>
-"apiary": {
-    "beeEffect": "",
-    "rallyStages": [
-,
-    ],
-    "maxBeeCount": 10,
-    "beesPerDay": 1,
-    "produceWaitDays": 7,
-    "collectionStage": 3
-  },
-</pre>
-Bee Effect, is the code of the particle effect that the apiary should produce.
+=== "spawnAction" ===
-Rally Stages, is a list of the number of bees the apiary should produce during the stages.
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Entity Action]].</code>'''
-Max Bee Count, is the maximum number of bees required to produce honey in your apiary.
-Bees per day, is the number of bees that will arrive on each new day.
-Produce wait days, is the number of days between producing honey.
-Collection stage, is the number of particles around the apiary to signify you can collect honey.
+'''Default Value:''' If not specified, will not play any actions upon placing.
-=== "axeable" ===
-This is the component for making your tile breakable by axes.
-This component can be added to your file by placing the text below into your file;
+This option specifies what action is played when the object is spawned into the world, either by loading it up in the world or by placing the object. Useful for setting a Tile's State on startup (Like the Mixing Station's mixer.)
-<pre>
-"axeable" : {
-  "treasure" : ""
-}
-</pre>
-Treasure is just the code of a treasure file you want the game to access in order to get drop lists.
+=== "tileStateKind" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing a specific tile state kind.</code>'''
-=== "grazable" ===
+'''Default Value:''' If not specified, this tile will not be a Tile State Entity.
-This is the component for allowing animals to eat your tile.
-This component can be added to your file by placing the text below into your file;
-<pre>
-"grazable" : {
-  "turnsInto" : ""
-}
-</pre>
-TurnsInto is the code of the block you want the tile to turn into.
+This option specifies what type of Tile State Entity this tile will be. This is mostly used for crafting stations and other interactable objects. This is not to be included on Tiles and objects that do not need any extra functionality.
-=== "hammerable" ===
+=== "useCustomRendering" ===
-This is the component for making your tile breakable by hammers.
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-This component can be added to your file by placing the text below into your file;
+'''Default Value:''' If not specified, will default to false. Is always True if [[#"customRendererVoxels"]] is non-empty.
-<pre>
-"hammerable" : {
-  "treasure" : ""
-}
-</pre>
-Treasure is just the code of a treasure file you want the game to access in order to get drop lists.
+Whether or not a custom rendering style should be used. Certain Tile State Kinds will need this value to be enforced while others can just use normal rendering.
-=== "hoeable" ===
+== Usage Options ==
-This is the component for allowing your tile to be changed into hoed dirt.
+=== "autoTileInfo" ===
+Auto Tile Info is a property which influences how Tiles are placed within the world. Using this property allows you to create fences that will turn at corners, and torches that always stick to a wall.
-This component can be added to your file by placing the text below into your file;
+This property has it's own page, including how to use it, at [[Auto-Tiling]].
-<pre>
-"hoeable" : {
-}
-</pre>
-There are no attributes in hoeable.
+=== "interactEffect" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to a [[Effect]] file.</code>'''
+'''Default Value:''' If not specified, will not play any effect on interaction.
-=== "mineable" ===
-This is the component for making your tile breakable by pickaxes.
-This component can be added to your file by placing the text below into your file;
+This is the effect that will play when the Tile is interacted with. Also allows the tile to be interacted with.
-<pre>
-"mineable" : {
-  "treasure" : ""
-}
-</pre>
-Treasure is just the code of a treasure file you want the game to access in order to get drop lists.
+=== "representativeTile" ===
+'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string containing the code to another tile file.</code>'''
-=== "pricing" ===
+'''Default Value:''' If not specified, will just give this tile instead of another tile.
-This is the component needed for selling your item in the catalogue. This is required if the object is searchable.
-This component can be added to your file by placing the text below into your file;
-<pre>
-"pricing" : {
-  "value" : 10.0,
-  "buyable" : true
-}
-</pre>
-Value is the price of the item to be bought for in the catalogue.
+This will set the tile that you will receive when pressing g on the tile and/or when using the [[Spawn On Break Component]]. This is most useful when using [[#"autoTileInfo"]] as this allows you to only need one tile which has auto tiling on it.
-Buyable sets whether the item can be bought from the catalogue or only sold.
-=== "scytheable" ===
+=== "unbreakable" ===
-This is the component for making your tile breakable by scythes.
+'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
-This component can be added to your file by placing the text below into your file;
+'''Default Value:''' No default value is specified. Always need to provide your own.
-<pre>
-"scytheable" : {
-  "treasure" : ""
-}
-</pre>
-Treasure is just the code of a treasure file you want the game to access in order to get drop lists.
-=== "shovelable" ===
-This is the component for making your tile breakable by shovels.
-This component can be added to your file by placing the text below into your file;
-<pre>
-"shovelable" : {
-  "treasure" : ""
-}
-</pre>
-Treasure is just the code of a treasure file you want the game to access in order to get drop lists.
-=== "sweepable" ===
-This is the component for making your tile breakable by brooms.
-This component can be added to your file by placing the text below into your file;
-<pre>
-"sweepable" : {
-  "treasure" : ""
-}
-</pre>
-Treasure is just the code of a treasure file you want the game to access in order to get drop lists.
+This option specifies whether a person can break the object after it is placed in the world. Should never be set to true, unless there is something that is set to remove this tile. This option does override the need to add any components for breaking the tile.

Difference between revisions of "Tile"

Latest revision as of 01:44, 9 November 2020

Contents

Creating a Tile-Object

Creating the Model

Adding the Tile Object to Staxel

Adding the Tile Object via Asset Manager

Adding the Tile Object via Text Files

A small explanation of the *.tile file

Why is my object not placing on anything other than the ground?

Creating a Material

Creating a material

Loading the material in the game

Useful Components

Config Options

"code"

"kind"

Catalogue/Inventory Options

"categories"

"descriptionImage"

"searchable"

"stackSizeLimit"

Engine Options

"canBeGifted"

"CanBreakDuringFestival"

"canGrowFlowers"

"totemCeiling"

"compound"

"size"

"specification"

"interactActionTrigger"

"interactVerb"

"mapping"

"merchantKind"

Object Options

"variants"

"voxels"

Material Options

"layout"

"voxels"

Pathfinding Options

"frontSide"

"pathFindingNoCollision"

"pathFindingPenalty"

Physics Options

"bouncyness"

"collision"

Tile Placement Options

"attachmentDirections" / "placementDirections"

"attachToAbove" / "attachToBelow" / "attachToSide"

"floats"

"orientationVariants"

"randomizePosition" / "radomizeVerticalPosition"

"variantsRandomizeVerticalPosition"

"wallPushOut"

Rendering Options

"alts"

"altsCount"

"aoFloor"

"emmisiveColor"

"light"

"open"

"palette"

"priority"

"smoothRecolorationOnPlace"

"solid"

Sound Options

"damageSoundGroup"

"placeSoundGroup"

"stepSoundGroup"

Tile State Entity Options

"animation"

"customRendererVoxels"

"dockDefinition"

"prefetchTileState"

"spawnAction"

"tileStateKind"

"useCustomRendering"

Usage Options

"autoTileInfo"