Villager Designs

Villagers in Staxel are fairly moddable, with many parts being able to be switched out, and new creations can add to the pool.

This page is about Villager Designs, these are found in .characterdesign files and contains information for;

• The species, gender and personality of the villager
• The Hair style, eye type and the model of the villager
• Which hand is the dominant hand

As a note, this file does not specify all of villagers looks, particularly the villagers clothes, but it does specify the majority of the physical traits for a villager.

This page will mainly focus on Version 3. This is the latest version of the design file. Staxel is made with keeping backwards compatibility in mind, which includes keeping saves at least partially workable between updates.

Creating a *.characterdesign file

Character design files are heavily dependent on a couple things; Species, Personalities and Accessories. As such, you can look at these pages to see how to create these individual things. You will learn where they belong later in the tutorial however.

Before you start this tutorial, be sure to head through Modding#Getting Started with Staxel Modding.

Adding the Villager Design via Asset Manager

Follow Modding#Using the AssetManager to Create Mods to open up the Asset Manager. With the Asset Manager open, head to View → Characters and Animals → Villager Assets. When the new window is open, head to Asset → Add → New Asset and the following window will show up.

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, then click on the drop down and select Character Design Asset. Then click save, give the item a code then click OK.

After the asset is created, it will have been automatically selected. With that it is now time to tell the game what you want to do with this Villager Design. The following set of steps highlight the important properties, however you can mess with any property.

1. Click on the dropdown arrow to the left of Design.
2. Click on the dropdown arrow to the left of Eyes.
3. Click on Eyes. And then click on the dropdown.
4. Click on the new Model property. And then click on the dropdown, Find the accessory you want for the eyes. You can make more accessories by following Accessory#Adding the Accessory to Staxel.
5. Click on Gender. And then click on the dropdown, and click the appropriate gender.
6. Click on Hair. And then click on the dropdown.
7. Click on the new Model property. And then click on the dropdown, Find the accessory you want for the hair. You can make more accessories by following Accessory#Adding the Accessory to Staxel.
8. Scroll down and Click on the last Model. And then click on the dropdown.
9. Click on the new Model property. And then click on the [...]. Now with the open file window open, head to the model you have made before. (Select the .layered file if you made that.)
10. Scroll down and Click on the Personality. And then click on the dropdown. Select the personality (Animation Set) you want for this character. You can make more accessories by following Personalities#Creating a *.personality file.
11. Scroll down and Click on the Species. And then click on the dropdown. Select the species you want for this character. You can make more accessories by following Species#Creating a *.species file.

With that, hit Crtl+S to save the file. And then go to File → All Assets → Build and Validate Assets. If this succeeds, then HURRAY! you have a new tile in the game. If it fails, try and read the error to see what you have done wrong. If you are confused then go to the #Modding channel on Discord and ask there.

Adding the Villager Design via Text Files

Follow Modding#Using a Text Editor to Create Mods in order to be properly set up for this step.

Create a text file and rename its extension to *.characterdesign. After creating this file, open it up in the text editor of your choice by right clicking the file and choosing open. You may want to force set the default program as well. Once this file is open copy the following template into the file.

{
  "code": "mods.modnamehere.villager.design.villagername",
  "design": {
    "_version": 3,
    "Species": "staxel.species.Elf",
    "Gender": "female",
    "Personality": "staxel.personality.feminine",
    "LeftHanded": false,
    "Model": {
      "model": "staxel/characters/species/elf/Elf_Female.qb",
      "palette": "staxel.palette.skin.oriental"
    },
    "Hair": {
      "model": "staxel.accessories.devavatars.razz.RazzHair",
      "palette": ""
    },
    "Eyes": {
      "model": "staxel.accessories.eyes.normal",
      "palette": "staxel.palette.pink"
    },
    "revision": 0
  }
}

Sadly there are no pictures for this, as there is nothing to show. However here are the explanations for this file above which contain things known as properties. These explanations are listed below.

• "code": A unique String that would be used to identify this object from others. For example this is like "staxel.item.crafting.BakingPowder" or "staxel.tile.grass". You will most commonly want to use you use the path to the Accessory Model but replace / with ., as this will ensure your design will have a different code to all other designs.
• "_version": This is a Integer that will tell the game what version of Villager Design you want to use. This was added in order to keep compatibility with old villagers on old worlds. At this point in time you do not want to change from 3.
• "Species": A String that is the code of the Species you want to use. This will provide the base look, specifically the base Body Type, of the character. The game currently offers 3 options for Humanoid villagers (i.e. "staxel.species.Human", "staxel.species.Elf" and "staxel.species.Invisible"), but you can also use Animal's and your own Species created by Species#Creating a *.species file.
• "Gender": A String which contains either "male" or "female". This chooses which of the two bodies that can be chosen from "Species".
• "Personality": A String that is the code of the Personality you want to use. This will provide the base animation set that the game will use, not to be confused with Villager Personalities which determines how a villager talks. The game currently only offers 2 options for Humanoid villagers (i.e. "staxel.personality.standard" and "staxel.personality.feminine"), but you can also use Animal's and your own Personality created by Personalities#Creating a *.species file.
• "LeftHanded": A Bool. Set to True to have NPC's have their dominant hand be left. False for right hand dominant.
• "revision": This is a Integer that will tell the game what revision of Villager Design this villager is. This enforces some checks between versions of Characters in order to avoid errors to old worlds. This is safe to be set to 0 and increased whenever the villager is changed.

