# Welcome

* [Patreon](http://patreon.com/lonedev)
* [YouTube](http://youtube.com/lonedev)
* [SpigotMC](https://www.spigotmc.org/members/lonedev.88296/#resources)
* [Website](http://devs.beer)
* [Steam developer page](https://store.steampowered.com/developer/LoneDev/)
* [Discord](https://discord.gg/4dfnpUK)

## Thanks to some awesome friends

### Cha\_Shao

Helped me a lot with the graphics assets of the plugin and beta testing.

{% embed url="<https://github.com/Cha-Shao>" %}

### The\_Gust

Helped with beta testing

{% embed url="<https://github.com/The-Gust>" %}

{% embed url="<https://www.spigotmc.org/members/the_gust.1117674/>" %}


# First install

## Installing the plugin

### Step 1

* install [LoneLibs](https://www.spigotmc.org/resources/lonelibs.75974/)
* install [ProtocolLib](https://ci.dmulloy2.net/job/ProtocolLib/lastSuccessfulBuild/)

{% hint style="warning" %}
This plugin requires some mid-level knowledge on how resourcepacks works.\
Please don't ask for support for basic questions about resourcepacks, ask to the community about this kind of questions.
{% endhint %}

### Step 2

You have to setup the wardrobe location, preview location, enter/exit location and various settings, please read here:

{% content-ref url="/pages/EqPXySOiBHsUFEJeGGYN" %}
[Customization](/wardrobe/customization)
{% endcontent-ref %}

### Step 3

{% content-ref url="/pages/2OJs3rPo6QkTye5ey5p0" %}
[Install base resourcepack](/first-install/install-base-resourcepack)
{% endcontent-ref %}


# Install base resourcepack

## If you don't have a resourcepack

{% content-ref url="/pages/pqVcRwQlnfEu1XyRzPQO" %}
[If you don't have a resourcepack](/first-install/install-base-resourcepack/if-you-dont-have-a-resourcepack)
{% endcontent-ref %}

## If you already have a resourcepack and you use ItemsAdder

{% content-ref url="/pages/yLaDSYMhmDgDDLFlMRk0" %}
[ItemsAdder](/first-install/install-base-resourcepack/itemsadder)
{% endcontent-ref %}

## If you already have a resourcepack and you don't use ItemsAdder

{% content-ref url="/pages/hzNBOeK9qkP3Z3YhfR5u" %}
[Any plugin and resourcepack](/first-install/install-base-resourcepack/any-plugin-and-resourcepack)
{% endcontent-ref %}


# If you don't have a resourcepack

## Installing the resource pack if you <mark style="color:orange;">don't</mark> have a resourcepack

### Step 1

Open the zip file which can be found here: `plugins/CosmeticsCore/default_assets.zip` .\
Extract the `Resourcepack` folder from the zip file to any folder of your PC.

### Step 2

Compress the `Resourcepack` folder CONTENTS (<mark style="color:red;">do not compress the folder itself</mark>).\
Select all the files and compress them.

<figure><img src="/files/36v5k3YXKr7aREsmMAfK" alt=""><figcaption></figcaption></figure>

### Step 3

Now decide a way to host your resourcepack, you usually would use **Dropbox** and `server.properties`. \
Do some research online on how to host resourcepacks.\
For example you can use one of these free websites:

* <https://resourcepack.host/>
* <https://mc-packs.net/>

## Installing the default cosmetics configuration

Open the zip file which can be found here: `plugins/CosmeticsCore/default_assets.zip` .

Copy the content of `plugins/` into your `plugins/` server folder.

If you have ItemsAdder regenerate your pack using  `/iazip` .

If you have ModelEngine regenerate the ModelEngine pack using  `/meg reload` and make sure to merge the new pack with yours.

Reload the plugin using `/cosmeticsconfig cosmetics reload` .


# ItemsAdder

## Installing the resourcepack <mark style="color:orange;">if you use ItemsAdder</mark>

{% hint style="warning" %}
Requires ItemsAdder v3.3 or greater
{% endhint %}

### Step 1

Open the zip file which can be found here: `plugins/CosmeticsCore/default_assets.zip` .

Extract it to a new folder, on your desktop for example.\
Note: ignore the `resourcepack` folder, you don't need it.

If you don't need the default cosmetics and you only need the UI you have to delete these folders and files:

* `plugins/ItemsAdder/contents/resourcepack/assets/cosmetics/`
* `plugins/ItemsAdder/contents/configs/cosmetics/`
* `plugins/ModelEngine/`
* `plugins/CosmeticsCore/`

### Step 2

Copy the previous `plugins` folder into your server `plugins` folder and replace files if asked.

### Step 3 (if you have ModelEngine)

If you have ModelEngine you can get the example balloon item.

Run `/meg reload`.

Open `plugins/ModelEngine/resource pack` folder and copy the `assets` folder.

Create a new folder and paste the assets folder inside of it: `plugins/ItemsAdder/contents/meg/resourcepack/`

### Step 4

Regenerate your ItemsAdder resourcepack using `/iazip` and follow the ItemsAdder hosting tutorial if needed.

### Step 5

Run `/cosmeticsconfig cosmetics reload`

### Done

<figure><img src="/files/Y1yOYJtbxwM5vRssYuIY" alt=""><figcaption></figcaption></figure>


# Any plugin and resourcepack

## Installing the resourcepack <mark style="color:orange;">if you already have a custom resourcepack</mark>

If you already have a custom resourcepack on your server you must merge the **CosmeticsCore** assets and (optional) default cosmetics.

### Step 1

Open the zip file which can be found here: `plugins/CosmeticsCore/default_assets.zip` .

Extract it to a new folder, on your desktop for example.

Delete this folder: `plugins/ItemsAdder/`

Delete this folder if you don't have **ModelEngine** plugin: `plugins/ModelEngine/`

If you don't need the default cosmetics and you only need the UI you have to delete these folders and files:

* `resourcepack/assets/cosmetics/`
* `plugins/CosmeticsCore/`

Open the `resourcepack` folder.

Copy `assets/z_cosmetics` and `assets/cosmetics` folder into your resourcepack.&#x20;

<figure><img src="/files/Gi7VcJS34k3vCjRxZLkG" alt=""><figcaption></figcaption></figure>

### Step 2

Open the file `assets/minecraft/models/item/fermented_spider_eye.json` with your favorite editor (example: **VSCode**) and don't close it (the file is inside the zip).

<figure><img src="/files/tGYr2sjrriwRuqwHTPHE" alt=""><figcaption></figcaption></figure>

### Step 3

Open the same previous file path in **YOUR** resourcepack (`fermented_spider_eye.json`).

Note: if you don't have this file in your resourcepack skip this step and simply copy and paste the `fermented_spider_eye.json` file inside your resoucepack into this path `assets/minecraft/models/item/fermented_spider_eye.json` .<br>

Use this tool to merge the **CosmeticsCore** file and your file:

{% embed url="<https://itemsadder.github.io/jsonmerger/>" %}

{% hint style="info" %}
`Json 1` is your json file, `Json 2` is the `CosmeticsCore` json file.

The result json is the one you will have to replace in your pack.
{% endhint %}

Now copy the result json and paste it into your old json file.

### Step 4

Follow the same previous steps for `potion.json`.


# Terms of service

{% hint style="danger" %}

### Before Buying

* ⛔ **This plugin requires users to download a resource pack (automatically sent on join)**. Ensure your players understand and accept this requirement.
* ⛔ **You must have knowledge about creating and managing Minecraft resource packs.** If you are new to resource packs, this plugin might not be suitable for you.
* ⛔ **Compatibility with other plugins or resource packs is not guaranteed.** It's impossible to test compatibility with every existing plugin. If conflicts arise, refunds will not be issued; instead, report issues clearly, and support will attempt to find a solution.
* ⛔ **Not compatible with some resource-pack-based plugins.** You should be prepared to merge resource packs manually.
  {% endhint %}

### Refund Policy

* **No refunds¹.** Refunds might be considered only under exceptional circumstances.
* Before initiating disputes via payment platforms (PayPal, Stripe, etc.), **contact the seller directly through the forum or email**.

¹Except as required by applicable state law.

### Resource Pack

* The plugin requires players to download a resource pack (automatically sent on join).
* It's not possible to use custom assets without resource packs; this is a Minecraft limitation, not a limitation of CosmeticsCore.

### Server Software

* This plugin officially supports **Spigot and Paper** servers. Compatibility with other forks is not guaranteed.
* Using other server software indicates acknowledgment that CosmeticsCore may not work as intended.

### Plugin Ownership

* ❌ **DO NOT DECOMPILE, RESELL, CRACK, OR REDISTRIBUTE THE PLUGIN.**
* You may use CosmeticsCore **only on servers you own** (including BungeeCord networks).
* It is your responsibility to prevent plugin leaks by keeping your files secure.
* Transfers of account or license ownership require a valid explanation and must be requested through Discord support.

### Bugs, Issues & Support

* ❗ **Do not leave negative reviews to gain attention.** It won't expedite support and might result in delayed assistance.
* Clearly report bugs on **GitHub**.
* Always consult the documentation and tutorials available on the **Wiki** before seeking help.
* For additional support, use the official **Discord** channel, making sure to provide detailed information.

### Updates

Once your purchase has been approved, you will be able to download this resource.

You are only guaranteed to be able to download this resource, as is, once. No additional downloads or updates are guaranteed.

### 🆘 Support Policy

* **No support for unverified accounts.** Verification is mandatory for support.
* **No tolerance for support abuse.** Spamming or repeatedly tagging support staff will result in ignoring your requests.
* **Detailed information required for support.** Requests lacking sufficient detail will not receive support.

### 🖌️ Addon Creation Policy

* You may sell custom resource packs, textures, configurations, or presets compatible with CosmeticsCore.
* **DO NOT INCLUDE DEFAULT ASSETS PROVIDED BY COSMETICSCORE** (textures, models, etc.) in your addons.
* A donation is appreciated if you profit significantly from your creations.

#### Creating Unique Addons

* Your addons **must not include default items, models, or textures from CosmeticsCore**.
* Redistribution of original CosmeticsCore assets is prohibited.

#### Copying Other Addons

* Avoid creating addons with substantial similarity to existing community creations. Doing so can result in the removal of your addon.
* Always seek permission from original creators if you intend to use elements of their work.


# Frequently asked questions

## Successfully introduce cosmetics in your server

{% hint style="info" %}

1. You must not make them easy to obtain. Make them a rare perk for donors or special events prizes (example: seasonal quests, boss battle prizes, staff members exclusive, donors exclusive)
2. Always make sure to publish a new cosmetic when you are 100% sure you want to keep it forever in your server. People don't like to buy cosmetics and see them removed after some time.
3. Make unique cosmetics, don't make useless variations of the same cosmetic design.
   {% endhint %}

## Offhand cosmetics (left hand)

Why aren't offhand cosmetics available in this plugin?

The reason is that offhand is a slot heavily used in the Minecraft gameplay to hold important items, for example shield, totems and other items.\
Using the offhand to place cosmetics would mean that the user won't really know which is the original item under the cosmetic, this would cause extreme confusion between players.

Imagine a player getting shot with a bow by another player who is apparently holding a cosmetic flower. In reality they are holding a bow.

Imagine a player during PVP, they won't know if they still have their shield or not in offhand.

Imagine a player which can't know if they still have their totem in offhand.

You may think: "you just need to open inventory and check".\
Imagine how annoying would be to have to open the inventory each 5 seconds in order to check durability of the shield in offhand.

## Multiple hats cosmetics

You cannot have more than 1 hat cosmetics equipped at the same time.

The hat cosmetic uses the helmet slot of your player, you cannot have more than 1 item at the same time in this slot, it's a limitation of the game.

There is no way to bypass this limitation.


# Translations

You can translate the plugin by creating a new file in the `lang` folder and set it in the `config.yml` file.

## Tiny font

You can use this generator to create small texts.

{% embed url="<https://lingojam.com/MinecraftSmallFont>" %}

<figure><img src="/files/gNX4k67NiumL0mAxoqdJ" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Do not use UPPERCASE characters in this converter or you will get a glitched text.
{% endhint %}

## JSON texts

{% hint style="danger" %}
For expert users, do not ask for support in order to use this feature.
{% endhint %}

This plugin supports JSON texts in lore, display name and translations of the plugin.\
Use this generator to generate the JSON texts.&#x20;

{% embed url="<https://minecraft.tools/en/json_text.php>" %}

### Example use case

You can set a custom font for a particular text:

```json
{"text":"Hello!","font":"my_custom_font"}
```

```json
{"text":"Lorem Ipsum!","font":"alt"}
```

&#x20;


# Files editor

## Blockbench extension

CosmeticsCore has a beta extension for Blockbench.

### Features

* preview body cosmetics in the editor
* create and preview self models for body cosmetics in the editor
* automatically fix size of the self models to allow further moving on the Y axis

### How to install

Get the latest `cceditor.js`  **URL** from the **Github** repository:

{% embed url="<https://github.com/LoneDev6/cosmeticscore-editor/releases>" %}

Open the plugins menu and paste the URL.

<figure><img src="/files/DBfCMqHbvWKS9xcyFDNJ" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/S5pdHdXJP5rOtSU4uP6r" alt=""><figcaption></figcaption></figure>

### How to open a cosmetic

Open your **.json** cosmetic file with Blockbench like you'd usually do.

### Usage tutorial - GLOBAL model

{% embed url="<https://youtu.be/i9H0VBKmvgA>" %}

### Usage tutorial - SELF model

{% embed url="<https://youtu.be/A4xYaW_9Zzg>" %}


# Commands

### Open the wardrobe

`/wardrobe`

Permission: `cosmeticscore.user.command.wardrobe`

### Open the cosmetics menu anywhere

`/cosmetics`

Permission: `cosmeticscore.user.command.cosmetics`

### Reload config.yml

`/cosmeticsconfig config reload`

Permission: `cosmeticscore.admin.command.cosmeticsconfig`

### Reload cosmetics

`/cosmeticsconfig cosmetics reload`

Permission: `cosmeticscore.admin.command.cosmeticsconfig`

### Force wear cosmetic

`/cosmetics <player> add <name> [silent|not-silent]`

Permission: `cosmeticscore.admin.command.cosmetics`

### Force un-wear cosmetic

`/cosmetics <player> remove <name> [silent|not-silent]`

Permission: `cosmeticscore.admin.command.cosmetics`

### Force un-wear all cosmetics

`/cosmetics <player> remove-all [category] [silent|not-silent]`

Permission: `cosmeticscore.admin.command.cosmetics`


# Permissions

## Commands permissions

{% content-ref url="/pages/wfZMOZZtk4kzzRlqO7Ki" %}
[Commands](/commands)
{% endcontent-ref %}

## Enter wardrobe area permission

Permission: `cosmeticscore.user.wardrobe.enterarea`

## Cosmetics wear permission

Permission: `cosmeticscore.user.cosmetics.wear.<name>`

Example: `cosmeticscore.user.cosmetics.wear.red_hat`

## Cosmetics see in wardrobe GUI permission

Permission: `cosmeticscore.user.cosmetics.seeingui.<name>`

Example: `cosmeticscore.user.cosmetics.seeingui.red_hat`


# Examples

### Allow players to open the wardrobe

`cosmeticscore.user.command.wardrobe`

### Allow every cosmetic to be visible in the wardrobe GUI

`cosmeticscore.user.cosmetics.seeingui.*`

### Allow every cosmetic to be worn by players

`cosmeticscore.user.cosmetics.wear.*`


# Adding content


# Properties

## `tooltip_style`

Use the new Minecraft 1.21.2+ feature to customize tooltip.

Example (download the resourcepack [here](https://www.planetminecraft.com/texture-pack/custom-tooltip-textures/))

<figure><img src="/files/86FOr3BMwrirbKIDUKdj" alt=""><figcaption></figcaption></figure>

```yaml
cosmetics:
  balloon_diamond_block:
    enabled: true
    display_name: "Diamond Block"
    tooltip_style: rainbow
    type: BALLOON
    model:
      gui: DIAMOND_BLOCK
      normal: DIAMOND_BLOCK
```


# Creating a model

To create a model you can use BlockBench.

{% hint style="warning" %}
This requires knowledge on how to create resourcepacks and how to manage CustomModelData.
{% endhint %}

### Step 1

<figure><img src="/files/fxhqb8gXz62wA1nxfk73" alt=""><figcaption></figcaption></figure>

### Step 2

Save the model file into your resourcepack

<figure><img src="/files/dwSaIRITdGueEGe6LtUm" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/j2dlzIoWfSjEtL9WYLJp" alt=""><figcaption></figcaption></figure>

### Step 3

{% hint style="warning" %}
This requires knowledge on how to create resourcepacks and how to manage CustomModelData.
{% endhint %}

Create the entry inside the `potion.json` file and decide a CustomModelData to be used later in the CosmeticsCore configurations.

```json
{
  "parent": "item/generated",
  "textures": {
    "layer0": "item/potion_overlay",
    "layer1": "item/potion"
  },
  "overrides": [
    ......
    ......
    {
      "predicate": { "custom_model_data": 600001 },
      "model": "cosmetics:hat/chef_hat"
    },
    ......
    ......
```

<figure><img src="/files/ny9Md5IY3vhxJxiH2zVi" alt=""><figcaption></figcaption></figure>


# Ballons (simple)

## Creating a balloon

### Step 1

Create a model following the tutorial

{% content-ref url="/pages/hboe6bWli2JL1FxJOkMK" %}
[Creating a model](/adding-content/creating-a-model)
{% endcontent-ref %}

### Step 2

Create the cosmetic configuration

```yaml
  simple_diamond_block_balloon:
    enabled: true
    display_name: "Simple Diamond Block Balloon"
    type: BALLOON
    model:
      gui: DIAMOND_BLOCK
      normal: DIAMOND_BLOCK
```

### Step 3

You're done

<figure><img src="/files/Qj3CXVDZ3p3lgO3TkkKF" alt=""><figcaption></figcaption></figure>


# Ballons ItemsAdder (simple)

{% hint style="warning" %}

### This requires ItemsAdder to work!

{% endhint %}

## Creating a balloon

### Step 1

Create a model following the tutorial

{% content-ref url="/pages/hboe6bWli2JL1FxJOkMK" %}
[Creating a model](/adding-content/creating-a-model)
{% endcontent-ref %}

### Step 2

Create the cosmetic configuration

```yaml
  simple_itemsadder_item_balloon:
    enabled: true
    display_name: "Simple ItemsAdder Item Balloon"
    type: BALLOON
    model:
      gui: iadeco:old_clock
      normal: iadeco:old_clock
```

### Step 3

You're done

<figure><img src="/files/ROxbCuc4jvvc1N9LyueU" alt=""><figcaption></figcaption></figure>


# Balloon (advanced)


# ItemsAdder Entity

{% hint style="warning" %}

### This requires ItemsAdder to work!

{% endhint %}

## Creating a balloon

### Step 1

Create an ItemsAdder entity reading the tutorial:

{% embed url="<https://itemsadder.devs.beer/plugin-usage/adding-content/mobs/advanced-method/creation>" %}

### Step 2

Create the cosmetic configuration

```yaml
  # Example custom kite created with ItemsAdder entities 
  # (supports also animated ItemsAdder entities models)
  amogus_balloon:
    display_name: "Amogus Balloon"
    type: BALLOON_ENTITY
    balloon:
      leash: true
    # Showing a different item into the GUI 
    # (in this case it's a must because ItemsAdder entities can't be put in GUIs)
    model:
      gui: minecraft:egg
      normal: cosmetics:amogus
    dye:
      enabled: true # To allow this item from being colored.
```

As you can see I set the `normal` model to the name of the **custom entity** created with ItemsAdder.

### Step 3

You're done

<figure><img src="/files/n48zHLCtoO9i62ql0CAc" alt=""><figcaption></figcaption></figure>

## Final notes

{% hint style="info" %}
You can even create animated balloons, just animate the idle animation of the entity using Blockbench.\
For example you can create a complex dragon or a rotating UFO. &#x20;
{% endhint %}


# ModelEngine

{% hint style="warning" %}

### This balloons type require ModelEngine to work.

{% endhint %}

## Creating a balloon

### Step 1

Create an ModelEngine entity, read the ModelEngine tutorials on their wiki (if available).\
Note that I'm not its developer.

### Step 2

Create the cosmetic configuration

```yaml
  # Example custom kite created with ItemsAdder entities 
  # (supports also animated ItemsAdder entities models)
  star_kite:
    display_name: "Star Kite"
    type: MEG_BALLOON_ENTITY
    balloon:
      leash: true
    # Showing a different item into the GUI 
    # (in this case it's a must because ModelEngine entities can't be put in GUIs)
    model:
      gui: minecraft:egg
      normal: star_kite
    dye:
      enabled: true # To allow this item from being colored.
```

As you can see I set the `normal` model to the name of the **custom entity** created with ModelEngine.

### Step 3

You're done

![](/files/BVAfWUjVCNaVzC8LjNx4)

## Final notes

{% hint style="info" %}
You can even create animated balloons, just animate the idle animation of the entity using Blockbench.\
For example you can create a complex dragon or a rotating UFO. &#x20;
{% endhint %}

## Leash location

{% content-ref url="/pages/YTfQd9PZMO9TNsRA0Ef4" %}
[Leash location](/adding-content/balloon-advanced/leash-location)
{% endcontent-ref %}


# Leash location

### Step 1

Create a new bone and call it `leash_pivot`.\
Set the `size` of the cube to `0, 0, 0`.

<figure><img src="/files/rGFSiHwpr17UdWzUGhqs" alt=""><figcaption></figcaption></figure>

### Step 2

Move it to where you want the leash to be attached.

<figure><img src="/files/bM8rbRrDBcaV0cD8b12Q" alt=""><figcaption></figcaption></figure>

Zoom and make the final adjustment to precisely place it where you want.

<figure><img src="/files/3hOBxyo5ZaWMAoEvaeAX" alt=""><figcaption></figcaption></figure>

### Step 3

Press Center Pivot button to center the pivot.

<figure><img src="/files/2vuq2fsiBFXPu1HLomg3" alt=""><figcaption></figcaption></figure>

### Done

<figure><img src="/files/cSiFDDOJRkNYEvi4OO6Q" alt=""><figcaption></figcaption></figure>


# Hat

## CustomModelData hat

You can create custom hats simply by using CustomModelData.

```yaml
  # Example manually created hat with CustomModelData
  cowboy_hat:
    display_name: "Cowboy Hat"
    type: HAT
    model:
      gui: potion:300003
      normal: potion:300003
    dye:
      enabled: false # To avoid this item from being colored.
```

In this example I created a custom hat with CustomModelData `300003`.\
I decided to use the same item both for the GUI preview and for the actual item which will be put on player's head.&#x20;

## ItemsAdder model

You can do the same thing but with ItemsAdder items models and avoid worrying about CustomModelData.

Example:

```yaml
  # Example manually created hat with CustomModelData
  cowboy_hat:
    display_name: "Cowboy Hat"
    type: HAT
    model:
      gui: my_items:cowboy_hat_icon
      normal: my_items:cowboy_hat
    dye:
      enabled: false # To avoid this item from being colored.
```

In this example you can see I used `my_items:cowboy_hat_icon` as icon `my_items:cowboy_hat` as item.\
They both are items from ItemsAdder.


# Body Cosmetic


# Static Body Cosmetic

## Models meaning

### Normal model

A normal model is the model which is shown to every player but the local player (yourself).\
This model is used only on Minecraft 1.20.1 and lower.

### Normal model 2

This normal model is the model which is shown to every player but the local player (yourself).\
This model is used only on Minecraft 1.20.2 and greater.

### Self model

The model which is shown ONLY to the local player (yourself).\
This self model is used only on Minecraft 1.20.1 and lower.

### Self model 2

The model which is shown ONLY to the local player (yourself).\
This self model is used only on Minecraft 1.20.2 and greater.

## Creation methods

### CustomModelData

You can create custom body items simply by using **CustomModelData**.

```yaml
  # Example manually created hat with CustomModelData
  squirrel_tail:
    display_name: "Squirrel Tail"
    type: BODY_ITEM
    model:
      gui: potion:400008
      normal: potion:400008
      normal_2: potion:410008
      self: potion:400009
    dye:
      enabled: false # To avoid this item from being colored.
```

In this example I created a custom body item with CustomModelData `400008`.\
I decided to use the same item both for the GUI preview and for the actual item which will be put on player's body.\
I then set a self model, which is the model shown only to the local player and not to the other players, in this case I set the CustomModelData to `400009`.&#x20;

### ItemsAdder

Same thing but using **ItemsAdder** models to avoid worrying about **CustomModelData**.

#### Example:

```yaml
  # Example custom Item created by ItemsAdder
  squirrel_tail:
    display_name: "Squirrel Tail"
    type: BODY_ITEM
    model:
      gui: my_item:squirrel_tail
      normal: my_item:squirrel_tail
      self: my_item:squirrel_tail_self
    dye:
      enabled: false # To avoid this item from being colored.
```

In this example I created a custom body item by using the ItemsAdder model named `squirrel_tail`.\
I decided to use the same item both for the GUI preview and for the actual item which will be put on player's body.\
I then set a self model, which is the model shown only to the local player and not to the other players, in this case I set it to `squirrel_tail_self`.

## Avoid cosmetics from obstructing view

It's important to have 3 separated models because the self models will avoid getting the player view occupied by the cosmetic and potentially cause annoyances during the gameplay (placing blocks, attacking, walking).

{% hint style="warning" %}
If you are not interested into setting a `self` and `normal` model you can skip this tutorial and only use the `normal` attribute\
Do not set the `self` attribute at all if you don't want to use a different item for the self view.
{% endhint %}

{% tabs %}
{% tab title="Without the self model" %}
![](/files/BtXnUSwSvnrnteDRi6rk)

![](/files/0Z0ztSd2Jt5eXCsI8QYv)
{% endtab %}

{% tab title="With the self model" %}
![](/files/DLPfdH7oGiFdItrPh08k)

![](/files/0Z0ztSd2Jt5eXCsI8QYv)
{% endtab %}
{% endtabs %}

## Implementing the self models

### Step 1

Decide a new **CustomModelData** for that item and add it to the item file or use **ItemsAdder** to automate the process (depends on your needs, refer to [ItemsAdder wiki ](https://itemsadder.devs.beer/)to learn how to create items).

In this example I use `400008` for the **normal** model and `400009` for the **self** model.

`assets/minecraft/models/item/XXX.json`

```json
{
  "predicate": { "custom_model_data": 400008 },
  "model": "cosmetics:body/squirrel_tail"
},
{
  "predicate": { "custom_model_data": 410008 },
  "model": "cosmetics:body/squirrel_tail_normal_2"
},
{
  "predicate": { "custom_model_data": 400009 },
  "model": "cosmetics:body/squirrel_tail_self"
},
{
  "predicate": { "custom_model_data": 410009 },
  "model": "cosmetics:body/squirrel_tail_self_2"
},
```

### Step 2

Edit your cosmetics configuration and add the **self** model.

```yaml
  squirrel_tail:
    display_name: "Squirrel Tail"
    type: BODY_ITEM
    model:
      gui: potion:400008
      normal: potion:400008
      normal_2: potion:410008
      self: potion:400009   # <------ HERE
      self_2: potion:410009   # <------ HERE
    dye:
      enabled: false # To avoid this item from being colored.
```

### Step 3

Install the official [Blockbench extension](https://cosmeticscore.devs.beer/files-editor).\
Open your `.json` file using **Blockbench**.

{% hint style="info" %}
This is a very important important step. \
You have to create the 2 **self** models and edit them until you are satisfied.
{% endhint %}

<figure><img src="/files/4NAnwcUPdhV0UIj2V6Hq" alt=""><figcaption></figcaption></figure>

\
You can use the preview to check exactly how the model will be shown ingame.

<figure><img src="/files/uaKG1Z08gCSo2suNUhZv" alt=""><figcaption></figcaption></figure>

## Issues with big models

If your model is too big and you cannot move it down you have to use "**Auto fix self model**".

<figure><img src="/files/PDODUyaTSmFKKCdeAxXf" alt=""><figcaption></figcaption></figure>

{% embed url="<https://youtu.be/uWobYhX691c>" %}

### Result

<div><figure><img src="/files/hADaaiLN5cmhGWcJGHtL" alt=""><figcaption></figcaption></figure> <figure><img src="/files/qPgemYwM251ziQtpFAeg" alt=""><figcaption></figcaption></figure></div>


# Advanced Body Item

{% hint style="warning" %}

### Advanced body item require ItemsAdder to work.

{% endhint %}

## Creating the entity

### Step 1

Create an ItemsAdder entity reading the tutorial:

{% embed url="<https://itemsadder.devs.beer/plugin-usage/adding-content/mobs/advanced-method/creation>" %}

### Step 2

Create the cosmetic configuration

```yaml
  wings_enderdragon:
    display_name: "Enderdragon Wings"
    type: BODY_ENTITY
    model:
      gui: dragon_head
      normal: cosmetics:wings_enderdragon
    dye:
      enabled: false # To avoid this item from being colored.
```

As you can see I set the `normal` model to the name of the **custom entity** created with ItemsAdder.

### Step 3

You're done

<figure><img src="/files/DqclN5nXtQ4vcP7hreTU" alt=""><figcaption></figcaption></figure>

## Final notes

{% hint style="info" %}
You can even create animated cosmetics, just animate the idle animation of the entity using Blockbench.
{% endhint %}

## Known issues

{% hint style="warning" %}

### Delayed cosmetic while moving

This is a known issue and cannot be fixed, but note that this behavior is only visible by the current player.<br>

All other players will see the cosmetic attached to the player with less delay.\
This also depends on the player ping and on the server performance.
{% endhint %}

{% tabs %}
{% tab title="Current player view" %}
{% embed url="<https://youtu.be/TiR3SKT_JRE>" %}
{% endtab %}

{% tab title="Other players view" %}
{% embed url="<https://youtu.be/YGCt6RXiMRw>" %}
{% endtab %}
{% endtabs %}


# Settings

## Enable/disable in worlds

Enable it in particular worlds:

```yml
cosmetics:
  worlds:
    - "world"
    - "world_nether"
```

Enable it in all worlds:

```yml
cosmetics:
  worlds:
    - "*"
```

Enable it in worlds which name starts with `world_` :

```yml
cosmetics:
  worlds:
    - "world_*"
```


# Wardrobe


# Customization

## Locations

You have to set the world and its coordinates, you can also set the yaw and pitch rotations.\
To get these values just use `/coords` command of **Essentials** or use `F3`.

### Camera location

Command: `/cosmeticsconfig config set camera-location`

![](/files/z2kVZgncE2TjstOYvtUW)

### Mannequin location

Command: `/cosmeticsconfig config set mannequin-location`

Location of the player to preview the cosmetics in the wardrobe.

![](/files/8tksk8TIqcknfZypahXx) ![](/files/MJouJYbmqiSclAViy3FV)

### Teleport area

This is a bit different, you have to set two points which represent the area in which the player can enter to open the wardrobe.

Command: `/cosmeticsconfig config set door-area-locations`

<div align="center"><img src="/files/ih8gsWumAQCMi81KzdRW" alt=""></div>

#### For better precision

<figure><img src="/files/jXKZy26qFUdC5E2HokNe" alt=""><figcaption></figcaption></figure>

### Exit location

Command: `/cosmeticsconfig config set exit-location`

Location where the player will be teleported back when they leave the wardrobe.

![](/files/y0ubXdWRYM4ryrQ1HwBq)

## Other camera settings

{% code title="" %}

```yaml
  camera:
    hide_actionbar_texts: true
    use_invisibility_potion: false
    rotation:
      manual:
        enabled: true
        step: 20
      auto:
        enabled: true
        direction: RIGHT
        step: 1.5
        pause_ticks_on_manual_rotation: 60
    zoom:
      enabled: true
      min: 2
    fade_effect: true
```

{% endcode %}

* `hide_actionbar_texts` : hide any actionbar message. Useful to hide HUDs created by ItemsAdder and similar plugins
* `use_invisibility_potion`: add invisibility potion to the player when they join the wardrobe (should not be needed)
* `rotation` : preview NPC rotation using the mouse wheel
  * `manual`: rotate the NPC using the mouse wheel while the cursor is not on the NPC
  * `auto`: automatically rotate the NPC
    * `pause_ticks_on_manual_rotation`: duration of the auto rotation pause after mouse scroll
* `zoom`: zoom using the mouse wheel, while the cursor is on the NPC&#x20;
  * `min`: is the min zoom amount
* `fade_effect`: black screen fade animation on enter-exit the wardrobe

## Graphics customization

```yaml
    slots:
      colors:
        owned: 56,67,100
        not_owned: 195,147,57
        wearing: 57,70,195
        wearing_preview: 195,120,57
        max_amount_reached_owned: 24, 29, 43
        max_amount_reached_not_owned: 64, 48, 17
```

{% hint style="warning" %}

### Warning

Colors must be int RGB colors separated with a comma, you can get them from any color picker.\
HEX and integer colors are not supported for now.
{% endhint %}

To generate these colors you can use any website which offers an **RGB color picker**.\
For example [this one](https://www.rapidtables.com/web/color/RGB_Color.html).

These properties are used to set colors of the slots in the wardrobe GUI.

![](/files/RZokQudVwJvu3J8rYVyb)

* **Owned**: color of the cosmetics owned (with permission)
* **Not owned**: color of the cosmetics not owned (no permission)
* **Wearing**: color of the cosmetics currently equipped
* **Wearing** preview: color of the cosmetics currently equipped but not owned (no permission), equipped only as preview
* **Max amount reached**: color of all the other cosmetics which cannot be equipped because the player is already wearing the max amount for that category


# Saving player data

## Configuration

```yaml
save:
  # Use only one at a time
  file:
    enabled: true
  mysql:
    enabled: false
    url: "jdbc:mysql://my_url_database_69.com:3306/database_name"
    username: "username"
    password: "password"
    table: "cosmeticscore_saved"

```

## File

This is the default method, it uses a wardrobe file for each player.

## MySQL

This is the method used by networks, this allows you to have multiple servers using the same wardrobe data for each player. Your players will then have the same equipped items when travelling on your network.\
(this obviously requires you to set up the plugin on each server with the same cosmetics files).


# Contribute


# Edit the English wiki

## How to edit this wiki?

### Setting up your repository

Open the [**Github** repository](https://github.com/LoneDev6/Wiki-CosmeticsCore) of this wiki, press on **`Fork`**.&#x20;

<figure><img src="/files/HEZKfwIxtJwKrchkIy2x" alt=""><figcaption></figcaption></figure>

Make sure you're on the `master` branch.

<figure><img src="/files/W1S2upLfe5kFDiAVokcy" alt=""><figcaption></figcaption></figure>

Select a file you want to edit and press the **pen** button

<figure><img src="/files/VbE5hKmC97KuZwxRamiz" alt=""><figcaption></figcaption></figure>

Edit the file and then press <mark style="color:green;">**Commit changes**</mark>

<figure><img src="/files/lh9T4wEn67e8bRSzr742" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}

## Important notes

* Do not remove the `#` special characters, edit only the next text, these are titles.
* Do not remove or edit special texts inside `{ }`, for example `{% hint style="info" %}`, these are used to create the hint message boxes.
* Do not remove `*` character, these are used to create lists
* Do not remove emojis
* Do not edit or remove the `--- description: ---` text on top of some pages, edit only the inner text.
* Do not remove `\` on some lines end
  {% endhint %}

### Example of what you *<mark style="color:red;">must not</mark>* edit

<figure><img src="/files/B4DMg5Hm92gnamEKkKR5" alt=""><figcaption></figcaption></figure>

### Last step

Contact **LoneDev** in order to get your changes reviewed and added to the wiki.\
Feel free to ping **LoneDev** on the Discord or to open a support ticket in the community channel.

{% hint style="info" %}
Would be good if you update your repository each time the main repository (the one in English) gets edited, to reflect changes.

To sync it you have to press **Fetch Upstream**.\
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork>

![](/files/K7mf0ziiUjxmMidqHzmg)

\
You can keep track of changes in the Discord notification channel.

![](/files/NyrDfsQ8dpVYlN6hpk1h)
{% endhint %}


# Translate this wiki

## How to translate this wiki?

### Getting a new branch for your language

Contact LoneDev and ask him to create a **new branch** for your language.\
Feel free to ping **LoneDev** on the Discord or to open a support ticket in the community channel.

### Setting up your repository

Then, after the branch creation, open the [**Github** repository](https://github.com/LoneDev6/Wiki-ItemsAdder) of this wiki, press on **`Fork`**.

![](/files/HEZKfwIxtJwKrchkIy2x)

Untick this option!

<figure><img src="/files/uqKhtCLL2zQn8SsKkjge" alt=""><figcaption></figcaption></figure>

Click here to change the branch.

{% hint style="warning" %}
DO NOT EDIT THE `master` BRANCH!
{% endhint %}

<figure><img src="/files/bTqIpHnAJBFwm97jtLXL" alt=""><figcaption></figcaption></figure>

Select a file you want to edit and press the **pen** button

<figure><img src="/files/7Cx4B6JJGt6ztbTnXb0M" alt=""><figcaption></figcaption></figure>

Edit the file and then press <mark style="color:green;">**Commit changes**</mark>

<figure><img src="/files/g7CIh8BVgsF4DUnCKtX1" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}

## Important notes

* Do not add content or new pages, only translate texts.
* The only content you can add is a "translated by" text in the welcome page.
* Do not remove the `#` special characters, translate only the next text, these are titles.
* Do not remove or edit special texts inside `{ }`, for example `{% hint style="info" %}`, these are used to create the hint message boxes.
* Do not remove `*` character, these are used to create lists
* Do not remove emojis
* Do not translate or remove the `--- description: ---` text on top of some pages, translate only the inner text.
* Do not remove `\` on some lines end
* Do not remove `[TEXT](LINK)` part, translate only the text, these are the clickable links.
  {% endhint %}

### Example of what you *<mark style="color:red;">must not</mark>* edit

![](/files/B4DMg5Hm92gnamEKkKR5)

### Last step

Contact **LoneDev** in order to get your changes reviewed and added to the wiki.\
Feel free to ping **LoneDev** on the Discord or to open a support ticket in the community channel.

{% hint style="info" %}
Would be good if you update your translation each time the main repository (the one in English) gets edited, to reflect changes.\
You can keep track of changes in the Discord notification channel.

![](/files/QktkieVjHbuWED5gnBml)
{% endhint %}


# Preview wiki changes

<figure><img src="/files/S2893N9dgmVAIweO347S" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/ri03ebIzAZJr4SUBMwKA" alt=""><figcaption></figcaption></figure>


# Compatibility with other plugins


# Compatible


# ItemsAdder

## Plugin

{% embed url="<https://spigot.devs.beer/itemsadder/>" %}

## Features

{% content-ref url="/pages/2soXCwnzhnijhbCGfefa" %}
[Advanced Body Item](/adding-content/body-cosmetic/advanced-body-item)
{% endcontent-ref %}

{% content-ref url="/pages/oQNkZe6KVIHUjQ7aeoXR" %}
[ItemsAdder Entity](/adding-content/balloon-advanced/itemsadder-entity)
{% endcontent-ref %}


# Vulcan

{% embed url="<https://www.spigotmc.org/resources/vulcan-anti-cheat-advanced-cheat-detection-1-7-1-19.83626/>" %}

## Enable compatibility

Open `config.yml` of Vulcan and set `enable-api: true`

### Why is this needed?

This compatibility option fixes the failed `Bad Packets (Type V)` kick false positive.


# PlaceholderAPI

## Check if cosmentic is equipped

`%cosmetics_has_equipped_<id>%`

Example: `%cosmetics_has_equipped_red_parrot%`

Check if a cosmetic in a category is equipped

`%cosmetics_has_equipped_category_<category>%`

* `hat`
* `body`
* `balloon`

Example: `%cosmetics_has_equipped_category_body%`


# Java API

{% hint style="warning" %}
This API is currently under development and can change during time
{% endhint %}

The API is under this package:&#x20;

```
dev.lone.cosmeticscore.api.temporary
```


# Branding

## Download branding assets

The below ZIP file contains assets that you can use for your resource page or in your own assets related to CosmeticsCore.\
Make sure to read the [Usage terms](#usage-terms) before doing anything though.

{% file src="/files/Aj5VuJHdhmVe31OLG6hi" %}

### Preview of the zip content

<figure><img src="/files/MpxEOAXP11ZKo8C3gS49" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/n004eHwxPSuP9FebmI66" alt=""><figcaption></figcaption></figure>

## Usage terms

You **can** use the assets...

* on resource pages for Add-ons and/or plugins supporting CosmeticsCore that you own.
* in own images for your resources.

...under the following conditions:

* You do not claim ownership over the assets. Original ownership stays with LoneDev, the developer of CosmeticsCore.
* You do not claim to have created those assets yourself.
* You do not use the assets or part of them to create your own resource logo.
* You do not redistribute the assets. This includes but isn't limited to modified versions of both the ZIP file and the actual files themself.
* Give credit to the original branding page (This one) by linking to it.
* The images may only be used to cite CosmeticsCore.

## Credits

* Thanks to Andre\_601 for the creation of the addon banner file.