Custom Races & Skins

The races configuration (races.yml) allows you to customize existing races or even create entirely new ones, while the skins configuration (skins.yml) determines how race will look if humanoid villagers are enabled. Races and skins are not hardcoded, meaning you can create COMPLETELY new races (or, if you prefer, factions), attributes such as health or model size, voice sounds, trading currency, and skins.

Example Race Configuration

races.yml

# Dwarves are the first race added. Why? Because dwarves rules!
dwarf:

  # Targeted entity type.
  target-entity-type: VILLAGER

  # It won't be checked if target-entity-type is not a villager.
  target-villager-type: SNOW

  # An item that members of the race will use for trading.
  normal-currency: GOLD_INGOT

  # An item to be used when normal currency is insufficient.
  special-currency: GOLD_BLOCK

  # A race description to be used by the AI when generating personal villager data and quests.
  race-description: "Short statured craftsmen known for their love of alcohol, beards and deep voices. With their naturally strong builds, they prefer to live in cold places, where they are often found. Excellent miners, blacksmiths and drinking companions."

  # Format: SOUND-MIN_PITCH-MAX_PITCH (pitch must be between 0.0 and 2.0)
  # https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
  sound:
    male:
      voice:
        - ENTITY_VILLAGER_AMBIENT-0.65-0.85
        - ENTITY_VILLAGER_NO-0.65-0.85
        - ENTITY_VILLAGER_TRADE-0.65-0.85
        - ENTITY_PILLAGER_AMBIENT-0.65-0.85
        - ENTITY_VINDICATOR_AMBIENT-0.65-0.85
      death: ENTITY_VILLAGER_DEATH-0.55-0.65
      hurt: ENTITY_VILLAGER_HURT-0.55-0.70
    female:
      voice:
        - ENTITY_WANDERING_TRADER_AMBIENT-1.9-2.0
        - ENTITY_WANDERING_TRADER_YES-1.9-2.0
        - ENTITY_VILLAGER_YES-1.9-2.0
        - ENTITY_WITCH_AMBIENT-1.8-2.0
      death: ENTITY_WITCH_DEATH-1.8-2.0
      hurt: ENTITY_WITCH_HURT-1.8-2.0

  # Entities have an inventory and we can specify the starting items they will have on spawn.
  # https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html
  spawn-items:
    - EMERALD-12-24
    - GOLD_INGOT-12-24
    - BREAD-4-8
    - APPLE-4-8

  # Standard attributes that allow you to make the entity a bit more original and realistic.
  # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
  basic-attributes:
    - MAX_HEALTH-30.0
    - SCALE-0.85

Explanation

As you can see, there are plenty of customization options. The abundance of comments eliminates the need for excessive explanations—just read them carefully, and you'll understand what everything does and why. Instead of boring explanations, let's create a custom race!

Creating a New Race

Warning! Ensure that replace-resources is disabled in config.yml, otherwise, upon the next server startup, all modified files will be overwritten with their default versions.

config.yml

core:
  # By default, the configs responsible for game values are overwritten each time the server starts with the defaults.
  # This is to make it easier for me to adjust the balance. But it can be switched off.
  replace-resources: false

To create a custom race, you need to understand that a race is a type of villager (e.g., PLAINS), which determines the villager's race and everything associated with it. This creates a convenient logic: in snowy biomes (SNOW), dwarves reside; in forests (TAIGA), elves dwell; in deserts (DESERT), orcs live, and so on. Keep this in mind first when creating a custom race: ask yourself, "Where will these creatures live?"

Next, as an example, I will show the Khajiit race (a race from The Elder Scrolls universe), its full description, and skin definitions.

Khajiits — Custom Race

races.yml

