Parts & Models
A cosmetic renders as one or more parts. Each part is either a flat icon (a floating item model) or a GeckoLib 3D model, anchored to a body point and transformed with offset / rotation / scale.
Making the files
This page is the reference for the fields. For a step-by-step on creating the models and textures — folder paths, Blockbench, drawing the texture — see Making Models & Textures.
The two rendering modes
1. Flat icon / vanilla model
Set customModelData_or_ID to a name. The mod looks for, in order:
assets/greatcosmetics/textures/icons/<name>.png— a plain flat icon (most common).assets/greatcosmetics/models/<name>.json— a custom vanilla item model.
The part is drawn as that item model floating at the anchor.
2. GeckoLib model
Set geoModelId to a name. This takes priority over the flat icon. The mod looks for, in any namespace:
geo/item/<name>.geo.json— requiredtextures/item/<name>.png— required (the mod also tries the folder that mirrors the.geopath)animations/item/<name>.animation.json— optional (see State animations)
Exact Path mode
With useExactPath on, the two fields above stop being "just the file name" and become a full relative path resolved by exact match in any namespace:
| Mode | Field value | Resolves to |
|---|---|---|
| Off | wizard_hat |
.../models/wizard_hat.json (namespace greatcosmetics for vanilla models) |
| On | hats/wizard_hat |
.../models/hats/wizard_hat.json in any namespace |
| On (Geo) | item/wizard_hat |
.../geo/item/wizard_hat.geo.json in any namespace |
Use it when your files sit in subfolders or in another mod's namespace, or when two files share a name.
Anchors
Where the part attaches:
HEAD, BODY, RIGHT_ARM, LEFT_ARM, RIGHT_LEG, LEFT_LEG
The anchor follows the body part's animation (head turns, arms swing), then the part's offset/rotation/scale are applied on top.
Transforms
| Group | Fields | Used |
|---|---|---|
| Scale | scaleX/Y/Z (default 1.0) |
Always |
| Normal values | offsetX/Y/Z, rotationX/Y/Z |
While standing |
| Sneak values | shiftOffsetX/Y/Z, shiftRotationX/Y/Z |
While the player is sneaking |
Sneak values exist because the vanilla sneak pose bends the body — a hat that sits right while standing may clip while crouched, so you tune a separate position for it.
The 3D gizmo
In the Dev Studio, select a part (click it in the outliner or open >> Config Part). Then, anywhere outside the panel:
- Hold
X,YorZ— locks the axis. - Drag the mouse — the part moves, rotates or scales live (pick the mode with the Move / Rotate / Scale buttons in the popup).
The text fields update as you drag, and vice-versa. Toggle the sidebar S button to edit the Sneak pose the same way.
Whenever a part (or an effect) is selected, three colour-coded buttons also appear on the center-right of the screen: X (red), Y (green), Z (blue) — matching the gizmo's own axis colours. Clicking one instantly resets that axis's Offset back to zero, or, while previewing the Sneak pose with the sidebar S toggle, resets the Sneak/Shift Offset for that axis instead — a quick way to snap a part back to dead-center on its anchor without dragging the gizmo by hand or typing 0 into a field.
Multiple parts
Add parts with + Add Part. A single cosmetic can combine, say, a GeckoLib hat on HEAD plus a flat feather icon offset to the side — each with its own transform. There's no hard limit; keep it reasonable for performance.
State animations
(GeckoLib parts only — flat icons never animate.)
A GeckoLib model plays an animation from its .animation.json based on what the wearer is doing — idle, walking, flying, and so on. There is no controller code to write and nothing to configure: the mod picks the clip purely by its name. Give a clip one of the fixed names below and it plays in that state; a model whose .animation.json has none of these names stays completely static (the old behaviour).
The fixed names
| Name | Plays when | Falls back to |
|---|---|---|
idle |
Standing still (the default / rest state) | — |
walk |
Moving on the ground | idle |
run |
Sprinting on the ground | walk → idle |
fly |
Flying (creative / cosmetic flight) or gliding with an elytra | idle |
swim |
In water and off the ground | walk → idle |
fall |
In the air, not flying (jumping / falling) | idle |
sneak |
Sneaking | (nothing — see below) |
Priority (the first one whose clip actually exists wins): sneak → fly → swim → fall → run → walk → idle.
sneak is special: if the model has no sneak clip, crouching is transparent — the animation doesn't change (a moving player keeps playing walk, a still one keeps idle). Every other name falls back down the chain to idle.
You only need the clips you care about. A cape with just idle and fly is fine — walking, sneaking, etc. all resolve down to idle (or, for sneak, just don't change anything).
Naming in Blockbench
You don't have to rename anything to the bare word. The mod matches a clip whose name ends with the fixed name after a separator, so all of these count as idle:
idleanimation.dragon_wings.idle— Blockbench's defaultanimation.<model>.<action>ground_idle/animation.charizard.ground_idle— the Cobblemon convention (ripped Pokémon animations)battle_idle,air_idle, … — anything ending_idle/-idle
Same for the others: ground_walk → walk, ground_run → run, air_fly → fly. When several clips could match, the more specific one wins (.idle beats ground_idle beats battle_idle). Clips with ride or test in the name are ignored.
Want an always-on animation?
A model that should always do the same thing (a slowly spinning halo, a flickering flame) — just name that clip idle. It loops in every state because everything falls back to idle.
Notes
- Every clip loops. One-shot animations are not supported here.
- Each wearer animates independently — two players in the same cosmetic don't sync.
- Blending between states is smoothed over ~5 ticks.
- In the Dev Studio the preview player just stands there, so you'll only see
idle(or nothing). Test movement animations in the world.
Checklist for a new model
- Drop the files in your resource pack (icon or
.geo+ texture). /gc reload(or restart the client) so it scans the pack.- Dev Studio → + Cosmetic → set Slot, Type, Display Name.
- In 3D Models, type the file name into Model/ID (flat) or GeckoLib Model ID (3D). Turn on Exact Path if the file is in a subfolder/namespace.
>> Config Part→ position it with the gizmo.Sto save. It's live for everyone.