Tile

From wiki
Revision as of 01:36, 22 February 2017 by DeamonHunter (Talk | contribs) ("autoTileInfo")

Jump to: navigation, search

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.


Configuration Options

This is a list of all options that you can add into a tile, complete with information on what they do.


Engine

"code"

Valid options (String): Any valid string. Common to make the string the path to the model but with periods [.] replacing slashes [/]

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.

For example: Having the code "mods.fountain.fountain" creates an object that has the handle "mods.fountain.fountain"


"kind"

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

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.


"canGrowFlowers"

Valid options (bool): Either true or false

This option specifies if flowers, can grow on top of the block during world generation. Helpful when a block is used in Structures.


"compound"

Compound is a container for multiple variables. It is written as:

"compound": {
  "size": {
    "x": 3,
    "y": 1,
    "z": 2
  },
  "specification": "\n\tCC XC CC\n\t"
}

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.


"size"

Size is another multiple variable container. It is written as:

"size": {
  "x": 3,
  "y": 1,
  "z": 2
},

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.

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 {"x" : 1, "y" : 4, "z" : 2}


"specification"

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


You do not need to add a specification, unless you want to allow an empty tile to be built in.


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;

  • "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 follows a pattern like;

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

An appropriate specification variable for this is "CE CE CE CX"

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


"pathFindingNoCollision"

Valid options (bool): Either true or false

This option allows the pathfinding system to ignore the tile for pathfinding purposes.


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


"mapping"

Valid options (Unsigned Int): Any positive number.

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.


"pathFindingPenalty"

Valid options (Int): Any positive or negative number.

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


"dockInfo"

This option specifies a bunch of options for interacting with a tile.

A Dock file includes;

"dockInfo" : {
  "allowStacksForAllSites" : false,
  "craftingKeyword" : "",
  "nameTagOffset" : { "x" : 0.0, "y" : 0.6, "z" : 0.0 },
  "sites" : [ ],
  "validDockables" : [ ],
  "validCategories : [ ]
}

"allowStacksForAllSites"

Valid options (Bool): Either true or false

An option to allow every site to allow stacking up to the stackSizeLimit.


"craftingKeyword"

Valid options (String): Any valid string.

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.


"nameTagOffset"

Valid options (Vector 3F): "nameTagOffset" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 }

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.


"sites"

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;

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

"siteName"

Valid options (String): Any valid string.

A string to name the site in question.

"location"

Valid options (Vector 3F): "location" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 }

Sets the location where the site will be. A unit of 1 is one block in that direction.

"rotation"

Valid options (Vector 3F): "rotation" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 }

Sets the rotation of the site. A unit of 1 is one rotation?

"allowStacks"

Valid options (Bool): Either true or false

Allows the site to take more than one object. Overrides "allowStacksForAllSites" in DockInfo.

"colliderOffset"

Valid options (Vector 3F): "colliderOffset" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 }

This offsets the collision of the site to be in a different spot than the place where it is docked.

"compact"

Valid options (Bool): Either true or false

This option sets it so that items placed in this space, gets rendered at a smaller size?

"craftTypeRestriction"

Valid options (List of Strings): Any valid string.

A word to describe what is done at the site. Similar to Crafting Keyword. Can also use "combine".

"dimensionOverride"

Valid options (Vector 3F): "dimensionOverride" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 }

Resizes the collision box to by multiplying each dimension with what is here. x of 2 will double the size in the x direction.

"dockOneAtATime"

Valid options (List of Strings): Any valid string.

Allow the site to only place only one object at a time. Does not affect the amount that can stack on the object.

"disallowManualDocking"

Valid options (Bool): Either true or false

Stop the player from placing objects in this dock. Still allows objects to be in the dock, from crafting, cooking etc.

"failedReactionCode"

Valid options (String): Any valid reaction code.

A reaction to use when the crafting fails.

"interactActionTrigger"

Valid options (String): A valid code for an entityAction

An option to specify an action to trigger when the tile is interacted with.

"sludgeLevels"

Valid options (List of Strings): Any valid paths that lead to models.

An ordered list of models to be used when crafting. Each entry represents one level/step in a recipe?

"unDockEffect"

Valid options (String): Any valid effect code.

The effect that gets triggered when removing an item from this site. Useful for Player Animations.


"validDockables" / "validCategories"

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"

ValidDockables are made of a seperate blobs with their own properties. These properties are as follow;

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

ValidCategories are also made of a seperate blobs with their own properties. These properties are as follow;

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

"code"

Valid options (String): Any valid string that leads to an item.

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

"category"

Valid options (String): Any valid string that references something in an items "categories" property.

Any items that have the string provided in their "categories" property are valid for this.

"offset"

Valid options (Vector 3F): "offset" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 }

Sets the offset of the item to be from the site. A unit of 1 is one block in that direction.

"rotation"

Valid options (Vector 3F): "rotation" : ( "x" : 0.0, "y" : 0.6, "z" : 0.0 }

Sets the offset of the rotation when compared to the site. A unit of 1 is one rotation?

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

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