# An example of a custom race of khajiits who live in hot biomes.
khajiit:

  # Targeted entity type.
  target-entity-type: VILLAGER

  # It won't be checked if target-entity-type is not a villager.
  target-villager-type: DESERT

  # Khajiits loves shiny. Right?..
  normal-currency: GOLD_INGOT

  # An item to be used when normal currency is insufficient.
  special-currency: GOLD_BLOCK

  # A race description to be used by the AI when generating personal villager data and quests.
  race-description: "Khajiits — a race of humanoid cats, distinguished by their cunning and ferocity, sharp claws on their paws, fur covering their entire body, silent steps, and excellent night vision. Many dislike Khajiits for their temperament and criminal activities: thieves, highway bandits, smugglers, and hired assassins are the main occupations of these oversized felines. A common saying goes, «pet a Khajiit — kiss your money goodbye». If, during a nighttime stroll through the city, you stumble upon a gang of Khajiits in an alley, rely on your luck and the sharpness of your blade."

  # Format: SOUND-MIN_PITCH-MAX_PITCH (pitch must be between 0.0 and 2.0)
  # https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
  sound:
    male:
      voice:
        - ENTITY_CAT_STRAY_AMBIENT-0.65-0.85
        - ENTITY_OCELOT_AMBIENT-0.65-0.95
      death: ENTITY_CAT_DEATH-0.95-1.5
      hurt: ENTITY_OCELOT_HURT-0.85-0.95
    female:
      voice:
        - ENTITY_CAT_BEG_FOR_FOOD-0.95-1.15
        - ENTITY_OCELOT_AMBIENT-0.65-0.95
      death: ENTITY_CAT_DEATH-1.15-1.8
      hurt: ENTITY_CAT_DEATH-0.95-1.15

  # Entities have an inventory and we can specify the starting items they will have on spawn.
  # https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html
  spawn-items:
    - GOLD_INGOT-12-24
    - SALMON-12-24 # Don't forget about food for our oversized kittens!

  # Standard attributes that allow you to make the entity a bit more original and realistic.
  # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
  basic-attributes:
    - MAX_HEALTH-17.5
    - SCALE-0.925

Custom Skins for Custom Race

Okay, we’ve created a new race. Make sure you’ve overwritten the race that previously replaced desert villagers (in our case, orcs). Now, we just need to add the skins. The format of the skins.yml file is shown below.

skins.yml

'ID': # Skin ID. Ensure no conflicts: use random large numbers if you want. It doesn’t matter (I’ll rework the format in the future).
  race: "race" # In our case, khajiit, as that’s what we named our race!
  gender: MALE # MALE/FEMALE
  texture: "texture" # More on this below.
  signature: "signature"

To proceed, we need to:

1. Find a skin that authentically matches our race. For searching existing skins, I recommend sites like minecraftskins.net, planetminecraft.com, namemc.com, novaskin.me. These sites offer convenient search tools, skin downloads, and a variety of works from talented artists. If you need something unique, you can hire artists or generate a custom skin using craftbench.ai.

2. Download the skin you like and upload it to mineskin.org to obtain the texture and signature. If you purchase a MineSkin subscription, you’ll also gain the ability to add capes!

   

   We are interested only in value and signature.