Finally there is couple more properties. These properties are known as Blobs and are named the following; "Model", "Hair" and "Eyes". However they all follow the same format. This format is as follows;

"Model": {
  "model": "staxel/characters/species/elf/Elf_Female.qb",
  "palette": "staxel.palette.skin.oriental"
},

The explanation of these two properties are below.

• "model": This property changes depending on which Blob it is. There are two different cases;
  • For "Model", A String that is the path to the model you want to use. This will be the model that will be the body for the NPC. This starts at the /content/ directory and therefore will mostly start with mods/modname/.
  • For "Hair" or "Eyes", A String that is the code of the Accessory you want to use. This will be the Accessory that will be the Hair or Eyes of the NPC.
• "palette": A String that is the code of the Pallete you want to use to colour the model. This is how different skin and hair colours are done. You can leave this blank in order to get the default palette.

After you have done editing the file, head to gamedata/bin/ folder, and start up Staxel.ContentBuilder.exe. When this has started up, click Validate Resources and wait until the progress bar has done. And with that you should have a working item. If you are confused then go to the #Modding channel on Discord and ask there.

Config Options

"code"

Valid options (String): A unique string which design this object is.

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

A string containing the code of the design the blob will be referring to.

"design"

Unlike most other files, the majority of data is actually specified in this property rather than the overall file. This property will generally look like;

"design": {
  "_version": 3,
  "Species": "staxel.species.Elf",
  "Gender": "female",
  "Personality": "staxel.personality.feminine",
  "LeftHanded": false,
  "Model": {
    "model": "staxel/characters/species/elf/Elf_Female.qb",
    "palette": "staxel.palette.skin.fair"
   },
  "Hair": {
    "model": "staxel.accessories.hairstyles.female.long.curlyhairbands.CurlyYellowHairbands",
    "palette": "staxel.palette.blonde"
  },
  "Eyes": {
    "model": "staxel.accessories.eyes.kawaiiEyelashes",
    "palette": "staxel.palette.blue"
  },
  revision": 1
}

These properties are listed below.

"_version"

Valid options (Integer): An integer which corresponds to the version of the file. Currently Version 3 is the latest.

Default Value: If not specified, will default to 1. (Not recommended to skip. As it leads to an older version.)

This is the version number which specifies how the file should be interpreted. This is mainly to keep old worlds from crashing due to missing information. For example, version 1 had "Model"/"Hair"/"Eyes" be a singular string for model rather than the combined model and palette listed below. It's recommended to use the latest version when creating new files.

"LeftHanded"

Valid options (Bool): False or True.

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

This determines whether the villager uses tools in their right hand or their left. The default is the right hand.

"Gender"

Valid options (String): Either "Male" or "Female".

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

This is the gender of the villager. This is mainly used in order to apply the correct Body Type to the model specified.

"Model"/"Hair"/"Eyes"

All three of these properties contain two values which aim to specify what accessory/model is meant to be in this place. None of these options are normally changed during gameplay (As opposed to clothing which may be changed.) These properties look like;

"Eyes": {
  "model": "staxel.accessories.eyes.kawaiiEyelashes",
  "palette": "staxel.palette.blue"
},

The properties inside of this can actually be omitted without trouble but this property (Model/Hair/Eyes) must exist.

"model"

Valid options (String): Either the code of an Accessory file or the path to a model file.

Default Value: If not specified, will default to no model.

This is the model to use for this section. The Accessory Code is the method that should be used for Eyes and Hair but the path should be used for models. (As these models generally don't have files associated with them.)

"palette"

Valid options (String): The code of an Pallete file.

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

This is the colouring to use for this section.

"Personality"

Valid options (String): The code of an Personalty file.

Default Value: If not specified, will default to no personality.

This points to what animation personality will be used for this model.

"Species"

Valid options (String): The code of an Species file

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

This is the species of the villager. This is mainly used in order to apply the correct Body Type to the model specified.

"revision"

Valid options (Integer): The number determining what version the person is

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

This is used to differentiate different versions of the same character and is mainly responsible for making sure the client and server are running the same version of the character.