Manas Cosmetics Configuration
==============================

This directory contains cosmetic definition files for Manas Cosmetics.
Each .json file in the cosmetics/ folder defines a single cosmetic item
that can be equipped by players.

──────────────────────────────────────────────────────────────────────
Quick Start (Recommended Workflow)
──────────────────────────────────────────────────────────────────────

1. Drop your .bbmodel file into the correct slot subfolder under models/
   (see "Models Directory Structure" below for the folder layout).
2. Run /manas_cosmetics generate in-game.
   This scans every slot subfolder and creates a .json sidecar in
   cosmetics/ for every .bbmodel that doesn't already have one.
   The command also performs a reload, so cosmetics are live immediately.
3. (Optional) Open the generated .json in cosmetics/ and tweak the
   scale, offset, rotation, or display_name to taste.
4. If you edited a .json, run /manas_cosmetics reload to apply changes.

──────────────────────────────────────────────────────────────────────
Models Directory Structure
──────────────────────────────────────────────────────────────────────

Place .bbmodel files in the subfolder that matches the cosmetic slot.
The slot (and, for weapons, the weapon type) is deduced from the path
automatically when you run /manas_cosmetics generate.

  models/
    helmet/            ← hat/crown cosmetics
    above_head/        ← floating items above the head
    chestplate/        ← chest cosmetics
    back/              ← wings, capes, backpacks
    front/             ← chest-front cosmetics
    legs/              ← leg cosmetics
    boots/             ← foot cosmetics
    armor_set/         ← full-body armour suits (one model spanning head/body/arms/legs)
    ears/              ← ear cosmetics (attaches to head, both ears in one model)
    orbit/             ← orbiting particles/objects
    pet/               ← companion pet models (auto-scaled to ≤1 block tall)
    aura/              ← (no model needed) procedural aura particles around the player
    weapon/            ← main-hand weapon overlays (renders over held item)
      sword/           ←   shown when holding a sword
      longsword/       ←   shown when holding a longsword
      katana/          ←   shown when holding a katana
      kodachi/         ←   shown when holding a kodachi
      spear/           ←   shown when holding a spear
      hammer/          ←   shown when holding a hammer
      axe/             ←   shown when holding an axe
      scythe/          ←   shown when holding a scythe
      bow/             ←   shown when holding a bow
      kunai/           ←   shown when holding a kunai
      pickaxe/         ←   shown when holding a pickaxe
      gauntlet/        ←   shown when holding a gauntlet
      greatsword/      ←   shown when holding a greatsword
      shield/          ←   shown when holding a shield
      grimoire/        ←   shown when holding a grimoire
      magic_staff/     ←   shown when holding a magic staff
      any/             ←   shown with any weapon
    shield/            ← off-hand shield slot cosmetics
    grimoire/          ← grimoire cosmetics (generated as slot="weapon", weapon_type="grimoire")
    magic_staff/       ← magic staff cosmetics (generated as slot="weapon", weapon_type="magic_staff")

──────────────────────────────────────────────────────────────────────
Cosmetic .json File Structure
──────────────────────────────────────────────────────────────────────

{
  "id":                  "manas_cosmetics:cosmetic_name",
  "display_name":        "Cosmetic Display Name",
  "slot":                "back",
  "weapon_type":         "any",
  "force_equip_allowed": true,
  "model":               "models/back/cosmetic_model.bbmodel",
  "scale":               [1.0, 1.0, 1.0],
  "offset":              [0.0, 0.0, 0.0],
  "rotation":            [0.0, 0.0, 0.0]
}

──────────────────────────────────────────────────────────────────────
Field Explanations
──────────────────────────────────────────────────────────────────────

Required Fields
───────────────
  id               Unique identifier for the cosmetic.
                   Format: mod_id:cosmetic_name
                   Example: "manas_cosmetics:angel_wings"

  display_name     Human-readable name shown in the wardrobe GUI.
                   Example: "Angel Wings"

  slot             Attachment point on the player model where the
                   cosmetic appears. See "Available Slots" below.

  model            Path to the .bbmodel file, relative to the
                   config/manas_cosmetics/ folder.
                   Example: "models/back/angel_wings.bbmodel"

