Revision as of 04:23, 19 January 2017

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.

If you are looking for config options, head on over to Modding Configs for more in depth information.

Most Recent change: 19/01/17 #Changelog

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

Staxel Modding Cheat Sheet

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

• Simple modding guide: http://blog.playstaxel.com/creating-mods/
• Video tutorial for making and adding hairstyles to Staxel: https://www.youtube.com/watch?v=chW0eI4Y70A
• 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 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

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 Mod → 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.

Creating a In-game object/tile

Setup

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.

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

Do not use Word or similar programs. They do not work in plain text and therefore will not work for the format needed.

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 \mods\ folder and right click on it. Select Create Shortcut 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.

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.

• If you are creating something that is not a full block, keep the Bounding Box, the box which tells you where you can build, in increments of 16. (Such as 16x16x16, 16x32x16, 48x48x48 etc)
• Keep in mind the size of the object. The player is X blocks high, x 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, many pixel art tutorials will help with understanding how to create voxels as the same underlying principles still apply.
• Try looking up an object and try recreating that. It can be helpful to view it 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 avaliable. If there is an update avaliable, 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/tile/Mineable.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 "mineable" with "axeable" or "shovelable". 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.

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;

1. 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 4 colours, you will need to make your image 64 pixels wide) while being exactly 32 pixels high.
2. Start by setting the top left most 16x16 grid to the first colour that you want to change. Once that 16x16 is filled, fill the 16x16 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.
3. 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.
4. Save it as a "*.png" file. You can now move that to a mod folder but we aren't done yet.

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.

1. Go back to the image editor, and create another image, this time exactly 12x12 in size.
2. Fill this with anything you like, such as having a "S" for "Suzy's Hair Colour". A recommendation would be to have a solid colour representing the main colour of your hairstyle.
3. Save this image as a *.png file. (If you want, name this as the same as the file containing the palette but append " icon" to it.)

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 *.palette file with the following inside of it;

{
  "code" : "mods.modname.uniquenamehere",
  "icon" : "mods/Modname/NameOfIcon.png",
  "palette" : "mods/Modname/NameOfPalette.png"
}

The "code" property is just a unique name for the palette. Set this to be the same as the directory and file name starting at /mods/ replacing any "/" with ".".

The "icon" property is the path to the small 12x12 image you created earlier.

The "palette" 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 *.accessory file to include the code name from your palette.

"palettes" : [ "mods.modname.palette1", "mods.modname.palette2"] 

And if everything went according to plan, you can now select your custom palette from your model.

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: { "layers": { "Head" : "mods/example/HeadLayer.qb" } }

Staxel Modding Programs

Voxel Modelling Software

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.

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.

Available at ephtacy.github.io

VoxelShop : Free software. Similar to Magicavoxel, but offers layer support, selection support. Doesn't have a max size.

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

Changelog

19/01/2017

• Revamped the previous tile modding tutorial, to one that is up to date and simpler.

16/09/2016

• Changed Pricing attribute to pricing : { "value" : 0 } due to today's released update.