Revision as of 06:27, 3 October 2017

In Staxel, *.accessory files are a files which specify an object that should be attached to a player. This includes Hats, Eyes, Shirts, Pants (Trousers), Shoes, Hair and other Accessories.

All accessories are defined in the same way, however Eyes and Hairs are not available in the catalogues and only available in the customisation menu, while other accessories can be in both.

Creating an Accessory

Creating an accessory, whether that be a shirt or a hair style, is fairly simple. There is one catch however, certain articles of clothing need voxels defined on differing layers in order to move with the model as it moves. Hair styles, Hats, Accessories and Eyes won't often need multiple layers while most others will need at least two layers.

Articles of clothing that need 2 or more layers, will have problems when you create them in a program that doesn't support layers. However Staxel does have a way to fix this. (This method may or may not be broken at this point in time.)

Creating the Model

The specifics of this step will vary on what type of modelling software that you use and what you aim to create. If your voxel editor supports layers than it is good to go, otherwise special steps may be needed in order to create the files[s] that will be loaded into Staxel.

Before beginning, it is a good idea to head over to Modding#Setting_up_for_Mod_Creation to make sure you have everything setup before starting.

Creating a Single Layered Accessory

To create an accessory follow these steps:

1. Open the following path, \gamedata\content\staxel\characters\species\ and choose a *.qb model to work with. Once you have chosen a model, open this up in your program. (Import if you can't open it.)
2. Make sure the bounding box in the program is set to 64x64x64 and that the character model is roughly centered if they weren't already set to this. (VoxelShop is known not to center an import for example.)
3. Create another layer and name it "Head" (Case Sensitive). If this fails, name it a temporary name for now. (Like "Head (2)").
   1. If you can't create or name Layers, such as in Magica Voxel, then additional methods may need to be followed. These will be detailed below.
4. Start creating you Accessory.
5. Once you have completed your Hair Style, delete every other layer, and any voxels not needed by your accessory, 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.

Your model is now complete and is ready to go.

In the case of Magica Voxel, the following steps will need to be taken:

1. Save the file as a *.vox with the name of the layer. This is case sensitive.
2. Now export the file to a *.qb with any name, it does not have to be as the layer. This has now saved the entire file under the layer name specified.

And this allows your model from Magica Voxel to work.

For other programs besides Magica Voxel, try a google search to find out the steps in order to name the file.

Creating a Multi Layered Accessory

Layer Supporting Programs

This largely follows the Single layered guide. So read the passage above however remember this extra information.

• Arms and legs have multiple parts to them. Be sure you make voxels near them on the right layer. You may also need to overlap some voxels in order to avoid gaps.
• Make sure you name each layer you create the right name.

Non Layer Supporting Program

This is where a lot of extra work will need to be put in. Follow the steps below;

1. For every layer needed in your model, make each part, such as left hand and right hand, of your accessory following the single layer guide. However don't combine these parts into a single layer.
2. Create a new file with the extension .layered.
3. Cut and paste the following, being sure that you change the name of each property. If you have more than two layers, add more properties depending on how many you have.

{
  "layers" : {
    "Hand_Right" :  "mods/modname/clothingitemrighthand.qb",
    "Hand_Left" :  "mods/modname/clothingitemlefthand.qb",
  }
}

With this done. You can now select this file, that is "mods/modname/clothing.layered", as the model for your accessory. [NOTE: This may not be working in release version of Staxel.]

Adding the Model to Staxel

Before starting this step, open up the Staxel launcher and make sure there is no game update available. If there is an update available, download it. This is to make sure you don't accidentally lose the files while you are working on them. If you ever do come to see "Begin Update", remove the files from the \mods\ before starting.

Once that is checked, then we can start creating the stuff needed to get the your tile into the game. Go to the \mods\ folder inside your Staxel installation and create a new folder with the name you want to call the mod. Once that is done, move the *.qb file that you created before in that folder that was created.

The next thing to do is to create a file with the extension *.accessory, 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.

{
  "code" : "mods.modname.modelname",
  "model" : "mods/modname/modelname.qb",
  "kind" : "Hair",
  "bodyType" : [ "staxel.bodyType.HumanoidMale", "staxel.bodyType.HumanoidFemale" ],
  "pricing": {
    "value": 250.0
  }
}

[Currently not working] If you have created a "*.layered" file, use this file in the model attribute instead of specifying a model

It's important to note that you can add a distinction between male and female versions. If your item does change between males and females (Such as Shirts) then you will need to add "altModels" attribute with the other model being specified for the other body type. (The male model for the male body type for example)

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 hair style to Staxel.

A small explanation of this *.accessory file

Feel free to skip this explanation if you "Just want to get the damn thing done!"

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

"model" : This is the path to the model that you have created. In our case you would put in something like "mods/modname/tilename.qb"

"kind" : This property tells the game, what the object actually is. No need to change this for Hair Styles.

"bodyType" : This property is a list of body types that the game will check for support of the accessory. Does not affect what can equip this accessory.

"pricing" : This property specifies on how much your accessory will cost when in the catalogue. Not needed for Hair Styles and Eyes.

Preparing the Accessory for Staxel's Palettes

What was not mentioned before is the system which allows your Accessory 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 Palettes#Creating a Palette for Player Models instead.

If you want to incorporate the Staxel palettes then you need to do a couple steps.

1. First open up the following palette into any photo editor with an eyedrop tool. \gamedata\content\staxel\palettes\blonde.png
2. Once that is open, open your Accessory in the Voxel editor of choice.
3. 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.
4. 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 *.accessory file that you made before.

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

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 Accessory Colours. The second line tells the game what palette to default to when choosing/displaying the Accessory.

Make sure to save the file and then run Content Builder again. And with that you should have a Accessory which has all the Staxel Palette colours with it.

Config Options

"code"

Valid options (String): A unique string which identifies what Accessory this is.

Default Value: No default value is specified. Always need to provide your own.

This option is required to uniquely identify any Accessory. This string must be unique to all other codes, but does not have any other requirements.

"kind"

Valid options (String): Hair, Eyes, Shirt, Trousers, Shoes, Accessory, Hat.

Default Value: No default value is specified. Always need to provide your own.

A string referring to the type of Accessory your object is. Mainly refers to what accessory slot the item is equipped in.

"altModels"

This option specifies that the game should choose a different model depending on the model type used. If an option is not listed here, it will use the one specified in "model".

This is not needed in a file, unless you want to have different models for males and females.

This is a List of Blobs which is specified as below.

"altModels": [
  {
    "bodyType": "staxel.bodyType.HumanoidFemale",
    "model": "staxel/characters/accessories/coats/FemaleLabCoat.qb"
  }
]

"bodyType"

Valid options (String): A string each pointing to a Body Type.

Default Value: An empty list.

This is the body type that will be checked against. If the body type is exactly what is specified here, then the accessory model will swap out for the one specified in #"model".

"model"

Valid options (String): Any valid string that contains the path to a model.

Default Value: No default value is specified. Always need to provide your own.

This is the model that will be used to replace the accessory's model if it the Body Type matches.

"bodyType"

Valid options (List of Strings): A list of strings each pointing to a Body Type.

Default Value: If not specified, will not check compatibility with any Body Type.

This is a list of Body Types that the game will check for compatibility. This does not limit the body types this clothing can go on. Currently there are two player Body Types, "staxel.bodyType.HumanoidMale", "staxel.bodyType.HumanoidFemale"

"categories"

Valid options (List of String): A list of valid strings.

Default Value: If not specified, will not have any user defined categories.

This is a list of strings which are used to identify what the tile actually is. These terms can all be searched for in the Catalogue/Creative Menu, but are also used in Totems and Achievements. Certain categories will appear under certain tabs in either menu. These include:

"block", "door", "floor"/"flooring", "flower", "furniture", "light", "plant", "tool", "window", "misc", "red", "orange", "yellow", "green", "blue", "purple", "pink", "white", "black" and "brown"

"charGenAvailable"

Valid options (Bool): True or False

Default Value: If not specified, will default to True.

Determines whether or not this item can be found in the Character Creator. This does not include Clothing.

"defaultPalette"

Valid options (String): Any valid string which point to Palette.

Default Value: "". If not specified, will default to the first available palette.

This is the palette that will be selected by default in the character manager.

"descriptionImage"

Valid options (String): A string containing the path to an image file.

Default Value: If not specified, will not show an image in the description.

This is an image that will show up in the description window.

"iconScale"

Valid options (Float): A positive decimal number.

Default Value: If not specified, will default to 1.

Changes how large the this item will appear when it is held in the hand/catalogue.

"inHandRotation"

Valid options (Vector 3 - Float): { "x": 0.0, "y": 0.0, "z": 0.0 }

Default Value: No default value is specified. Always need to provide your own.

This is the rotation of the item in the player's hand. This is used to make sure the item is facing the correct direction. Rotations are in Radians and not Degrees.

"model"

Valid options (String): Any valid string that contains the path to an model.

Default Value: No default value is specified. Always need to provide your own.

The model of the accessory. The layers in the model need to line up to the layers used by Player Models.

"hairReplacements"

This options specifies that this accessory will change the player's hairstyle when equipped. Useful when you add a hat that completely covers the hair, and it would look weird when hair flows through it.

This contains two values, a value specifying the default replacing model and a list of blobs which is specified as below.

"hairReplacements": {
  "default": "staxel.accessories.characters.accessories.hatHairs.HatHairShort",
  "specific": [
    {
      "type": "short",
      "code": "staxel.accessories.characters.accessories.hatHairs.HatHairShort"
    },
    {
      "type": "medium",
      "code": "staxel.accessories.characters.accessories.hatHairs.HatHairMedium"
    },
    {
      "type": "long",
      "code": "staxel.accessories.characters.accessories.hatHairs.HatHairLong"
    }
  ]
},

"code"

Valid options (String): Any valid string pointing to another Accessory.

Default Value: No default value is specified. Always need to provide your own.

A string specifying what hair style to use for the specified type.

"default"

Valid options (String): Any valid string pointing to another Accessory.

Default Value: No default value is specified. Should always provide your own. (It may work if left out)

A string that contains the default hairstyle to be used when equipping your accessory.

"type"

Valid options (String): Any valid string.

Default Value: No default value is specified. Always need to provide your own.

A string specifying what sub category of hair, see subcategory, to swap for the model in this blob.

"palettes"

Valid options (List of Strings): A list of strings each pointing to a separate Palette.

Default Value: If not specified, will not have any palettes and will rely on the model's colours.

This is a list of colour swaps for this model.

"paletteGroups"

Valid options (List of Strings): A list of strings each pointing to a separate Palette Group.

Default Value: If not specified, will not have any palettes and will rely on the model's colours.

This is a list of Palette groups which contain a number of colour swaps for this model.

"searchable"

Valid options (Bool): True or False

Default Value: If not specified, will default to True.

Determines whether or not this item can be found in the catalogue. This does not include Hair Styles and Eye models.

"stackSizeLimit"

Valid options (Integer): Any valid positive integer.

Default Value: If not specified, will generally default to 999 items per stack.

This is the number of tiles that you can hold in a single slot of your inventory, or in a Dock.

"starter"

Valid options (Bool): True or False

Default Value: If not specified, will default to False.

Determines whether or not this item can be found in the Character Creator. This does not include Hair Styles and Eye models.

"subcategory"

Valid options (String): Any valid string.

Default Value: If not specified, will not be a part of any subcategory.

A string containing what sub type the object will be. Used in a couple places, like "HairReplacements".