3. Copy and paste the required values and save the file.

   skins.yml

   # Khajiits
   '30':
     race: "khajiit"
     gender: MALE
     texture: "ewogICJ0aW1lc3RhbXAiIDogMTc0OTM1NjYyNzc0MCwKICAicHJvZmlsZUlkIiA6ICI0ZWE3NGM1ZGUyZGI0OGY2YjViOTk1YTVhNTYzMmU0NCIsCiAgInByb2ZpbGVOYW1lIiA6ICJNclNjYXJ5U3BhY2VDYXQiLAogICJzaWduYXR1cmVSZXF1aXJlZCIgOiB0cnVlLAogICJ0ZXh0dXJlcyIgOiB7CiAgICAiU0tJTiIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYjBkOWZmOGE3MWM4NGJiOTJhYjA2NzM1ZTczZTg0ZDZlOWZlMGMzNmNmYjFjNDJkN2Y3MzM2Yzg5NTdjYjFkNSIKICAgIH0sCiAgICAiQ0FQRSIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNTY5YjdmMmExZDAwZDI2ZjMwZWZlM2Y5YWI5YWM4MTdiMWU2ZDM1ZjRmM2NmYjAzMjRlZjJkMzI4MjIzZDM1MCIKICAgIH0KICB9Cn0="
     signature: "qvZrcryKBym0HNVYnWAhV2nY76wyv9QrizsOZV2WydMRJddqlauDW54g65VvYnPWNajflybQfF6h5jSY6cdhkEqQhDTgQX0v18gCAxOMfA4rGAxZ/n2vjBWBxzyr36ihzja2zA193cuWEKmwG50BoQwmT9l+PUcYzAG7BE9t/Of8EEUt/eQr5+8COdHaIFhM6btNKpV2D01hr1z0lodn9dXzBofGPSg0MZM6zYqd9kHOegpME3a9DLGFVvFxQAxpOYge8P/0Nk7D5SfSMzm1vU07XaqBzixzRNSZPTYE1bV0kGaQsuBB85ts0+pbCrltzqihX0Q1JeJ1g+OEugOtIlS5HNWpcya+AhePC4ni+LIMMHPzWTIBAtajQkY594TzRE1VSRSP7tZjeiRIicYwGjmxpXi8FkPGGN+H5RtrLAF1dO7GNpX9KsEbayYoyGSvbUIlcJw40znzb+rLq/s+VDi6+tnwAZKsylGPDla549/6Vy/K8Z6hI/jDMC4TSPsgfNWi7j8YLiZt+6+vaqHR3ESmQ+2maSajqJF7CvfLoziTHoSCCUQcdOTBGi97fc389YILEneFLsne/6ZDRj8vlCnhqMNAKwtKp6u8p+/JsyQsKvDEDu2pme7L/JXCqjOxdB86yT8O+8FolhJm1HZ0VZyw30Jk6RImWLtjOp1qNmY="
   '31':
     race: "khajiit"
     gender: FEMALE
     texture: "ewogICJ0aW1lc3RhbXAiIDogMTc0OTM1NzA2MDYwMiwKICAicHJvZmlsZUlkIiA6ICJlMTNkYWY5NTc3YzE0NTUyODBjNzNmYWQ4NThmMmU5MSIsCiAgInByb2ZpbGVOYW1lIiA6ICJUMGJpaWkiLAogICJzaWduYXR1cmVSZXF1aXJlZCIgOiB0cnVlLAogICJ0ZXh0dXJlcyIgOiB7CiAgICAiU0tJTiIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvY2NmN2NjMGZhMzY0ZmJlOTg5ZDg5MTVkYmEyODA0ZDIwMTA5YjEzMmE5ZmQ1NmZlMmViMWI0ZjlhZGFhZjI0NyIKICAgIH0sCiAgICAiQ0FQRSIgOiB7CiAgICAgICJ1cmwiIDogImh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNTY5YjdmMmExZDAwZDI2ZjMwZWZlM2Y5YWI5YWM4MTdiMWU2ZDM1ZjRmM2NmYjAzMjRlZjJkMzI4MjIzZDM1MCIKICAgIH0KICB9Cn0="
     signature: "JzEEpMFRLNjSfJAkc5Uv4SpxFR3ZS74j4gxbq95d/X7ZEJ0DmCZFSxmgyTyPITXZ01foOstHh2z7VeQTwhusBf6lM1hgcZHiwBdFIezEnzYlxL0fZN7UsYmVI9ESJey3URCEjzDg3SoeBVBmBBw0wwKXyQ8yl/Wb2nFyQmbgOyWA5Yqdok3o9nDhu3KNpUDIj1owvcY4APidDhkJnwgCdLtooQC1SfiQpWfBBlbFsfSNXQVDwPwfNkU3VNgMuqBqtatMHvM3tQghEWh8z/X1JJIwDkvqPH2Lpi7ieq0fdYRnDXfpedNGoRzprEbStpwZYnF7gEUGo58pwufrOGdp2YQ0danRDQ3x9x4GCzwsr3VDgAoM5brTvgnP8fXaQJ9Nfva2Ks7u9gJeLyVPIA8auhQ2VJ+6BWE4yD6+/1iJYWvQh52GucokkdukDBS8Cpp+Wfji3c9ME5say4KEr29DYNRMAej4h/1kDtNcZgxCQjm+ShD5FrRoBX5cJJkQcPNJ5is/tfWFwk4TRytohl76dPMteXAoiF/P69UQYV52jYBNPzOK16ylvAKc2fnLvlbd7dkQDPHoX/cfBjtod1fuxIwo4DuHukkEhQssOr2X3CZclgUGUMKZ6IghLqFAeHIeHXvFU6VmML7eRQKzgz70LLQYZYwNJoI/COa1nK8AtUc="

The Result

Meow!