Creating Custom Cosmetic Resourcepack

Creating Custom Cosmetic Resourcepack

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.