"effect"

Valid options (String): Any valid "code" string that points to an effect.

This option specifies the effect which will be played upon doing an action with this item.

"effectTrigger"

Valid options (String): Any valid "code" string that points to an effect.

This option specifies the trigger that will be applied to the object upon doing an action. Commonly "staxel.effect.DockItem".

"unDockable"

Valid options (Bool): Either true or false

Whether or not, the player can pick up the item again after placing it.

"sites"

Valid options (List of Strings): Any valid string, the correspends to any of the site names.

This option specifies what sites this dockable can affect. You can also have "all" to affect all sites.

"group"

Valid options (String): Any valid string.

Not entirely sure here.

"asSludge"

Valid options (Bool): Either true or false

Whether or not, when the item dock, does it affect the sludge levels of the object.

"undockItem"

Valid options (Item Blob): An item which is created upon undocking.

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.

"requiresActionCookie"

This is a small blob that is contained within a group or dockable. It contains the following two values:

"requiresActionCookie" : {
  "name" : "",
  "value" : ""
}

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): Any path pointing to a *.qb file. Starting at, but not including, the "content" folder

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 [ "staxel/tile/grass/Grass-alt2.qb", "staxel/tile/grass/Grass-alt3.qb", "staxel/tile/grass/Grass-alt4.qb" ], 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): The number of alts + voxel combined

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 4 here.


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


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

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.

"attachToAbove" / "attachToBelow" / "attachToSide"

Valid options (bool): Either true or false

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.


"attachmentDirections" / "placementDirections"

Valid options (String Array): A combination of one of (x,y,z) AND (p,n), OR just "all"

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


"orientationVariants"

Valid options (Bool): Either true or false

This option specifies if the object should be rotated randomly upon placement. (Right?)

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.


"randomizePosition" / "radomizeVerticalPosition"

Valid options (Bool): Either true or 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 Bools): Either true or false for each model specified in alts. Needs to be the same length as Alts.

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

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"

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.


Physics and Lighting

"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

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): Either true or false

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.


"emmisiveColor"

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

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 positive decimal number.

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.


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


Rendering Options

"open"

Valid options (Bool): Either true or 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.

"solid"

Valid options (Bool): Either true or 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.


"smoothRecolorationOnPlace"

Valid options (Bool): Either true or false

This option will make the tile recolour itself to match the tiles nearby it. Used when a palette is defined.


"palette"

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

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 (int): Any valid integer.

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.


Shop / Inventory Options

These options specify how the shop and inventory will handle this tile.

"categories"

Valid options (String Array): 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"

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.

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.


"descriptionImage"

Valid options (String): A valid path to an image

This option specifies an image that will be placed at the end of a description in the catalogue and creative inventory.


"searchable"

Valid options (Bool): Either true or 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. Useful for objects that have auto tiling info such as fences. (As such only one object appears in the shopping menu)


"stackSizeLimit"

Valid options (int): Any valid integer.

This is the number of a tile you can hold in 1 slot in your inventory. Left at 999 for consistency with other items.


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

"interactActionTrigger"

Valid options (String): A valid code for an entityAction

An option to specify an action to trigger when the tile is interacted with.

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

Other Options

"merchantKind"

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

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

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

"apiary": {
    "beeEffect": "",
    "rallyStages": [
      0,
    ],
    "maxBeeCount": 10,
    "beesPerDay": 1,
    "produceWaitDays": 7,
    "collectionStage": 3
  },

Bee Effect, is the code of the particle effect that the apiary should produce. Rally Stages, is a list of the number of bees the apiary should produce during the stages. 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.


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

"axeable" : {
  "treasure" : ""
}

Treasure is just the code of a treasure file you want the game to access in order to get drop lists.


"grazable"

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;

"grazable" : {
  "turnsInto" : ""
}

TurnsInto is the code of the block you want the tile to turn into.


"hammerable"

This is the component for making your tile breakable by hammers.

This component can be added to your file by placing the text below into your file;

"hammerable" : {
  "treasure" : ""
}

Treasure is just the code of a treasure file you want the game to access in order to get drop lists.


"hoeable"

This is the component for allowing your tile to be changed into hoed dirt.

This component can be added to your file by placing the text below into your file;

"hoeable" : {
}

There are no attributes in hoeable.


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

"mineable" : {
  "treasure" : ""
}

Treasure is just the code of a treasure file you want the game to access in order to get drop lists.


"pricing"

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;

"pricing" : {
  "value" : 10.0,
  "buyable" : true
}

Value is the price of the item to be bought for in the catalogue. Buyable sets whether the item can be bought from the catalogue or only sold.


"scytheable"

This is the component for making your tile breakable by scythes.

This component can be added to your file by placing the text below into your file;

"scytheable" : {
  "treasure" : ""
}

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;

"shovelable" : {
  "treasure" : ""
}

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;

"sweepable" : {
  "treasure" : ""
}

Treasure is just the code of a treasure file you want the game to access in order to get drop lists.