Modding

Modding for Staxel with Magica Voxel

MagicaVoxel can be downloaded at this location: [1] Please use the most current version. Tutorial written for Ver.97

STAXEL ERASES THE MODS FOLDER EVERY TIME IT UPDATES!

Having your working file *.vox and your object file *.qb saved separately in a backup folder is rule #1 for modding in Staxel. Copy finished files from this location into Staxel after it has updated.

- How objects behave in Staxel

Staxel uses world co-ordinates broken up into 16 Voxel square regions. Created Objects will conform to this grid. Within MagicaVoxel, created objects lay upon the ground plane and exist within a working space bounding box of white lines and a grid. Objects created in MagicaVoxel export to Staxel within this bounding box. The X,Y,Z coordinates of the bounding box are locked to the 16 X 16 grid, even if your model is mostly built to one corner. So far, the 'front' of your model is side with the green line, the Y Axis.

Example of the work area:[2]

- Exporting to Staxel

When your model is ready, assuming it has a primary side to face a specific direction, make sure this side of the model is looking over the green line. MagicaVoxel exports to several file types. Export your model to a .qb file by expanding the Export button at the bottom right of the window and clicking on 'QB.' This opens a dialogue box that asks where to save the file. Save your object to a folder outside of Staxel with a proper name.

After making sure Staxel has updated through the launcher, go to C:\User\yourusername\AppData\Local\Staxel.Launcher\gamedata\content\mods. If you need help finding the AppData folder, search for Windows AppData Folder and you'll see how to un-hide it. Now that you're in mods, create a new folder and name it either for the object you are making or the object set it is a part of. Copy and paste your *.qb file here.

In order for your model to show up in Staxel, it needs a *.tile file to accompany it. For simplicity, copy and past the *.tile file from another object in the Staxel Folder. Open the file in Windows Notepad and you should see something like this:

{ "__inherits" : "staxel/tileObject/base.config", "code" : "staxel.tileObject.serverVillage.exterior.SignPost", "voxels" : "staxel/tileObject/serverVillage/exterior/SignPost.qb", "attachToBelow" : true, "stepSoundGroup" : "staxel.sounds.WoodFootSteps", "collision" : true, "randomizePosition" : false, "compound" : { "size" : { "x" : 1, "y" : 3, "z" : 1 }, "specification" : " C C X" }, "categories" : [ "white", "brown", "misc" ] }

For your mod to work, edit the following lines of code, then save the tile file into the same folder as your object.

"code" : "staxel.tileObject.serverVillage.exterior.SignPost", Change this line to say "mods.YourModFolderName.YourModsFileName" Do not include the file type here.

"voxels" : "staxel/tileObject/serverVillage/exterior/SignPost.qb", Change this line to say "mods/YourModFolderName/YourModsFileName.qb Make sure to include the file type here.

"attachToBelow" : true, This can be true or false. True makes your model stick to the ground plane correctly. Great for objects that have to sit on the ground. False locks the object to the 16 X 16 grid. Great for objects that have to stack regularly and correctly, like bridge pieces or building objects.

"collision" : true, This can be true or false. True makes the object physical, can be stood upon. False makes the object nonphysical, can be passed through.

"randomizePosition" : false, Object Jitter. Bold text assigns a random amount of x and/or y value when placed. Great for multiple objects in a room to look more natural. Bold text locks the object where you built it in the bounding box, locked to the 16 x 16 grid. Great for building objects that must stay correctly spaced.

"compound" : { "size" : { "x" : 1, "y" : 3, "z" : 1 }, "specification" : " C C X" }, Information Required, Not fully understood

"categories" : [ "white", "brown", "misc" ] Causes the object to show up in specific places in the interface when the player selects a bias for the color or object type specified here.

So long as the file locations are correct and you've decided how your object is supposed to behave in world, save this file from notepad and open the Contend Builder program. Found within C:\Users\YourUserName\AppData\Local\Staxel.Launcher\gamedata\bin, this program must run without error in order for your mod to be present in the game. When done, the progress window will close and you are ready to start Staxel up and use your modded item.

Error Examples and Corrections coming soon

For now, your object ends up in a list of other staxel objects based upon alphabetical hierarchy. If you don't immediately see your object in the TAB window, type in the objects name and it should turn up. If you are still having trouble, check your work flow, make corrections and if you're still unable to get by, check with the Forums. We'll set you straight.

Installing a mod

You do not need to install content mods when wanting to join a content modded server.

Mods go into the Content/mods directory ( %localappdata%\Staxel.Launcher\gamedata\Content\mods )

Every mod should have its own directory there, file should not be left in the directory itself.

When making a mod, make sure the use a unique mod prefix (mods.[yourmod]. namespace prefix and not the staxel. prefix) for newly added assets.

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

Mods need to be reinstalled after updates, and a modded installation will be detected as failing validation.

Only install mods from trusted sources.

Contentbuilder needs to be run after installing a mod.

Alternatively, if working with *.sxlmod packages, see AssetManager for details about the Mod Manager.

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.

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

Hooks

ModdingHooks

Voxel Modelling Software

Qubicle : Best Voxel software, has a lot of tools and options, but you will need to buy it to be able to export .qb and use other features. VoxelShop : Free software, with basic tools, but has layers (for making .accessory mods), has a big range of tools. MagicaVoxel : Free software, its very easy to use, it doesn't have layers, see next heading.

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