Revision as of 06:06, 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.

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.

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

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.

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.

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

== Under Construction ==