Skip to content

v2 | HatCosmetics

Jump to bottom
Marcel edited this page Jul 12, 2025 · 10 revisions

If you are looking for HatCosmetics V3 wiki, you can access it here.

Permissions

To find out how to set up permissions, head over to the wiki page.

Adding Custom Cosmetics

Note

This guide is written so that even those who've never edited a resourcepack before can follow along.

For this guide, you'll need:

  • A model editor, Blockbench, is the recommended tool.
  • A text editor capable of editing .json files.

Understanding Resourcepacks

Cosmetics need both a .json model file and a .png texture file. In addition to that, you'll need to edit a model replacement file. All of these are located within a resourcepack.

Modelling Custom Cosmetics

To model and texture your own cosmetics, you will need a model editor. The recommended option is Blockbench. Tools such as Blender will work and will be significantly harder.

The example resourcepack is the base for this tutorial. To make use of this, download the compressed archive (.zip), or alternatively view it here. If you already use a server resourcepack, hats can be added to it.

The folowing structure is used for a resourcepack:

  • pack.mcmeta contains the name and metadata of your resourcepack.
  • pack.png is the image visible in the client side resourcepack settings menu.
  • assets/minecraft/ contains the actual pack data. This is where you will add all of your changes.

Atlases

Note

Atlases are only needed after 1.19.3. If you're using a version of Minecraft previous to that, feel free to delete this folder.

The example resourcepack only uses one directory (textures/hatcosmetics/). If you add more subdirectories to textures/, you must also edit the atlases/blocks.json file to include these.

Below is an example of blocks.json with additional directories:

{
    "sources": [
        {
            "type": "directory",
            "source": "hatcosmetics",
            "prefix": "hatcosmetics/"
        },
        {
            "type": "directory",
            "source": "example",
            "prefix": "example/"
        }
    ]
}

Models and Textures

A texture is a 2D image file that gets applied to the surface of a 3D object. A model is the definition of the 3D geometric structure, serving as the foundation onto which textures are applied. These two are closely tied together, and require each other to function.

In the example resourcepack, models/hatcosmetics/ contains two example cosmetics:

  • disguise.json
  • staff_hat.json

Warning

Do not add special characters, upper case letters or spaces to your files/directories' names. This will cause malformation errors from Minecraft's perspective, and force unload your resourcepack.

You may need to edit your model files depending on how you structured and exported your models.

Below are the first few lines of staff_hat.json:

{
	"credit": "Made by Tonus_ with Blockbench",
	"texture_size": [64, 64],
	"textures": {
		"0": "hatcosmetics/staff_hat",
		"particle": "hatcosmetics/staff_hat"
	}

Note that on the 5th and 6th lines, the texture names start with hatcosmetics/. This is because the texture files are located in hatcosmetics/ inside of textures/. staff_hat is the name of the texture file within that folder, without the file extension .png.

It is possible to reuse textures for multiple models, as well as use multiple textures for a model. For simplicity, when starting off, it is recommended to stick to one texture per model.

When exporting your textures, ensure these are exported in .png format. As for models, export these as a Minecraft Model JSON Format (Schema MC Wiki) Place these in models/hatcosmetics/ and textures/hatcosmetics respectively.

Note

It is possible to give the texture and the model file different names. However, doing so might lead to confusion.

Item Model (feather.json)

The models/item/ directory contains item files.

Inside the example pack, you will find feather.json. This matches the item the plugin is replacing for hat models in the config. The overrides in the item definition registers the models for cosmetics. If you have already make use of a custom server resourcepack that already contains a custom feather model, you need to copy over the overrides to bind cosmetics to the feather item.

If you wish to change the base item in the config, rename the file to the item of choice, and change the textures/layer0 parameter to the item. Note that this is the Material, not the in-game display name.

Important

The following explains the main edits needed within the resource pack. Follow these steps as closely as possible if this is your first attempt.

To add custom model hats, edit the feather.json.

"overrides": [
	{"predicate": {"custom_model_data":1000101}, "model": "hatcosmetics/staff_hat"},
	{"predicate": {"custom_model_data":1000102}, "model": "hatcosmetics/disguise"}
]

Each cosmetic will need it's own separate predicate override. Each predicate must have a unique custom_model_data across all resourcepacks (including the Minecraft vanilla one), as well as the model extension path from the textures/ directory.

Note

While the example pack starts at 1000101 and follows a sequential order, these are not requirements.

Adding Resourcepack to Server

There are a few ways to make your resourcepack accessible to others:

SimpleResourcepack Plugin (RECOMMENDED)

SimpleResourcepack is a plugin that allows self-hosting resourcepack(s) on the same container/machine as your server. This requires an additional port!

  1. Compress the resourcepack to a .zip archive.
  2. Configure and add resourcepack according to the SimpleResourcepack wiki.

Note

HatCosmetics is looking to improve in v3 by optinally integrating with SRP and automatically updating the resourcepack for you. Keep an eye out for future updates and announcements!

Cloud Service Provider

One easy way to share your resourcepack is via cloud service providers.

Some examples of cloud service providers include:

  • Google Drive
  • OneDrive
  • GitHub / GitHub LFS

Any publicly accessible provider will work granted that the file can be publicly accessed.

Note

It is not possible, nor ever will be to encrypt or obfuscate a resourcepack.
Each client downloads the resourcepack locally, meaning they will have access to it regardless.

In order to set this up:

  1. Compress the resourcepack to a .zip archive.
  2. Upload the .zip archive to your provider.
  3. Copy the raw URL to directly download your file.
  4. Navigate to the server.properties configuration of your Minecraft server, and set the resource-pack= value to the URL.

Manual Distribution

It may be possible that you do not want your resourcepack public, such as for small friend servers. In such cases, you can manually give the resourcepacks to the players, and this will also work.

Registering Cosmetics (config.yml)

Getting Started

Important

Ensure you have started the server at least once, and have a config.yml file.

Hat Properties

Property Optional? Type Description
item ✅ Material Override for default item used as base item.
data ✅ Integer Model Data number defined in resourcepack.
name String Name displayed on the item.
description ✅ List of String Lines of text displayed underneath item.

Example Hat Configuration (Default)

The default config.yml file should look something like:

# HatCosmetics config version: 4
# For both my sake and yours, please DO NOT change the config version!

# Refer to Spigot-API Materials for list of items: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
# Item used for all hats:
item: FEATHER
# Item used to border the hats in the GUI:
border: LIGHT_BLUE_STAINED_GLASS_PANE

# The number of hat rows in the GUI (must be between 1 and 4, or -1 for auto)
# This is only for the actual hats and not the two rows for the border and close menu item
gui_rows: 1
hide_hats: false # If set to true, players will only see hats they have access to in the GUI and equip command

hats:
  # This is where you add your hats
  staffHat:             # The name used for /hats equip and the hat's permission
    #item: DIAMOND_HOE  # (OPTIONAL) Only use if your hat uses a different item from the rest
    data: 1000101       # The custom model data defined in your resourcepack for the item
    name: "&fStaff Hat" # The name displayed on the item
    #description:       # (OPTIONAL) Adds list of text underneath the "Hat Cosmetic" line
    #  - ""
    #  - "&bShow who's boss!"

Note

The definition order of hats is the order of display in the in-game menu.

Adding Vanilla Items

For vanilla blocks/items, you'll need an item line. You can add anything as a hat, all you need is the Spigot Material.

If you have tooltips enabled (F3 + H), the ID will be shown in gray when you hover over the item on your inventory. A Material is equivalent to the ID with the minecraft prefix removed.

While normal square blocks are just placed on the player's head, some blocks will have special position and will sit differently. Below is an example using Big Dripleaf:

dripleaf:
  item: BIG_DRIPLEAF
  name: "Dripleaf"

Adding Custom Models

Warning

If you don't have a resourcepack properly set up, this will not work.

For custom models, you'll need a data line. The data line should be set to the model data found in the resourcepack model .json. On the example resourcepack feather.json, this would be the custom_model_data.

customHat:
  data: 1000101
  name: "Custom Hat"

Caution

Ensure that this data value is unique across ALL of your resourcepacks, including minecraft default.
Values over 1000000 are generally considered unique.

Text Formatting

The hat's name and description can have custom text formats. To view formatting options, see the Minecraft wiki.

Note

The example config.yml uses &f instead of §f.
Uppercase letters and both formats are accepted.

Did not find what you are looking for?

Feel free to create an issue or ask for help in Discord.

Clone this wiki locally