Optional Fields
───────────────
  weapon_type          Restricts cosmetic visibility to players holding
                       a specific weapon class. Defaults to "any".
                       See "Weapon Types" below for valid values.

  force_equip_allowed  When true, players can equip this cosmetic even
                       if they are not holding the required weapon type.
                       Defaults to true.

  scale                [x, y, z] multiplier for the cosmetic's size.
                       Defaults to [1.0, 1.0, 1.0] (original size).

  offset               [x, y, z] position adjustment relative to the
                       attachment point, in BBModel units.
                       Defaults to [0.0, 0.0, 0.0].

  rotation             [x, y, z] rotation in degrees applied after scale.
                       Defaults to [0.0, 0.0, 0.0].
                       Cosmetics attach to the matching vanilla body
                       part automatically, so the default no-rotation
                       pose already matches the player's orientation.
                       Override only if your bbmodel is authored in
                       a non-standard orientation.

──────────────────────────────────────────────────────────────────────
Scale Values
──────────────────────────────────────────────────────────────────────

The scale array controls the size of your cosmetic in three dimensions:

  "scale": [scaleX, scaleY, scaleZ]

  scaleX   Width scaling  (left-right)
  scaleY   Height scaling (up-down)
  scaleZ   Depth scaling  (front-back)

Common Scale Values
───────────────────
  [1.0, 1.0, 1.0]   Original size (no scaling)
  [0.5, 0.5, 0.5]   Half size
  [1.5, 1.5, 1.5]   50% larger
  [0.8, 0.8, 0.8]   Slightly smaller (good for wings)
  [1.2, 1.2, 1.2]   Slightly larger

Scale Tips
──────────
  Wings / Capes    Use smaller values (0.6-0.8) to avoid body clipping.
  Hats / Helmets   Use 1.0 or slightly above for a proper fit.
  Accessories      Adjust based on visual reference in-game.
  Asymmetric       Use different values per axis when needed,
                   e.g. [1.0, 0.8, 1.2] stretches depth without
                   changing width or height.

──────────────────────────────────────────────────────────────────────
Offset Values
──────────────────────────────────────────────────────────────────────

The offset array controls the position of your cosmetic relative to
the attachment point:

  "offset": [offsetX, offsetY, offsetZ]

  offsetX   Left-right  (negative = left,    positive = right)
  offsetY   Up-down     (negative = down,     positive = up)
  offsetZ   Front-back  (negative = forward,  positive = back)

Offsets are optional. Every slot already attaches to the matching
vanilla body part (helmet → head, chestplate / back / front → body,
boots → feet, weapon → hand, …) with a sensible default position,
so authored bbmodels typically render correctly with the generated
[0, 0, 0] offset. Reach for offsets only to fine-tune placement for
a specific model.

Offset Tips
───────────
  Start from zero    Default [0, 0, 0] is correct for most models.
  Start small        Adjust in 0.1-unit increments when tuning.
  Test in-game       Check positioning from multiple angles.
  Consider anims     Ensure the offset works across crouch / swim.

──────────────────────────────────────────────────────────────────────
Available Slots
──────────────────────────────────────────────────────────────────────

  helmet       On the player's head
  above_head   Floating above the head
  chestplate   On the chest
  back         On the back (wings, capes, backpacks)
  front        In front of the chest
  legs         On the legs
  boots        On the feet
  armor_set    Full-body armour suit. One model whose bones bind to the
               player skeleton: name them head / body / arm_l / arm_r /
               leg_l / leg_r (the side is also inferred from each bone's
               pivot X) so each limb follows the player's animation.
               Equipping a set clears the helmet/chestplate/legs/boots
               cosmetics, and vice versa; you wear one or the other.
  ears         Attached to the sides of the head (model defines both ears)
  orbit        Orbiting around the player
  pet          Companion entity (auto-scaled to ≤1 block tall).
               Add "floats": true to the pet sidecar to make it
               hover and fly-follow the owner instead of walking.
  aura         Procedural particle effect around the player (no model file; see aura example)
  weapon       Overlaid on the held weapon / tool
  shield       In the shield (off) hand
  grimoire     In the offhand as a magic book
  magic_staff  In the main hand as a staff

──────────────────────────────────────────────────────────────────────
Weapon Types
──────────────────────────────────────────────────────────────────────

  any          No restriction; always visible
  sword        Swords only
  axe          Axes only
  bow          Bows only
  hammer       Hammers only
  katana       Katanas only
  kodachi      Kodachi only
  kunai        Kunai only
  longsword    Longswords only
  magic_staff  Magic staves only
  scythe       Scythes only
  shield       Shields only
  spear        Spears only
  pickaxe      Pickaxes only
  gauntlet     Gauntlets only
  greatsword   Greatswords only

