> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/edcosmetics/cosmetics/importing.md).

# Importing Your Own Cosmetics

Bring your own hats, wings, back items and emotes in without touching the resource pack: drop the files into a folder, run one command, and they are cosmetics.

1. Put the files into `plugins/EdCosmetics/imports/`:

   * `hats/` hats and other head pieces
   * `wings/` wings and back items (backpacks, capes, tails...)
   * `emotes/` emote animations

   Files dropped straight into `imports/` are recognised automatically too, and zip files are unpacked for you.
2. Run `/edcosmetics import`.
3. Every file is converted: the resource pack files are made, the cosmetic is added to its category file (`categories/hats.yml`, `categories/wings.yml`, `emotes/emotes.yml`), the plugin reloads and the resource pack is installed again. Players rejoin to download the new pack.
4. Edit the new cosmetic like any other: name, description, rarity, permission, price...

The reply lists what each file became and anything worth checking (a rotation that had to be rounded, a texture that was missing, a model that uses a lot of video memory).

## What can be imported

|                        |                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hats**               | Blockbench models (`.bbmodel`, any format), Java item models (`.json` and their textures), Bedrock models (`.geo.json` + `.png`), and whole ItemsAdder, Oraxen, Nexo or HMCCosmetics folders: every hat their configs describe is imported                                                                                                                                 |
| **Wings & back items** | Blockbench models (`.bbmodel`) with their animations, Bedrock / Lunar style models (`.geo.json` + `.png` + `.animation.json` + `cosmetic_info.json`), Java item models worn on the back, and the back items (wings, backpacks, capes, tails...) of ItemsAdder, Oraxen or Nexo item configs, also inside HMCCosmetics / CosmeticsCore / MagicCosmetics packs that ship them |
| **Emotes**             | Emotecraft and PlayerAnimator emotes (`.json`, `.emotecraft`), Bedrock / GeckoLib player animations (`.animation.json`), Blockbench player-template animations (`.bbmodel`, one emote per animation)                                                                                                                                                                       |

### Hats

Models made as a helmet (with a `head` display) sit exactly where their author put them. A model with no `head` display is placed on the head for you. Clients up to 1.21.x only allow one rotation axis per cube in steps of 22.5°: rotations that don't fit are rounded for those clients (the reply names the cubes), while 26.1+ clients get the exact model. Every imported hat also gets its emote version, so it stays glued to the head while emoting.

### Wings & back items

Built on Blockbench's player template (feet at y 0, the body is the box x -4..4, y 12..24, z -2..2). Bones, cube rotations, meshes, inflate, per-face and box UV, several textures, animated textures and Blockbench animations are read. One animation named like *idle* plays standing still; one named *fly* / *walk* / *run* plays while moving. A texture named `<name>_glow` (or `_e`, `_emissive`) is a glow mask for `<name>`: its white pixels glow in the dark. They come with a combined look for every armour in `equipment-combos.yml`, a menu icon rendered from the model (or your own `<name>_icon.png`) and their emote version.

Bedrock / Lunar folders keep their state machine: the idle state is baked standing still, the moving state while walking, and an animated texture (`extra_1.json` / `.png.mcmeta`) keeps playing. A Blockbench model made in the Java block / item format (built in 0..16) is moved onto the back for you. Java item models from a pack hang centred on the back; give them a `flap` in their `.yml` to make static wings beat.

Every model is drawn in layers of 4 faces; `max-layers` (default 32) keeps big models light for the clients by leaving out the smallest faces first (the reply says how many). The reply also warns when a design needs a lot of video memory (big animated textures): shrink the texture or lower `fps` / `max-frames`.

### Emotes

The animation is mapped onto the plugin's player model (head, body, arms, legs and the whole body's turn and position). Each emote gets a wheel icon (rendered from its pose, or your own `<name>_icon.png`) and its name on the wheel.

## Options

A `.yml` file with the same name next to a model changes how it is imported, e.g. `fire_wings.yml` next to `fire_wings.bbmodel`:

```yaml
id: fire_wings              # the cosmetic id (default: the file name)
name: '&6Fire Wings'        # the name shown in menus
description:
  - '&7Wings made of flames.'
rarity: epic
category: wings             # another category file of the same type
scale: 1.0                  # bigger or smaller
offset: [0, 0, 0]           # move it (Blockbench pixels)
```

Wings and back items also understand:

| Key                                                    | What it does                                                                                                  |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `idle` / `run`                                         | the animation names to use standing still / moving                                                            |
| `frames`                                               | baked frames per animation, `{ idle: 24, run: 16 }`                                                           |
| `glow`, `glow-strength`                                | texture names that glow as a whole, and how much (0..1, default 0.6)                                          |
| `glowA` / `glowB`                                      | the two colours glowing pixels pulse between (`'#ffaa33'`)                                                    |
| `max-layers`                                           | detail limit (default 32, 0 = none)                                                                           |
| `seam`                                                 | grows flat planes by this many pixels so hinged membrane pieces overlap (no cracks at the bends)              |
| `smooth`, `snap-run`                                   | smooth texture filtering; switch to the moving animation at once instead of blending                          |
| `icon`                                                 | a png to use as the menu icon                                                                                 |
| `cosmetic`                                             | extra keys copied into the cosmetic's entry                                                                   |
| Bedrock / Lunar: `fps`, `max-frames`, `loop`           | frames a second (12), frame cap (72), loop length in seconds                                                  |
| Bedrock / Lunar: `vars`, `idle-vars`, `run-vars`       | Molang variables to start with, e.g. `{ v.state: 2 }`                                                         |
| Bedrock / Lunar: `idle-anims`, `run-anims`             | the animations to play, overriding the state machine                                                          |
| Bedrock / Lunar: `textures`                            | more textures: `[{ file, width, height, frame-height, frametime }]`                                           |
| Java item model: `java`, `assets`                      | `'namespace:path'` of the model, and the folder holding `<namespace>/models` and `<namespace>/textures`       |
| Java item model: `display`, `rotation`                 | the display transform that orients it (`head`), or your own rotation `[x, y, z]`                              |
| Java item model: `fit`, `fit-y`, `fit-z`, `fit-ignore` | centred on the back (`back`), its height and depth (pixels), textures left out of the fit                     |
| Java item model: `flap`                                | a baked wing beat: `{ hinge, center, idle: { period, fold: [min, max], roll: [min, max], lag }, run: {...} }` |

Hats also understand `rotation: [x, y, z]` (or one number for the yaw).

Emotes understand:

| Key                                 | What it does                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `names`                             | the name per language, e.g. `{ es: 'Saludo', de: 'Gruß' }` (the wheel shows `name` for the others)           |
| `permission`                        | its own permission (default `<permission-prefix>.<id>`; `''` = everyone)                                     |
| `loop`, `speed`, `max-loop-seconds` | play it in a loop, faster / slower, and how long a loop may last                                             |
| `sound`                             | a sound played when it starts                                                                                |
| `icon`, `icon-time`, `icon-yaw`     | a png for the wheel (or `<name>_icon.png` next to the file); else the moment and angle of the automatic icon |
| `props`, `particles`                | the same as in `emotes/emotes.yml`                                                                           |
| `animation` / `animations`          | which animations of a file to import (every one by default)                                                  |

The plugin's player model has no elbows or knees: bent forearms and shins, and single parts that move instead of turning, are left out (the reply says so). Lunar `.bobj` emotes can't be read; export from Emotecraft as `.json`.

## Running it again

`/edcosmetics import` only converts files that changed since the last time: edit a model or its `.yml` and import again to update the cosmetic. `/edcosmetics import force` converts everything again, `/edcosmetics import <name>` only files whose name contains `<name>`.

What imports make is kept in `plugins/EdCosmetics/generated/` (its resource pack files and lists), apart from the plugin's own files, so plugin updates never remove your cosmetics. Delete a cosmetic from its category file to remove it from the menus.