Difference between revisions of "Tile"

From wiki
Jump to: navigation, search
(Config Options: More edits to stuff. Will continue at a later point.)
m ("collision")
Line 405: Line 405:
 
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>.
 
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>.
  
== "collision" ==
+
=== "collision" ===
 
'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
 
'''Valid options ([[Modding_Key_Terms#Bool|Bool]]): <code>True or False</code>'''
  
Line 412: Line 412:
  
 
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.
 
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 ==
 
== Tile Placement Options ==

Revision as of 08:02, 23 August 2017

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.


Contents

Creating a In-game 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.


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.

  • Keep the Bounding Box, the box which tells you where you can build, in increments of 16. (Such as 16x16x16, 16x32x16, 48x48x48 etc) This allows you to allign the block within the tile.
  • 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?


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.


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 *.vox and Voxel Studio stores them as *.vsd. Staxel uses only one format for now, the *.qb file created by Qubicle. As this is a popular format, most of the software avaliable have a way to "export" to a *.qb 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.


Adding the Model to Staxel

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 *.qb 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/tileObject/Base.config",
  "voxels": "mods/modname/modelname.qb",
  "code": "mods.modname.modelname",
  "categories": [
    "cat1",
    "cat2",
  ],
  "pricing": {
    "value": 20.0
  }
}

If you have a tile that is larger than 1 square, you will need to include a "compound" section in there as well. Look at Modding Configs#"compound" for more info.

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 tile to Staxel.


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 "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 "base" with the name of any config tile found in the same folder. (That is "staxel/tileObject/".) In essence this is used to remove a number of redundent text that would need to appear in every block.

"code" : 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 \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" however it isn't necessary. (A code of "bob" could work but might not 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"

"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. A list of those categories are mentioned at Modding Configs#"categories"

"pricing" : This property sets how much it would cost in the shipping catalogue. Keeping this the same is fine.


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 *.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 traveled 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 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.

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.


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
  }
}

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.


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 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"


"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.


"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.


"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:

  1. You want to specify some empty tiles within the object itself.
  2. 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".


"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 cieling, while setting to false may leave it floating in mid-air.


"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".


"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.


"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): Any valid "code" string that points to a Sound Group.

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

For example: Setting this to "staxel.sounds.damage.Grass" will make the block play grass sounds when destroyed.


"placeSoundGroup"

Valid options (String): Any valid "code" string that points to a Sound Group.

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

For example: Setting this to "staxel.sounds.damage.Grass" will make the block play destroying grass sounds when the tile is placed.


"stepSoundGroup"

Valid options (String): Any valid "code" string that points to a Sound Group.

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

For example: Setting this to "staxel.sounds.damage.Grass" will make the block play destroying grass sounds when a person is walking over the object.


Tile State Entity 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): A valid path to a .bvh animation

An option that specifies what animations should be used on the model. This requires that layernames are the same in the model and animations.


"customRendererVoxels"

Valid options (String): A valid path to a model

An option to specify the use of a set of voxels while the object is placed?


"prefetchTileState"

Valid options (Bool): Either true or false

This options decides whether or not the TileState of a block is gotten on Server Start.


"spawnAction"

Valid options (String): Any valid "code" string that points to a Entity Action.

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.


"tileStateKind"

Valid options (String): "object", "material", "nothing"

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.


"useCustomRendering"

[To Be Added]


Usage Options

"autoTileInfo"

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:

"autoTileInfo" : [
  {
    "lookFromOverride" : "",
    "DirectionsToLookIn" : [
      {
        "direction" : "",
        "secondDirection" : "",
        "tilesToLookFor" : [],
        "tileCategoriesToLookFor" : [],
        "rotationToLookFor": 0
      }
    ],
    "results" : [
      {
        "tileToPlace" : "",
        "direction" : "",
        "secondDirection" : "",
        "rotation" : ""
      }
    ],
    "onTileRemoval" : false
}


"Common Terms"

"direction"

Valid options (String): up, down, front, back, left, right, none

Forces the object to go look in this direction. So giving this up, makes the tile look one tile upwards.


"secondDirection"

Valid options (String): up, down, front, back, left, right, none

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"

Valid options (String): up, down, front, back, left, right, none

Sets the initial spot to be in the specified direction, rather than the tile itself.


"onTileRemoval"

Valid options (Bool): Either true or false

Updates the tiles on removing the tile?


"directionsToLookIn"

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"

Valid options (String): Any valid code that points towards a tile or tileObject.

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"

Valid options (String): Any valid string that points that is a category in tile or tileObject.

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.


"rotation"

Valid options (Int): A number between 0-3 representing rotation

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.


"results"

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"

Valid options (String): Any valid string that points that is a category in tile or tileObject.

This points to the specific tile or tileObject to be placed when succeeding.

"rotation"

Valid options (Int): A number between 0-3 representing rotation

This is the rotation that the tile will be placed in. This is relative to the tile being placed.


"dockDefinition"

[To Be Added]


"interactEffect"

Valid options (String): Any valid effect 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.


"representativeTile"

Valid options (String): Any valid tile 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.


"unbreakable"

Valid options (Bool): Either true or false

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.