──────────────────────────────────────────────────────────────────────
Example Configurations
──────────────────────────────────────────────────────────────────────

Basic Wings (models/back/angel_wings.bbmodel)
───────────────────────────────────────────
{
  "id":           "manas_cosmetics:angel_wings",
  "display_name": "Angel Wings",
  "slot":         "back",
  "model":        "models/back/angel_wings.bbmodel",
  "scale":        [1.0, 1.0, 1.0]
}

Sword Weapon Overlay (models/weapon/sword/icicle_blade.bbmodel)
───────────────────────────────────────────────────────────────
Weapon-slot cosmetics anchor to the hand via the sword-oriented
hand transform, and offset/rotation are applied ON TOP of that
anchor. Use them to nudge a BBModel whose grip isn't exactly at
its origin (e.g. tall staves, asymmetric grimoires) back into
the hand without re-authoring the model.
{
  "id":           "manas_cosmetics:icicle_blade",
  "display_name": "Icicle Blade",
  "slot":         "weapon",
  "weapon_type":  "sword",
  "model":        "models/weapon/sword/icicle_blade.bbmodel",
  "scale":        [1.0, 1.0, 1.0],
  "offset":       [0.0, 0.0, 0.0],
  "rotation":     [0.0, 0.0, 0.0]
}

Floating Hat (models/above_head/wizard_hat.bbmodel)
─────────────────────────────────────────────────
{
  "id":           "manas_cosmetics:wizard_hat",
  "display_name": "Wizard Hat",
  "slot":         "above_head",
  "model":        "models/above_head/wizard_hat.bbmodel",
  "scale":        [1.0, 1.0, 1.0],
  "offset":       [0.0, 0.9, 0.0]
}

Aura (no model file, procedural particles)
───────────────────────────────────────────
EASIEST WAY: run /manas_cosmetics edit <new_name> with a name
that doesn't exist yet; this creates the aura and opens the
in-game aura designer (live preview, style/particle/color
controls, Save & Reload). No JSON editing needed.

For hand-editing: auras pick a built-in style and tune it.
"colors" is 1-4 RGB stops blended over each particle's
lifetime. "particle" picks the texel shape of each particle.
All other numbers are multipliers on the style's defaults
(1.0 = stock); "particle_count" is absolute (0 = style
default, max 1024).
Styles:    rising_motes, twin_helix, halo, circle, vortex_shroud,
           rune_circle, orbiting_orbs, starfield_shimmer,
           ember_crown, falling_embers, pulse_rings, triangle,
           pentagram, hexagram, magic_circle, arcane_array,
           summoning_circle.
Particles: glow (soft mote), orb (hard ball), spark (4-point
           star), pixel (crisp square), smoke (fuzzy blob).
{
  "id":           "manas_cosmetics:my_flame",
  "display_name": "My Flame",
  "slot":         "aura",
  "aura": {
    "style":           "vortex_shroud",
    "particle":        "glow",
    "colors":          [[255, 200, 60], [255, 90, 20], [120, 20, 20]],
    "particle_count":  0,
    "size":            1.0,
    "speed":           1.0,
    "radius":          1.0,
    "height":          1.0,
    "alpha":           1.0,
    "rotation_speed":  1.0,
    "emissive":        true,
    "motion_response": 1.0
  }
}
A legacy sidecar with only "aura_color": [r, g, b] still works;
it renders the original rising motes in that tint.

──────────────────────────────────────────────────────────────────────
Troubleshooting
──────────────────────────────────────────────────────────────────────

Cosmetic Not Visible
  - Check that the model path in your .json matches the actual file name.
  - Verify scale isn't too small; try [1.0, 1.0, 1.0] to rule it out.
  - Ensure the chosen slot has an attachment point on the player model.

Poor Positioning
  - Adjust offset values in small increments (0.05-0.1 at a time).
  - Try different scale values; large cosmetics may appear off-centre.
  - Remember that each slot has a different base origin.

Clipping Into the Body
  - Reduce scale values.
  - Adjust offset to move the cosmetic away from the body.
  - Try a different attachment slot if clipping persists.

Red Tint / Wrong Colours
  - Ensure the model has a valid texture assigned in Blockbench.
  - Use PNG format for textures.
  - Verify the model's UV mapping is correct.

