Difference between revisions of "Modding"

From wiki
Jump to: navigation, search
(Added sound creation. Also fixed up changelog.)
 
(13 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
[[Category:Modding]]
 
This page is meant to give an overview into Staxel's modding systems and give you insight into how to install, modify and create your own mods in the game.
 
This page is meant to give an overview into Staxel's modding systems and give you insight into how to install, modify and create your own mods in the game.
 +
  
 
'''Please note this page, and the game itself, is a Work In Progress. Many things are likely to change with the modding systems and any of these methods can be made obsolete at any time.'''
 
'''Please note this page, and the game itself, is a Work In Progress. Many things are likely to change with the modding systems and any of these methods can be made obsolete at any time.'''
  
  
If you are looking for config options, head on over to [[Modding Configs]] for more in depth information.
+
'''Head to [[:Category:Modding]] to look for a specific item to Mod. Most items includes tutorials on how to implement those items within their pages.'''
  
Most Recent change: 21/01/17 [[#Changelog]]
 
  
  
Line 44: Line 45:
  
 
= Creating Mods =
 
= Creating Mods =
== Staxel Modding Cheat Sheet ==
+
== Getting Started with Staxel Modding ==
 +
Staxel modding is easy to get into. Unlike other games, with Staxel you do not need to touch a single piece of code in order to create [[Tile|Tiles]], [[Villager NPCs|Villagers]] or [[Accessory|Clothing/Hair Styles]]. All you need in these cases, is a modelling program that supports making voxel models, and some patience.
  
This cheat sheet contains useful links and resources for modding in Staxel.
 
  
* Simple modding guide: http://blog.playstaxel.com/creating-mods/
+
=== Choosing a Modelling Program ===
* Video tutorial for making and adding hairstyles to Staxel: https://www.youtube.com/watch?v=chW0eI4Y70A
+
To start off with, you will need to choose a Voxel editing program that will allow you to create models. There are three major programs that are in use by Modders in Staxel. Each program will have it's quirks, but each can be easily used to create models and you should choose the one that best suits your needs/wants.  
* The 'Mini Mod kit' comes with templates of character pieces to build off of: http://launcher.playstaxel.com/support/MiniModKit.zip
+
* Creating content for Staxel using [http://store.steampowered.com/app/454550/ Qubicle - Base Edition]: http://minddesk.com/learn/article.php?id=71&oid=11
+
''These may be outdated. If you want more help join the Staxel discord server and people there will be able to help you.''
+
  
==Creating and Updating a .sxlmod file==
+
==== Qubicle ====
=== Creating a .sxlmod file ===
+
[[File:Qubicle.png|800px]]
'''<tt>.sxlmod</tt>''' mods are the preferred method for providing mod files to other players. They provide a way to easily create mods which also does not get deleted upon a Staxel update.  
+
  
To create a '''<tt>*.sxlmod</tt>''' you will need to follow this procedure;
+
'''Avaliable at:''' [http://www.minddesk.com/ http://www.minddesk.com/]
# Head to <code>C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\</code> and start '''<code>Staxel.ModManager.exe</code>'''
+
# Head to '''<tt>Mod → New → Create new Package</tt>'''. Once you have done that follow the instruction set that fit your situation;
+
# Fill in all the details you want.
+
# After that is done, drag your mod files, that are underneath the main mod folder (For Example, if your mod is say <tt>"WoodStuff"</tt> drag all the stuff inside the <tt>"WoodStuff"</tt> folder), into the shaded "Drag and Drop" area, to move them into the mod's folder.
+
# Select OK and the mod is now complete.
+
  
Once the previous instructions have been done, you can then navigate to '''<tt>View → Open Package directory</tt>''' or head to <code>C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\LocalContent\packages\</code> to find your mod file which you can upload to whatever site you choose.
 
  
 +
This is the program that is used by Staxel's artists and other members of the dev team. It is mostly guaranteed to work all models, especially Character Models and Tile Materials.
  
=== Updating a .sxlmod file ===
+
Pros:
Updating a '''<tt>*.sxlmod</tt>''' file is a simple thing to do. To update the file with new additions;
+
* Works with Staxel, even includes some of staxels models under the /Games/ toolbar.
# Head to <code>C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\</code> and start '''<code>Staxel.ModManager.exe</code>'''
+
* Compresses models by default. (Roughly 75% saving on space per object)
# Highlight the mod you want to update
+
* No obvious object size or colour limits.
# Head to '''<tt>Mod → Update Package → From Installation</tt>'''. if you want to update the files based on the already installed mod or '''<tt>From Contents</tt>'''
+
# Your mod is now updated. Feel free to share this with others.
+
  
One thing to note is that Staxel does not do version control with files. Once you have updated a mod, you cannot get the old one back, unless copies were made.
+
Cons:
 +
* Costs money to buy it, but does come with a free trial.
 +
* Certain features are locked behind DLC. Most features are not needed though.
  
  
== Setting up for Mod Creation ==
+
==== MagicaVoxel ====
While modding is easy in Staxel; there are a couple things needed before starting. First off, you will need to have a program to create a voxel model in. You can have a look at [[#Voxel Modelling Software]] and choose a program to work with. Be aware, each program has its quirks, and can cause trouble if you can't figure them out. As such it would be a good idea to learn how to use the program before starting modding, as this can avoid some frustration later down the line.
+
[[File:MagicaVoxel.png|800px]]
  
 +
'''Avaliable at:''' [https://ephtracy.github.io/ https://ephtracy.github.io/]
  
Along with this, there should be one other type of program installed. While notepad is great and all (it really is not great); it would be a good idea to install a different text editing program. Some good suggestions would be [https://notepad-plus-plus.org/ Notepad++], [https://www.sublimetext.com/ Sublime text] or [https://atom.io/ Atom]. These provide their own benefits, and some can be set to give you contextual highlighting to help visually while editing. However this is ''not needed'' and working with normal notepad is fine.
+
This is the program used by most Modders. It is easy to use, it is responsive and comes with most of the basic features. It is however lacking in a couple areas which make creating certain Objects a pain. It is under development, and more features are being added to it.
  
'''Do not use Word or similar programs. They do not work in plain text and therefore will not work for the format needed.'''
+
Pros:
 +
* Free.
 +
* Responsive and easy to use.
 +
* Works great for [[Tile]] Objects, [[Structures]] and [[Items]].
  
To make sure that you don't run into problems with the game not recognising files. By sure to check that you can always see file extensions. (For example .txt). To do this go to Windows Explorer, click on the view tab at the top, and check the box next to "File Name Extensions". This makes sure you can see the .txt behind text files you create among other things.
+
Cons:
 +
* Unable to work with Layers. (Although version 99a has introduced layers in World mode.) [[Accessory|Accessories]] can still be made with this. See notes.
 +
* Size limits. As such cannot open Tile Material models properly. (World mode can create larger objects, but individual objects can't be imported to that size yet.)
 +
* Does not compress files.  
  
After picking and choosing programs, the final step should be to set up a folder in which you can put your work in. This folder should be easy to get to, such as on the desktop, but if you want to back it up in Dropbox/Google Drive than feel free to do so. This means that you will always have a backup folder to rely on rather than working inside the game's files. After creating this folder, navigate to the games <code>\mods\</code> folder and right click on it. Select '''<tt>Create Shortcut</tt>''' and drag this shortcut to the folder you created before. This will save a lot of time trying to search for this folder, and will help with moving files around.
+
Notes:
 +
* All non-symmetrical models need to be Flipped in the X direction before exporting.
 +
* Accessories can be made with a single layer. Save the current model (i.e. create a .vox file) under the exact same name as the layer, then export the model. This model will be saved under that layer name.
 +
* It is possible to create a Layered object with only using models with no layers. See [[#Layered Voxels]] to see how this can happen.
  
  
== Creating a In-game object ==
+
==== VoxelShop ====
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.  
+
[[File:VoxelShop.png|800px]]
  
 +
'''Avaliable at:''' [https://blackflux.com/node/11 https://blackflux.com/node/11]
  
'''Be sure that before starting, you go through [[#Setting up for Mod Creation]] to avoid pain that may arise during the creation of your mod'''
 
  
=== Creating the Model ===
+
This is the program that is mainly used by Modders for its advantage in editing Staxel's [[Accessory|Accessories]] and large [[Tile|Tiles]].  
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 '''<tt>16</tt>'''. (Such as '''<tt>16x16x16</tt>''', '''<tt>16x32x16</tt>''', '''<tt>48x48x48</tt>''' etc) This allows you to allign the block within the tile.
+
Pros:
* 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.
+
* Free.
* 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?
+
* Supports Layers, and large models.  
 +
* Allows Compresses models by default. (Roughly 75% saving on space per object)
  
 +
Cons:
 +
* Large files can take a long time to load. (Compared to Qubicle.)
 +
* Options and features are a little more obtuse than counterparts. But it is simple to get the hang of once used.
  
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.
 
  
 +
=== Getting Started with Modding ===
 +
Again before we get started, there is a single important thing to mention.
  
Once you are done, you will need to do one thing. Most programs will have their own format for storing voxel models. For example Magica Voxel stores them as '''<tt>*.vox</tt>''' and Voxel Studio stores them as '''<tt>*.vsd</tt>'''. Staxel uses only one format for now, the '''<tt>*.qb</tt>''' file created by Qubicle. As this is a popular format, most of the software avaliable have a way to <tt>"export"</tt> to a '''<tt>*.qb</tt>''' file. So when your model is down, be sure to export the file to the right type, otherwise you will run into issues later. Don't forget about the folder that was setup in the steps before. It's a lot easier to keep track of things when they are all in the same folder.
 
  
 +
'''Keep a backup of your mods.'''
  
=== Adding the Model to Staxel ===
+
This is not an understatement. As with all other situations, you should keep a backup of all things you create. This is doubly true, as the Standalone Launcher (The one provided by Humble) will delete mod files every update. The steam version does not delete files however.
  
Before starting this step, open up the Staxel launcher and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them. If you ever do come to see "Begin Update", remove the files from the <code>\mods\</code> before starting.
 
  
 +
Back to the modding. With a Model editor selected, you can now head on to create an object. There are two major ways to create any object;
  
Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Go to the <code>\mods\</code> folder inside your Staxel installation and create a new folder with the name you want to call the mod. Once that is done, move the '''<tt>*.qb</tt>''' file that you created before in that folder that was created.  
+
* By editing text files.
 +
* By using the Asset Manager.
  
The next thing to do is to create a file with the extension '''<tt>*.tile</tt>''', a good practice would be to name it the same as the model. After creating this object open it up in the text editor of your choice by right clicking the file and choosing open. You may want to set the default program to Notepad or whatever program you want to as this will avoid the need to right click every time. Once this file is open copy the following template into the file.
+
The following two sections will detail how to use each part. Feel free to skip to [[#Finding out how to Create a Specific Thing]], if you just want to get on to modding.
  
<pre>
 
{
 
  "__inherits": "staxel/tileObject/Base.config",
 
  "voxels": "mods/modname/modelname.qb",
 
  "code": "mods.modname.modelname",
 
  "categories": [
 
    "cat1",
 
    "cat2",
 
  ],
 
  "pricing": {
 
    "value": 20.0
 
  }
 
}
 
</pre>
 
  
''If you have a tile that is larger than 1 square, you will need to include a '''<tt>"compound"</tt>''' section in there as well. Look at [[Modding Configs#"compound"]] for more info.''
+
=== Using the AssetManager to Create Mods ===
 +
The Asset Manager is an all-in-one Modding Program for Staxel. It allows you to create and edit new files.
  
Change the temporary names of the stuff inside the text and then save the file. After you have done this, head to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''.
+
'''While Asset Manager is good for creating files and checking them, it is recommended to make / edit mods in a Text Editor. Asset Manager is known to not save some properties.'''
  
When this has started up, click '''<tt>Validate Resources</tt>''' and wait until the progress bar has done. Congratulations, you have now added a tile to Staxel.
+
To get to the Assetmanager do the following;
  
 +
* If you are planning to mod the Standalone (Non-Steam) version, and you have not changed the install directory, paste the following in the [[Media:Search Bar.png|Top bar in Windows Explorer]]: <code>%AppData%/local/staxel.launcher/gamedata/bin/</code>
 +
* If you are planning to mod the Standalone (Non-Steam) version, and but you have changed the directory, you will need to find the folder.
 +
* If you are planning to mod the Steam Version, right-click on Staxel in Steam and click Properties. In the new window, head to the Local Files tab and click Browse Local Files. Head to the <code>/bin/</code> folder from there.
  
==== A small explanation of the *.tile file ====
+
You should be in the <code>/bin/</code> folder by this point. In this folder there will be a program by the name of <code>Staxel.AssetManager.exe</code>. Open this program up.
Feel free to skip this explanation if you "Just want to get the damn thing done!"
+
  
'''<tt>"__inherits"</tt>''' : Simply put, this tells the game "Hey if I'm missing something, look in this file for the stuff." In our case, simply leaving this alone is fine, however you could replace <tt>"base"</tt> with the name of any config tile found in the same folder. (That is <code>"staxel/tileObject/"</code>.) In essence this is used to remove a number of redundent text that would need to appear in every block.
 
  
'''<tt>"code"</tt>''' : This line is basically the ID of the tile. It tells the game what to call the tile. Just like in Minecraft, each tile code must be unique to each other. To accomplish this, the easiest way is just make path that is required to get to the directory, starting from <code>\mods\</code> and with every <tt>"\"</tt> being replaced with a <tt>"."</tt>. For example If the path was <code>"\mods\Awesome\plant"</code>, a good code will be <code>"mods.Awesome.plant"</code> however it isn't necessary. (A code of <code>"bob"</code> could work but might not be unique)
+
You are now looking at the Asset Manager.
  
'''<tt>"voxels"</tt>''' : This is the path to the model that you have created. In our case you would put in something like <code>"mods/modname/tilename.qb"</code>
+
[[File:Asset Manager.png|800px]]
  
'''<tt>"categories"</tt>''' : This is a list of stuff that the game can use to categorise your object. These are mostly used in searching for the object, however certain key phrases are used to sort the object in creative/shipping catalogue. A list of those categories are mentioned at [[Modding Configs#"categories"]]
+
When you open the Asset Manager, options will be grayed out while a progress bar will appear at the bottom. This happens as the Program is trying to load all of the different Objects that is in Staxel. Give the program some time to do this, it will usually take between 10 seconds to a minute.
  
'''<tt>"pricing"</tt>''' : This property sets how much it would cost in the shipping catalogue. Keeping this the same is fine.
 
  
 +
Once the initial load is done, signalled by the green light at the bottom, you can now start creating new assets. Click on the View drop down. Here there is a lot of options, each of which open something new. When creating a new asset, you will need to open up one of these options before continuing. For example, if you wanted to add a new [[Sound]] to the game, you would need to go to View -> Sound Assets.
  
=== Why is my object not placing on anything other than the ground? ===
 
This is a common issue that arises when creating mods. The config that was inherited above, has a specific setting which only allows placing on top of an object. This however can be "fixed" though, by adding another line, and editing it to your preference, in your '''<tt>*.tile</tt>''' file. This line is as follows;
 
  
<pre>
+
When you have opened one of these options you will be greeted with something like this;
"placementDirections" : ["xn", "xp"],
+
</pre>
+
  
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 '''<tt>"xp"</tt>''' 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, '''<tt>"x"</tt>''', '''<tt>"y"</tt>''' and '''<tt>"z"</tt>''' for anything 3D. The second letter is whether you want to go forward or backwards in the direction. This is expressed as positive '''<tt>"p"</tt>''' or negative '''<tt>"n"</tt>'''. 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.
+
[[File:Asset Manager - Tile Assets.png|800px]]
  
For example, if you want to attach an object to the ceiling, you can add the entry '''<tt>"yp"</tt>'''. '''<tt>"y"</tt>''' being the upwards direction and '''<tt>"p"</tt>''' being up.  
+
This new window is where your new thing will get created. But first some explanatory stuff;
  
If you don't know which direction to choose, for example knowing whether it's '''<tt>"x"</tt>''' or '''<tt>"z"</tt>''', or whether it's positive or negative; just try a direction out and see if it works. If it's off by 90 degrees then you have the wrong axis, or if it's off by 180 degrees you have traveled in the wrong direction on the same axis.
+
* On the left, is a list of things. Each of these things is another asset for the game to use. For example, in the picture above <code>mods.coloureditems.stairs.inner.clean.dark1</code> is a tile that was added to the game.
  
With that, your object should be placing in the right spots.
+
* In the top left, there will sometimes be a dropdown. This dropdown allows you to see other items and is commonly used when more than one thing falls under the same heading. For example, there are ''six'' different types of tiles, and as such the dropdown will allow you to select each type.
  
As a side note, there is an option which specifies the opposite direction, "What directions can other objects be attached to this object?". This is specified as '''<tt>"attachmentDirections"</tt>''' and uses the same settings as '''<tt>"placementDirections"</tt>'''.
+
* On the right, is another list. This list contains all the ''properties'' that defines how this thing will act within Staxel. For example, in the picture provided there is a ''property'' name "Bounciness", which controls how much the tile will bounce you when you run into it. If you want to know what a property does, click on it and a description will appear down the bottom. Some of these will have links linking back to this wiki giving more information.
  
== 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.
+
To create a new object, go to the top bar of the new window, and select Asset -> Add -> New Asset. This will pop up a new window like the one below.
{| style="width: 80%;"
+
|-
+
! style="width: 50%;"| 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.
+
|}
+
  
 +
[[File:Asset Manager - New Asset.png]]
  
=== Creating a material ===
+
It will commonly only have two things to fill out, but may change. First click on the button <code>Asset Path</code> and navigate upwards to the <code>/content/</code> folder. Once there, open the <code>/mods/</code> folder and create a new folder. Name this new folder to what you want the mod to be called and then open this new folder. When you open this folder give the asset a name and click save.  
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 <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>''', and then click the '''"Material from tile"''' button. Navigate to your tile that you have just built and open that up. It will then create another file that appends <tt>'''".material.qb"'''</tt>. This file is now the file that the game can use as a material. Feel free to rename this file, and/or get rid of the original file.  
+
You will then be back that the "Add --- Asset" window. Type into the Asset Code box, starting off with "mods." then adding the folder name you just created, followed by a dot and the name of the asset you just made. For example; you can add the following "mods.MyTotallyAwesomeMod.Cup". With this click OK.
  
  
As a quick check, open up the material file in your favourite voxel editor and check if it was what you wanted before continuing.
+
With this you have created a new asset. It would have been automatically been selected. Now all you need to do is edit the stuff to the side. Feel free to muck around with these values. See above for the explanation of what the right side of the panel does again.
  
  
=== Loading the material in the game ===
+
When you have done editing, save the Asset (Either by CRTL + S or by going Asset -> Save -> Asset) then go to Asset -> Validate Assets. If you done something wrong, a Scary Message will come up. These usually will give the information needed in order to fix up your mistake. You will need to edit the appropriate properties in order to fix them however if you don't know how to fix it you can ask at the Discord or Forums.
  
Before starting this step, open up the Staxel launcher and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them. If you ever do come to see "Begin Update", remove the files from the <code>\mods\</code> before starting.
 
  
 +
Once all that is done, close the window but not Asset Manager. Click on Assets -> Build Assets or Assets -> Build and Validate Assets. These will both allow the game to run with your new stuff. With that done, you can look at [[#Finding out how to Create a Specific Thing]] to find out how to mod something.
  
Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Go to the <code>\mods\</code> folder inside your Staxel installation and create a new folder with the name you want to call the mod. Once that is done, move the '''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 '''<tt>*.tile</tt>''', a good practice would be to name it the same as the model. After creating this object open it up in the text editor of your choice by right clicking the file and choosing open. You may want to set the default program to Notepad or whatever program you want to as this will avoid the need to right click every time. Once this file is open copy the following template into the file.
+
=== Using a Text Editor to Create Mods ===
 +
This path is more for the technically minded people. Doing things this way can lead to more headaches as a program won't be helping you along your way. But can allow you to complete things faster.
  
<pre>
+
There are a some things needed before starting this route. The first of which is to make sure you have a text editor to edit files. There are probably two text editors you know of off the top of your head, Notepad and Word. The problem is neither of these make good modding tools. Notepad is very basic and missing a lot of handy features, while Word cannot create the files we are looking for. The fix to this is getting a new text editor.
{
+
  "__inherits": "staxel/tile/Shovelable.config",
+
  "voxels": "mods/modname/modmaterial.qb",
+
  "code": "mods.modname.modmaterial",
+
  "categories": ["block"],
+
  "pricing": {
+
    "value": 10.0
+
  }
+
}
+
</pre>
+
  
Change the temporary names of the stuff inside the text and then save the file. After you have done this, head to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''.  
+
Some good suggestions would be [https://notepad-plus-plus.org/ Notepad++], [https://www.sublimetext.com/ Sublime text] or [https://atom.io/ Atom]. These provide their own benefits, and some can be set to give you contextual highlighting to help visually while editing. However this is ''not needed'' and working with normal notepad is fine.
  
When this has started up, click '''<tt>Validate Resources</tt>''' 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]].
+
Once you have a text editor, you will need to make sure a couple things are done. The first is to make sure that you don't run into problems with either you or the game not recognising files. The best way to do this is to make sure you have file extensions enabled on every file. To do this go to Windows Explorer, click on the view tab at the top, and check the box next to "File Name Extensions". This makes sure you can see the .txt behind text files you create among other things.
  
  
== Creating a Hair Style ==
+
Once you have shown the extensions. First of all, head to the <code>/mods/</code> folder located in your game files. Create a new folder. Name this new folder to what you want the mod to be called and then open this new folder. You can then create new files for yourself. There are two methods, completely creating new files from scratch. Or copying a file already in Staxel's files.  
The hairstyle is the simplest form of customisation that can be added to a player. This is due to the fact that they only encompass a single layer in the voxel model allowing you to focus less on how it moves. That being said there can be some troubles associated with how you create the Hair Style which will be covered later.
+
  
 +
* To create a completely new file, right-click in the empty space of a folder, then go to New -> Text Document. Once created rename the entirety of the text file to something like "mod.tile" or whatever extension you want. Do not keep the ".txt" part of the file name. Once done open this file up in the text editor of your choice. (You may need to specify this upon opening.) When open, add a set of braces <code>{ }</code> to the file.
  
Before beginning, it is a good idea to head over to [[#Setup]] to make sure you have everything setup before starting.
+
* Copy the file to the folder either rename it and/or open it. (You may need to specify this upon opening.)
  
  
=== Creating the Model ===
+
Once that is open, you are ready to head to [[#Finding out how to Create a Specific Thing]]. Although you might want to take a quick look at [[Modding Key Terms]].
The specifics of this step will vary on what type of modelling software that you use, especially considering if your selected voxel editor supports layers.
+
  
==== Modelling Software Supports Layers (Qubicle/VoxelShop) ====
 
To create a Hair Style with these programs follow these steps:
 
# Open the following path, <code>\gamedata\content\staxel\characters\species\</code> and choose a '''<tt>*.qb</tt>''' model to work with. Once you have chosen a model, open this up in your program. (Import if you can't open it.)
 
# Make sure the bounding box is set to '''<tt>64x64x64</tt>''' and that the character model is roughly centered if they weren't already set to this. (VoxelShop is known not to centre an import for example.)
 
# Create another layer and name it "Head" (Case Sensitive). If this fails, name it a temporary name for now. (Like "Head (2)")
 
# Start creating you Hair Style.
 
# Once you have completed your Hair Style, delete every other layer except the one you were working on. (If you gave your layer a temp name, now would be the time to change it.) Once that is done, save or export this model to your folder.
 
  
 +
=== Finding out how to Create a Specific Thing ===
 +
At this point, you are probably wondering, "Are we ever going to get to the actual modding?", well here it is...
  
==== Modelling Software Does Not Supports Layers (Magica Voxel) ====
 
To create a Hair Style with these programs follow these steps:
 
# Open the following path, <code>\gamedata\content\staxel\characters\species\</code> and choose a '''<tt>*.qb</tt>''' model to work with. Once you have chosen a model, open this up in your program. (Import if you can't open it.)
 
# Make sure the bounding box is set to '''<tt>64x64x64</tt>''' and that the character model is roughly centered if they weren't already set to this.
 
# Start creating you Hair Style ontop of the model.
 
# Once you have completed your Hair Style, delete all the voxels that is not your hair's model. Due to the lack of layers, this is needed otherwise the hair would display the body as well.
 
  
At this point, you might need to find out how to name the layer.  
+
Or rather, here is the section that will point you to the places that will explain things. There is a number of different ways to add content in the game, and a single page cannot describe every single way in which Content can be added on a single page.
  
In the case of Magica Voxel, the following steps can be taken:
+
So here is a list of places you can go to find out more information:
# Save the file as a '''<tt>*.vox</tt>''' with the name '''<tt>"Head"</tt>'''. This is case sensitive.
+
* For creating basic Tiles, that is anything you can place in the world: Head to [[Tile#Creating a In-game object]].
# Now export the file to a '''<tt>*.qb</tt>''' with any name, it does not have to be "Head". This has now saved the entire file under the layer name "Head".
+
* For creating your own Hair Style, or Clothing Piece: Head to [[Accessory#Creating an Accessory]]
 +
* For creating basic items: Head to [[Craft Items#Creating a Craft_Item]]
 +
* For other things, look for their specific page at [[:Category:Modding]]
  
For other programs besides Magica Voxel, try a google search to find out the steps in order to name the file.
+
==Creating and Updating a .sxlmod file==
 +
=== Creating a .sxlmod file ===
 +
'''<tt>.sxlmod</tt>''' mods are the preferred method for providing mod files to other players. They provide a way to easily create mods which also does not get deleted upon a Staxel update.  
  
=== Adding the Model to Staxel ===
+
To create a '''<tt>*.sxlmod</tt>''' you will need to follow this procedure;
 +
# Head to <code>C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\</code> and start '''<code>Staxel.ModManager.exe</code>'''
 +
# Head to '''<tt>Sxl Mods → New → Create new Package</tt>'''. Once you have done that follow the instruction set that fit your situation;
 +
# Fill in all the details you want.
 +
# After that is done, drag your mod files, that are underneath the main mod folder (For Example, if your mod is say <tt>"WoodStuff"</tt> drag all the stuff inside the <tt>"WoodStuff"</tt> folder), into the shaded "Drag and Drop" area, to move them into the mod's folder.
 +
# Select OK and the mod is now complete.
  
Before starting this step, open up the Staxel launcher and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them. If you ever do come to see "Begin Update", remove the files from the <code>\mods\</code> before starting.
+
Once the previous instructions have been done, you can then navigate to '''<tt>View → Open Package directory</tt>''' or head to <code>C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\LocalContent\packages\</code> to find your mod file which you can upload to whatever site you choose.
  
  
Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Go to the <code>\mods\</code> folder inside your Staxel installation and create a new folder with the name you want to call the mod. Once that is done, move the '''<tt>*.qb</tt>''' file that you created before in that folder that was created.  
+
=== Updating a .sxlmod file ===
 +
Updating a '''<tt>*.sxlmod</tt>''' file is a simple thing to do. To update the file with new additions;
 +
# Head to <code>C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\</code> and start '''<code>Staxel.ModManager.exe</code>'''
 +
# Highlight the mod you want to update
 +
# Head to '''<tt>Mod → Update Package → From Installation</tt>'''. if you want to update the files based on the already installed mod or '''<tt>From Contents</tt>'''  
 +
# Your mod is now updated. Feel free to share this with others.
  
The next thing to do is to create a file with the extension '''<tt>*.accessory</tt>''', a good practice would be to name it the same as the model. After creating this object open it up in the text editor of your choice by right clicking the file and choosing open. You may want to set the default program to Notepad or whatever program you want to as this will avoid the need to right click every time. Once this file is open copy the following template into the file.
+
One thing to note is that Staxel does not do version control with files. Once you have updated a mod, you cannot get the old one back, unless copies were made.
  
<pre>
 
{
 
"code" : "mods.modname.modelname",
 
"model" : "mods/modname/modelname.qb",
 
"kind" : "Hair",
 
"bodyType" : [ "staxel.bodyType.HumanoidMale", "staxel.bodyType.HumanoidFemale" ]
 
}
 
</pre>
 
  
Change the temporary names of the stuff inside the text and then save the file. After you have done this, head to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''.
+
== Other Staxel Tutorials ==
  
When this has started up, click '''<tt>Validate Resources</tt>''' and wait until the progress bar has done. Congratulations, you have now added a hair style to Staxel.
+
This cheat sheet contains useful links and resources for modding in Staxel.
  
 
+
* Simple modding guide: http://blog.playstaxel.com/creating-mods/
==== A small explanation of this *.accessory file ====
+
* Video tutorial for making and adding hairstyles to Staxel: https://www.youtube.com/watch?v=chW0eI4Y70A
Feel free to skip this explanation if you "Just want to get the damn thing done!"
+
* The 'Mini Mod kit' comes with templates of character pieces to build off of: http://launcher.playstaxel.com/support/MiniModKit.zip
 
+
* Creating content for Staxel using [http://store.steampowered.com/app/454550/ Qubicle - Base Edition]: http://minddesk.com/learn/article.php?id=71&oid=11
'''<tt>"code"</tt>''' : This line is basically the ID of the tile. It tells the game what to call the tile. Just like in Minecraft, each tile code must be unique to each other. To accomplish this, the easiest way is just make path that is required to get to the directory, starting from <code>\mods\</code> and with every <tt>"\"</tt> being replaced with a <tt>"."</tt>. For example If the path was <code>"\mods\Awesome\plant"</code>, a good code will be <code>"mods.Awesome.plant"</code> however it isn't necessary. (A code of <code>"bob"</code> could work but might not be unique)
+
''These may be outdated. If you want more help join the Staxel discord server and people there will be able to help you.''
 
+
'''<tt>"model"</tt>''' : This is the path to the model that you have created. In our case you would put in something like <code>"mods/modname/tilename.qb"</code>
+
 
+
'''<tt>"kind"</tt>''' : This property tells the game, what the object actually is. No need to change this for Hair Styles.
+
 
+
'''<tt>"bodyType"</tt>''' : This property is a list (or more correctly an array) of what body types which support this hairstyle. If you want to make this Hairstyle male only, then remove the Humanoid female reference.
+
 
+
 
+
=== Preparing the Hair Style for Staxel's Palettes ===
+
What was not mentioned before is the system which allows your Hair Style to be of different colours. Staxel has a system in which a "palette" is applied over your model, substituting certain colours with other colours.
+
 
+
If you want to use your own palettes, you do not need to do extra work with the model unless you want to. Head to [[#Creating a Palette for Player Models]] instead.
+
 
+
If you want to incorporate the Staxel palettes then you need to do a couple steps.
+
 
+
# First open up the following palette into any photo editor with an eyedrop tool. <code>\gamedata\content\staxel\palettes\blonde.png</code>
+
# Once that is open, open your Hair Style in the Voxel editor of choice.
+
# Look at the bottom layer of the palette. These are the colours you want to appear in the model. The top layer are the colours your model needs to be for it to appear like the colour below.For example: The top right colour, the dark swamp green, is replaced with the bottom right colour, the yellow-brown colour. You need to start replacing the colours in your model with these swamp/murky greens using the bottom row as the one to determine what to replace.
+
#* You can leave other colours in the model. These colours will then stay constant, no matter what palette is added.
+
# Once all the colours are replaced with their appropriate colour,  save this file over your previous one. (Also replace the one in the mod afterwards).
+
 
+
Once this is done, add the following two lines into the '''<tt>*.accessory</tt>''' file that you made before.
+
 
+
<pre>
+
  "palettes" : [ "staxel.palette.black", "staxel.palette.darkbrown", "staxel.palette.brown", "staxel.palette.blonde", "staxel.palette.grey",
+
    "staxel.palette.red", "staxel.palette.orange", "staxel.palette.yellow", "staxel.palette.green", "staxel.palette.blue", "staxel.palette.purple", "staxel.palette.pink" ],
+
  "defaultPalette" : "staxel.palette.grey"
+
</pre>
+
 
+
The first line, gives the game a list of what palettes that can be used with your Hair Style. This line contains all the currently avaliable Hair Colours. The second line tells the game what palette to default to when choosing/displaying the hairstyle.
+
 
+
Make sure to save the file and then run <tt>Content Builder</tt> again. And with that you should have a Hair Style which has all the Staxel Palette colours with it.
+
 
+
== Creating a Piece of Clothing ==
+
 
+
== Creating a Palette for Player Models ==
+
A palette is basically an optional colour scheme for a given accessory model. Models do not necessarily need to support palettes (you can have a completely unpalettable model designed to only have one colour scheme), but models which are designed to support palettes can essentially have any number of colour schemes limited only by the number of palettes defined.
+
 
+
 
+
'''In essence, a palette is an image with two rows of different colours. The top row of colours are the colours you want to replace, and the bottom row are the colours you want to replace the colour above with.'''
+
 
+
 
+
To create a palette you must first have a model to base the palette off. Without a model, a palette is basically useless. Once you have acquired a model to work with;
+
#You will first need to create an image in your favourite image software. (Photoshop, Gimp, even Paint is fine for this.) The size of the image will be 16 pixels per colour you want to change in the width(For Example if you want to change '''<tt>4 colours</tt>''', you will need to make your image '''<tt>64 pixels</tt>''' wide) while being exactly '''<tt>32 pixels</tt>''' high.
+
#Start by setting the top left most '''<tt>16x16</tt>''' grid to the first colour that you want to change. Once that '''<tt>16x16</tt>''' is filled, fill the '''<tt>16x16</tt>''' to the right of it with the second colour. Keep doing this until all colours are filled. This gives the basis on which your Palette is set.
+
#When that is done, you can now choose which colours you want to replace the originals with, and fill the space underneath that colour. Continue until you are done.
+
#Save it as a '''<tt>"*.png"</tt>''' file. You can now move that to a mod folder but we aren't done yet.
+
 
+
[http://puu.sh/qnbAL/bb7b8b9e3b.png Example of a palette that replaces 4 colours.]
+
 
+
 
+
With that, you have now created the image that is required for a palette. You will then need to create an icon for your palette. This icon gets displayed in the menu representing the palette.
+
#Go back to the image editor, and create another image, this time exactly '''<tt>12x12</tt>''' in size.
+
#Fill this with anything you like, such as having a <tt>"S"</tt> for <tt>"Suzy's Hair Colour"</tt>. A recommendation would be to have a solid colour representing the main colour of your hairstyle.
+
#Save this image as a '''<tt>*.png</tt>''' file. (If you want, name this as the same as the file containing the palette but append <tt>" icon"</tt> to it.)
+
 
+
[http://puu.sh/qnbPO/2d1958e355.png Example of a non-standard Icon to represent a palette.]
+
 
+
 
+
With those two images made, we are now ready to actually tell the game "Hey this is a palette!" So we need to create a '''<tt>*.palette</tt>''' file with the following inside of it;
+
<pre>{
+
  "code" : "mods.modname.uniquenamehere",
+
  "icon" : "mods/Modname/NameOfIcon.png",
+
  "palette" : "mods/Modname/NameOfPalette.png"
+
}</pre>
+
 
+
The <tt>"code"</tt> property is just a unique name for the palette. Set this to be the same as the directory and file name starting at <code>/mods/</code> replacing any <tt>"/"</tt> with <tt>"."</tt>.
+
 
+
The <tt>"icon"</tt> property is the path to the small '''<tt>12x12</tt>''' image you created earlier.
+
 
+
The <tt>"palette"</tt> property is the path to the palette that you created earlier.
+
 
+
 
+
With this the palette is now ready to be added to models. You may now add/edit the following line in any '''<tt>*.accessory</tt>''' file to include the code name from your palette.
+
<pre>"palettes" : [ "mods.modname.palette1", "mods.modname.palette2"] </pre>
+
 
+
And if everything went according to plan, you can now select your custom palette from your model.
+
 
+
 
+
== Adding new sounds ==
+
Staxel also allows you to add new sounds to staxel. The process for doing so is actually quite simple and as long as you know how to get the sounds, the rest shall follow easily.
+
 
+
Before beginning make sure to follow [[#Setting up for Mod Creation]]. There are however two things that you will probably need before getting started however.
+
 
+
First, you need to have an object already made so that you can test the sound. Follow [[#Creating a In-game object]] to create one. Anything will do.
+
 
+
Second, you need to have some sound files already made. As a note, the game only allows '''<tt>*.wav</tt>''' files to be played as sounds. If your sounds are not in this format then you can use [http://www.audacityteam.org/download/ Audacity] and export them to '''<tt>*.wav</tt>''' files.
+
 
+
Once this is done, move the object and the sound files to a new mod folder. Then create a file with an ending of '''<tt>.sound</tt>''', and place the following into it.
+
 
+
<pre>
+
{
+
  "code" : "mods.modname.modsoundname",
+
  "sounds" : [
+
    {
+
      "file" : "mods/modname/modsoundname1",
+
      "volume" : 0.4
+
    },
+
    {
+
      "file" : "mods/modname/modsoundname2",
+
      "volume" : 0.4
+
    }
+
  ]
+
}
+
</pre>
+
 
+
You can replace the temporary names with whatever will work for your mod. '''Do not add .wav to the end of the file. The game automatically adds this.''' Now in this example it shows 2 sound files added. You can add any number of sounds from 1 to some large number, and the game will just randomly select a sound from the list. If you only have one sound, then remove the content between the '''<tt>{ }</tt>''' and remove the preceding comma.
+
 
+
Congrats you have created your sound. Now to get an object to play it, add the following line to the object's '''<tt>*.tile</tt>''' file.
+
 
+
<pre>
+
"stepSoundGroup" : "mods.modname.modsoundname"
+
</pre>
+
 
+
Once this line is added in, head to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''. When this has started up, click '''<tt>Validate Resources</tt>''' and wait until the progress bar has done. Now you can load up and hear your sound whenever you walk over your object.
+
 
+
 
+
=== Compressing the file ===
+
Staxel also has the option to compress these files to save space but not lose quality. Before doing this, you will want to make sure you have a backup of the sound file, as it will be overwritten. You can compress your file by simply heading to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''.  When this has started up, click '''<tt>Compress .wav assests</tt>''', wait a moment and then click '''<tt>Validate Resources</tt>''' and wait until the progress bar has done. Now all the sound assests you added are compressed and will still run in staxel.
+
 
+
 
+
== Hooks ==
+
These hooks allow you to access the guts of Staxel's code without the need to edit any of Staxel's files.
+
 
+
[[ModdingHooks]]
+
 
+
 
+
== Layered Voxels ==
+
 
+
Some parts of staxel uses layered voxel files, like clothing.
+
If your voxel editor doesn't support layers you can also try using a .layered file, which allows for building a layered model out of several other files.
+
 
+
example.layered:
+
<code>
+
{
+
"layers": {
+
"Head" : "mods/example/HeadLayer.qb"
+
}
+
}
+
</code>
+
<!-- == Directories == -->
+
<!-- == localhost:8086 == -->
+
<!-- == Fileformats == -->
+
  
  
 
= Staxel Modding Programs =
 
= Staxel Modding Programs =
== Voxel Modelling Software ==
+
''Section to be updated''
 
+
== Asset Manager ==
'''Qubicle''' : Paid Voxel software. Used by the Staxel Dev team. It has a lots of tools and options, but you will need to buy it to be able to export .qb and use other features. Some features are locked behind DLC but a free trail is available.
+
 
+
[http://www.minddesk.com/ Available at minddesk.com]
+
 
+
'''MagicaVoxel''' : Free software. Its very easy to use however it doesn't have support for layers and doesn't have proper selection tools. Also has a max size of 126^3. (May cause trouble with terrain tiles.) See [[#Modding for Staxel with Magica Voxel]] for more info.
+
 
+
[https://ephtracy.github.io/ Available at ephtacy.github.io]
+
 
+
'''VoxelShop''' : Free software. Similar to Magicavoxel, but offers layer support, selection support. Doesn't have a max size.
+
 
+
[https://blackflux.com/node/11 Available at blackflux.com]
+
 
+
 
+
There are others not listed here, but these prove to be the most popular in the Staxel community.
+
 
+
== AssetManager ==
+
 
+
The Asset Manager is an all-in-one asset management system for Staxel. The default path for the Asset Manager is '<user id>/appdata/local/staxel.launcher/gamedata/bin/staxel.assetmanager.exe'.
+
 
+
 
Start by loading the content system ('''"File->Load Asset Directory"''', this will be done automatically if the option is checked in your preferences ('''"Edit->Preferences"''')). Everything, except building assets or using the "Create Material Models From Tile Models" tool, requires the content system to be loaded.
 
Start by loading the content system ('''"File->Load Asset Directory"''', this will be done automatically if the option is checked in your preferences ('''"Edit->Preferences"''')). Everything, except building assets or using the "Create Material Models From Tile Models" tool, requires the content system to be loaded.
 
From there you may begin using tools (under '''"Tools"''' in the top menu) or editing assets. To edit assets, open the window for the type of asset you wish to edit (under '''"View"''' in the top menu, or press '''CTRL+Shift+1-9''') and have at it.
 
From there you may begin using tools (under '''"Tools"''' in the top menu) or editing assets. To edit assets, open the window for the type of asset you wish to edit (under '''"View"''' in the top menu, or press '''CTRL+Shift+1-9''') and have at it.
  
The Live Content System ('''"View->Content System Live"''') shows you exactly what is in Staxel's content directory, and let's you manage (create/delete) files and folders within the content directory safely.
+
The Live Content System ('''"View->Content System Live"''') shows you exactly what is in Staxel's content directory, and lets you manage (create/delete) files and folders within the content directory safely.
  
 
The Asset Manager also comes with a Mod Manager ('''"View->Mod Manager"'''). The Mod Manager allows you to create mod packages ('''*.sxlmod''' files) and (un)install them, and delete them, whenever you please. Creating a mod package (in the Mod Manager click '''"Mod->New->Create New Package..."''') is as simple as selecting files to include in the mod and choosing a name for the mod. Once that is done the mod package is ready to be shared or installed at your convenience. To install or uninstall mods select the mod packages from the list and either click '''"Mod->Install Packages/Uninstall Mods"''' or right-click the selected packages and click '''"Install Packages/Uninstall Mods"''' from the menu. Files from an installed mod that have been edited (by yourself, hopefully) will not be uninstalled, but may be overwritten by reinstalling the associated mod package (assuming the file comes from the associated mod package). Installed mods must be built (if not already, and/or validated) by clicking the '''"File->All Assets->Build and Validate Assets"''' button in the Asset Manager. This can be done for you  automatically, or turned off, by changing the appropriate setting ('''"Automatically Build Mods After Installation"''') in your preferences.
 
The Asset Manager also comes with a Mod Manager ('''"View->Mod Manager"'''). The Mod Manager allows you to create mod packages ('''*.sxlmod''' files) and (un)install them, and delete them, whenever you please. Creating a mod package (in the Mod Manager click '''"Mod->New->Create New Package..."''') is as simple as selecting files to include in the mod and choosing a name for the mod. Once that is done the mod package is ready to be shared or installed at your convenience. To install or uninstall mods select the mod packages from the list and either click '''"Mod->Install Packages/Uninstall Mods"''' or right-click the selected packages and click '''"Install Packages/Uninstall Mods"''' from the menu. Files from an installed mod that have been edited (by yourself, hopefully) will not be uninstalled, but may be overwritten by reinstalling the associated mod package (assuming the file comes from the associated mod package). Installed mods must be built (if not already, and/or validated) by clicking the '''"File->All Assets->Build and Validate Assets"''' button in the Asset Manager. This can be done for you  automatically, or turned off, by changing the appropriate setting ('''"Automatically Build Mods After Installation"''') in your preferences.
Line 473: Line 268:
  
 
''[More comprehensive help section coming...]''
 
''[More comprehensive help section coming...]''
 
  
 
== ContentBuilder ==
 
== ContentBuilder ==
Line 480: Line 274:
  
  
=Changelog=
+
= Extras =
7/02/2017
+
== Layered Voxels ==
* Added a tutorial for making sounds.
+
Some parts of staxel uses layered voxel files, like clothing.
* Added a tutorial for making materials.
+
If your voxel editor doesn't support layers you can also try using a .layered file, which allows for building a layered model out of several other files.
* Added a section to objects to address issues with placing
+
 
* Other minor changes.
+
example.layered:
21/01/2017
+
<code>
* Added a tutorial for making hair styles.
+
{
19/01/2017
+
  "layers": {
* Revamped the previous tile modding tutorial, to one that is up to date and simpler.
+
    "Head" : "mods/example/HeadLayer.qb"
16/09/2016
+
  }
*Changed Pricing attribute to <code>pricing : { "value" : 0 }</code> due to today's released update.
+
}
 +
</code>

Latest revision as of 01:01, 12 July 2019

This page is meant to give an overview into Staxel's modding systems and give you insight into how to install, modify and create your own mods in the game.


Please note this page, and the game itself, is a Work In Progress. Many things are likely to change with the modding systems and any of these methods can be made obsolete at any time.


Head to Category:Modding to look for a specific item to Mod. Most items includes tutorials on how to implement those items within their pages.


Installing Mods

Only install mods that come from trusted sources. Staxel, and related parties, are not liable for any damage done to your computer by installing mods.

There are a couple things you should note when installing mods;

  • Modded Installations will always fail validation attempts.
  • Mods need to be reinstalled after every update.
  • You do not need to install content mods when wanting to join a content modded server.


Installing a .sxlmod file

A *.sxlmod is basically a .zip file with a little extra information pertaining to the mod. To install it follow these instructions;

  1. Move the *.sxlmod to the following folder: C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\LocalContent\packages\
  2. Start the staxel launcher and press the mod manager button in the top left. Alternatively if that does not work, head to C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\ and start Staxel.ModManager.exe
  3. Once the mod manager is started, you will see the mod that you just moved into the folder. To install it, click on it to highlight it then go to Mod → Install Package
  4. Once the progress bar is finished, you are now free to play with your mods. Enjoy!

As this is a *.sxlmod file, the mod file will not be deleted upon update. However you will need to repeat steps 2-4 for every update.

[An example .sxlmod will be added here in the future.]


Installing a normal mod folder or .zip file

Note: These files will get destroyed every update forcing you to repeat these steps every update. If you want to update the mod in order to keep the files in a singular spot, head to #Creating a .sxlmod file and follow those instructions.

To install these files;

  1. Move and/or extract these files to this directory: C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\Content\mods (Avoid copying two mods into the same folder. And do not place individual items in the \mods\ directory.)
  2. After that is done, head on over to C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\ and start Staxel.ContentBuilder.exe
  3. Once the content builder is started. Click the Validate Resources button in the top left.
  4. Once the progress bar stops, you are ready to play. Enjoy!

Example mod: launcher.playstaxel.com/examples/grassSnow.zip (thanks to scornedbythenine)


Creating Mods

Getting Started with Staxel Modding

Staxel modding is easy to get into. Unlike other games, with Staxel you do not need to touch a single piece of code in order to create Tiles, Villagers or Clothing/Hair Styles. All you need in these cases, is a modelling program that supports making voxel models, and some patience.


Choosing a Modelling Program

To start off with, you will need to choose a Voxel editing program that will allow you to create models. There are three major programs that are in use by Modders in Staxel. Each program will have it's quirks, but each can be easily used to create models and you should choose the one that best suits your needs/wants.

Qubicle

Qubicle.png

Avaliable at: http://www.minddesk.com/


This is the program that is used by Staxel's artists and other members of the dev team. It is mostly guaranteed to work all models, especially Character Models and Tile Materials.

Pros:

  • Works with Staxel, even includes some of staxels models under the /Games/ toolbar.
  • Compresses models by default. (Roughly 75% saving on space per object)
  • No obvious object size or colour limits.

Cons:

  • Costs money to buy it, but does come with a free trial.
  • Certain features are locked behind DLC. Most features are not needed though.


MagicaVoxel

MagicaVoxel.png

Avaliable at: https://ephtracy.github.io/

This is the program used by most Modders. It is easy to use, it is responsive and comes with most of the basic features. It is however lacking in a couple areas which make creating certain Objects a pain. It is under development, and more features are being added to it.

Pros:

Cons:

  • Unable to work with Layers. (Although version 99a has introduced layers in World mode.) Accessories can still be made with this. See notes.
  • Size limits. As such cannot open Tile Material models properly. (World mode can create larger objects, but individual objects can't be imported to that size yet.)
  • Does not compress files.

Notes:

  • All non-symmetrical models need to be Flipped in the X direction before exporting.
  • Accessories can be made with a single layer. Save the current model (i.e. create a .vox file) under the exact same name as the layer, then export the model. This model will be saved under that layer name.
  • It is possible to create a Layered object with only using models with no layers. See #Layered Voxels to see how this can happen.


VoxelShop

VoxelShop.png

Avaliable at: https://blackflux.com/node/11


This is the program that is mainly used by Modders for its advantage in editing Staxel's Accessories and large Tiles.

Pros:

  • Free.
  • Supports Layers, and large models.
  • Allows Compresses models by default. (Roughly 75% saving on space per object)

Cons:

  • Large files can take a long time to load. (Compared to Qubicle.)
  • Options and features are a little more obtuse than counterparts. But it is simple to get the hang of once used.


Getting Started with Modding

Again before we get started, there is a single important thing to mention.


Keep a backup of your mods.

This is not an understatement. As with all other situations, you should keep a backup of all things you create. This is doubly true, as the Standalone Launcher (The one provided by Humble) will delete mod files every update. The steam version does not delete files however.


Back to the modding. With a Model editor selected, you can now head on to create an object. There are two major ways to create any object;

  • By editing text files.
  • By using the Asset Manager.

The following two sections will detail how to use each part. Feel free to skip to #Finding out how to Create a Specific Thing, if you just want to get on to modding.


Using the AssetManager to Create Mods

The Asset Manager is an all-in-one Modding Program for Staxel. It allows you to create and edit new files.

While Asset Manager is good for creating files and checking them, it is recommended to make / edit mods in a Text Editor. Asset Manager is known to not save some properties.

To get to the Assetmanager do the following;

  • If you are planning to mod the Standalone (Non-Steam) version, and you have not changed the install directory, paste the following in the Top bar in Windows Explorer: %AppData%/local/staxel.launcher/gamedata/bin/
  • If you are planning to mod the Standalone (Non-Steam) version, and but you have changed the directory, you will need to find the folder.
  • If you are planning to mod the Steam Version, right-click on Staxel in Steam and click Properties. In the new window, head to the Local Files tab and click Browse Local Files. Head to the /bin/ folder from there.

You should be in the /bin/ folder by this point. In this folder there will be a program by the name of Staxel.AssetManager.exe. Open this program up.


You are now looking at the Asset Manager.

Asset Manager.png

When you open the Asset Manager, options will be grayed out while a progress bar will appear at the bottom. This happens as the Program is trying to load all of the different Objects that is in Staxel. Give the program some time to do this, it will usually take between 10 seconds to a minute.


Once the initial load is done, signalled by the green light at the bottom, you can now start creating new assets. Click on the View drop down. Here there is a lot of options, each of which open something new. When creating a new asset, you will need to open up one of these options before continuing. For example, if you wanted to add a new Sound to the game, you would need to go to View -> Sound Assets.


When you have opened one of these options you will be greeted with something like this;

Asset Manager - Tile Assets.png

This new window is where your new thing will get created. But first some explanatory stuff;

  • On the left, is a list of things. Each of these things is another asset for the game to use. For example, in the picture above mods.coloureditems.stairs.inner.clean.dark1 is a tile that was added to the game.
  • In the top left, there will sometimes be a dropdown. This dropdown allows you to see other items and is commonly used when more than one thing falls under the same heading. For example, there are six different types of tiles, and as such the dropdown will allow you to select each type.
  • On the right, is another list. This list contains all the properties that defines how this thing will act within Staxel. For example, in the picture provided there is a property name "Bounciness", which controls how much the tile will bounce you when you run into it. If you want to know what a property does, click on it and a description will appear down the bottom. Some of these will have links linking back to this wiki giving more information.


To create a new object, go to the top bar of the new window, and select Asset -> Add -> New Asset. This will pop up a new window like the one below.

Asset Manager - New Asset.png

It will commonly only have two things to fill out, but may change. First click on the button Asset Path and navigate upwards to the /content/ folder. Once there, open the /mods/ folder and create a new folder. Name this new folder to what you want the mod to be called and then open this new folder. When you open this folder give the asset a name and click save.

You will then be back that the "Add --- Asset" window. Type into the Asset Code box, starting off with "mods." then adding the folder name you just created, followed by a dot and the name of the asset you just made. For example; you can add the following "mods.MyTotallyAwesomeMod.Cup". With this click OK.


With this you have created a new asset. It would have been automatically been selected. Now all you need to do is edit the stuff to the side. Feel free to muck around with these values. See above for the explanation of what the right side of the panel does again.


When you have done editing, save the Asset (Either by CRTL + S or by going Asset -> Save -> Asset) then go to Asset -> Validate Assets. If you done something wrong, a Scary Message will come up. These usually will give the information needed in order to fix up your mistake. You will need to edit the appropriate properties in order to fix them however if you don't know how to fix it you can ask at the Discord or Forums.


Once all that is done, close the window but not Asset Manager. Click on Assets -> Build Assets or Assets -> Build and Validate Assets. These will both allow the game to run with your new stuff. With that done, you can look at #Finding out how to Create a Specific Thing to find out how to mod something.


Using a Text Editor to Create Mods

This path is more for the technically minded people. Doing things this way can lead to more headaches as a program won't be helping you along your way. But can allow you to complete things faster.

There are a some things needed before starting this route. The first of which is to make sure you have a text editor to edit files. There are probably two text editors you know of off the top of your head, Notepad and Word. The problem is neither of these make good modding tools. Notepad is very basic and missing a lot of handy features, while Word cannot create the files we are looking for. The fix to this is getting a new text editor.

Some good suggestions would be Notepad++, Sublime text or Atom. These provide their own benefits, and some can be set to give you contextual highlighting to help visually while editing. However this is not needed and working with normal notepad is fine.


Once you have a text editor, you will need to make sure a couple things are done. The first is to make sure that you don't run into problems with either you or the game not recognising files. The best way to do this is to make sure you have file extensions enabled on every file. To do this go to Windows Explorer, click on the view tab at the top, and check the box next to "File Name Extensions". This makes sure you can see the .txt behind text files you create among other things.


Once you have shown the extensions. First of all, head to the /mods/ folder located in your game files. Create a new folder. Name this new folder to what you want the mod to be called and then open this new folder. You can then create new files for yourself. There are two methods, completely creating new files from scratch. Or copying a file already in Staxel's files.

  • To create a completely new file, right-click in the empty space of a folder, then go to New -> Text Document. Once created rename the entirety of the text file to something like "mod.tile" or whatever extension you want. Do not keep the ".txt" part of the file name. Once done open this file up in the text editor of your choice. (You may need to specify this upon opening.) When open, add a set of braces { } to the file.
  • Copy the file to the folder either rename it and/or open it. (You may need to specify this upon opening.)


Once that is open, you are ready to head to #Finding out how to Create a Specific Thing. Although you might want to take a quick look at Modding Key Terms.


Finding out how to Create a Specific Thing

At this point, you are probably wondering, "Are we ever going to get to the actual modding?", well here it is...


Or rather, here is the section that will point you to the places that will explain things. There is a number of different ways to add content in the game, and a single page cannot describe every single way in which Content can be added on a single page.

So here is a list of places you can go to find out more information:

Creating and Updating a .sxlmod file

Creating a .sxlmod file

.sxlmod mods are the preferred method for providing mod files to other players. They provide a way to easily create mods which also does not get deleted upon a Staxel update.

To create a *.sxlmod you will need to follow this procedure;

  1. Head to C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\ and start Staxel.ModManager.exe
  2. Head to Sxl Mods → New → Create new Package. Once you have done that follow the instruction set that fit your situation;
  3. Fill in all the details you want.
  4. After that is done, drag your mod files, that are underneath the main mod folder (For Example, if your mod is say "WoodStuff" drag all the stuff inside the "WoodStuff" folder), into the shaded "Drag and Drop" area, to move them into the mod's folder.
  5. Select OK and the mod is now complete.

Once the previous instructions have been done, you can then navigate to View → Open Package directory or head to C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\LocalContent\packages\ to find your mod file which you can upload to whatever site you choose.


Updating a .sxlmod file

Updating a *.sxlmod file is a simple thing to do. To update the file with new additions;

  1. Head to C:\Users\[Your username here]\%localappdata%\Staxel.Launcher\gamedata\bin\ and start Staxel.ModManager.exe
  2. Highlight the mod you want to update
  3. Head to Mod → Update Package → From Installation. if you want to update the files based on the already installed mod or From Contents
  4. Your mod is now updated. Feel free to share this with others.

One thing to note is that Staxel does not do version control with files. Once you have updated a mod, you cannot get the old one back, unless copies were made.


Other Staxel Tutorials

This cheat sheet contains useful links and resources for modding in Staxel.

These may be outdated. If you want more help join the Staxel discord server and people there will be able to help you.


Staxel Modding Programs

Section to be updated

Asset Manager

Start by loading the content system ("File->Load Asset Directory", this will be done automatically if the option is checked in your preferences ("Edit->Preferences")). Everything, except building assets or using the "Create Material Models From Tile Models" tool, requires the content system to be loaded. From there you may begin using tools (under "Tools" in the top menu) or editing assets. To edit assets, open the window for the type of asset you wish to edit (under "View" in the top menu, or press CTRL+Shift+1-9) and have at it.

The Live Content System ("View->Content System Live") shows you exactly what is in Staxel's content directory, and lets you manage (create/delete) files and folders within the content directory safely.

The Asset Manager also comes with a Mod Manager ("View->Mod Manager"). The Mod Manager allows you to create mod packages (*.sxlmod files) and (un)install them, and delete them, whenever you please. Creating a mod package (in the Mod Manager click "Mod->New->Create New Package...") is as simple as selecting files to include in the mod and choosing a name for the mod. Once that is done the mod package is ready to be shared or installed at your convenience. To install or uninstall mods select the mod packages from the list and either click "Mod->Install Packages/Uninstall Mods" or right-click the selected packages and click "Install Packages/Uninstall Mods" from the menu. Files from an installed mod that have been edited (by yourself, hopefully) will not be uninstalled, but may be overwritten by reinstalling the associated mod package (assuming the file comes from the associated mod package). Installed mods must be built (if not already, and/or validated) by clicking the "File->All Assets->Build and Validate Assets" button in the Asset Manager. This can be done for you automatically, or turned off, by changing the appropriate setting ("Automatically Build Mods After Installation") in your preferences. Importing a mod package is also simple. Click "Mod->New->Add Existing Package" to import a package (perhaps passed on from a friend) into your package directory. The Mod Manager can also attempt to convert a .zip file, while it's being import, into a mod package, but it has one rule: all files inside the .zip must be inside a single root directory (e.g. "MyMod/block.tile"). The reason for this is that the Mod Manager tries it's best not to break paths used in the assets (e.g. block.tile might reference the model "MyMod/block.qb" which would break if block.qb is not in the MyMod directory). Finally, mod packages can be edited in two ways: by updating them via their installation directories (e.g. MyMod.sxlmod might update it's files from "mods/MyMod"), or by editing their contents manually. Both methods are under "Mod->Update Package".

While editing assets, it is sometimes helpful to view the asset's source file. To do this quickly, open an asset window and click "View->Source->File". The source file will be opened in an editor of your choosing, specified in your preferences. If you like, you can provide arguments to the editor in the preferences. If the arguments are left empty the asset's source path will be provided, otherwise, you can use the macro $(fpath) which will be replaced by the asset's source path (e.g. "/f $(fpath)" may be expanded to "/f C:\dirt.tile"). You may also like to open the directory containing the asset's source file via "View->Source->File in Directory".

If you have made changes to any assets, or have added new model files, and are ready to use them in Staxel, it is a good idea to make sure that all your assets are valid and your model files are converted into the format used by Staxel. To do this, click "File->All Assets->Build and Validate Assets". Don't forget to save your assets (in each asset window, "Asset->Save->All Assets") before doing so, however.

[More comprehensive help section coming...]

ContentBuilder

Content builder ( %localappdata%Staxel.Launcher\gamedata\bin\Staxel.ContentBuilder.exe ) is a tool used to prepare assets to be used by the game, it needs to be run when adding mods to a server.


Extras

Layered Voxels

Some parts of staxel uses layered voxel files, like clothing. If your voxel editor doesn't support layers you can also try using a .layered file, which allows for building a layered model out of several other files.

example.layered: {

 "layers": {
   "Head" : "mods/example/HeadLayer.qb"
 }

}