──────────────────────────────────────────────────────────────────────
File Organisation
──────────────────────────────────────────────────────────────────────

  config/manas_cosmetics/
    cosmetics/              ← .json sidecar files (auto-generated or manual)
    models/
      <slot>/               ← .bbmodel files for each slot
      weapon/
        <weapon_type>/      ← .bbmodel files for each weapon type
    README.txt              ← this file (auto-updated on startup)

Naming tips:
  - Use descriptive, lowercase file names, e.g. angel_wings.bbmodel
  - The cosmetic "id" field must be unique across all loaded cosmetics.
  - If two models in different slot folders share the same filename, the
    second one will be skipped during generate; use distinct names.

──────────────────────────────────────────────────────────────────────
Commands
──────────────────────────────────────────────────────────────────────

Cosmetic Management (OP only)
─────────────────────────────

  /manas_cosmetics edit <id>
    Open the in-game editor for a specific cosmetic. Model
    cosmetics get the transform editor (offset / rotation /
    scale nudge controls); AURA cosmetics get the aura designer
    (style, particle, colors, and all tuning values with live
    preview). If <id> doesn't exist yet, a new aura is created
    under that name and the designer opens on it. Click
    "Save & Reload" to persist to the sidecar JSON and
    broadcast the updated registry to all clients. OP only.

  /manas_cosmetics generate
    Scan every models/ subfolder and write a .json sidecar in
    cosmetics/ for each .bbmodel that doesn't have one yet, then
    auto-reload so the new cosmetics are live immediately.

  /manas_cosmetics delete <id>
    Delete a single cosmetic's config (its .json sidecar) and
    auto-reload so it disappears immediately. The .bbmodel is left
    in place, so /generate can re-create the sidecar later. Only
    one cosmetic can be deleted per command; there is no bulk form.

  /manas_cosmetics delete withmodel <id>
    As above, but also delete the cosmetic's .bbmodel model file.
    If another loaded cosmetic still references that same model the
    file is kept (and you are told so) to avoid breaking it.

  /manas_cosmetics reload
    Reload all .json files in cosmetics/ and all kit files in
    kits/ without restarting the server. Also pushes the updated
    registry to every connected client.

  /manas_cosmetics list
    Print every currently loaded cosmetic (id, slot, display name).

  /manas_cosmetics give <player> <id>
    Unlock a single cosmetic for <player> and auto-equip it in
    the correct slot. Useful for a quick all-in-one handout.

  /manas_cosmetics giveitem <player> <ids>
    Give one cosmetic-ticket item per id to <player>'s inventory
    (items drop at their feet if the inventory is full).
    <ids> accepts: a single id, a comma-separated list, or "all".

  /manas_cosmetics unlock <player> <ids>
    Add one or more cosmetic ids to <player>'s unlocked set so
    they can equip those cosmetics through the wardrobe.
    <ids> accepts: a single id, a comma-separated list, or "all".

  /manas_cosmetics revoke <player> <ids>
    Remove cosmetic ids from <player>'s unlocked set and
    immediately unequip any of the revoked cosmetics they are
    currently wearing.
    <ids> accepts: a single id, a comma-separated list, or "all".

  /manas_cosmetics unlocked <player>
    List every cosmetic id currently in <player>'s unlocked set.

Kit Commands
─────────────

  /manas_cosmetics kit list
    List every available kit with its claim status for the
    running player (or just the kit names if run from console).

  /manas_cosmetics kit claim <kit_id>
    Claim a kit as the current player. Adds every cosmetic in
    the kit to your unlocked set. Respects the kit's cooldown.

  /manas_cosmetics kit grant <player> <kit_id>     (OP)
    Grant a kit to <player>, bypassing the cooldown. Also
    records the claim timestamp so their /kit list shows it.

  /manas_cosmetics kit reset <player>              (OP)
    Reset every kit cooldown for <player> so they can claim
    all kits again immediately.

  /manas_cosmetics kit reset <player> <kit_id>     (OP)
    Reset the cooldown of a single kit for <player>.

Wardrobe
─────────

  /manas_cosmetics wardrobe
    Open the wardrobe GUI for the running player (no permission
    required). The server syncs the player's latest cosmetic data
    before opening the screen.

──────────────────────────────────────────────────────────────────────
License
──────────────────────────────────────────────────────────────────────

Manas Cosmetics is distributed under the Manas Cosmetics License.
The full terms ship inside the mod jar at manas_cosmetics/LICENSE.txt.
In short: free to use on any server (including monetised ones), but the
mod and its models, textures, and other assets may not be modified,
reused, repackaged, or turned into content for other projects. Download
only from the official CurseForge and Modrinth pages.
