GunCosmetics — Dynamic Skins & Keychains for TACZ

GunCosmetics is a powerful, data-driven expansion for the Timeless and Classics Zero (TACZ) mod. It introduces a complete cosmetic ecosystem for your firearms, allowing players to personalize their weapons with high-quality skins and animated 3D charms.

✨ Features

• Weapon-Specific Skins: Apply unique textures and even custom GeckoLib models to specific weapons.
• Universal Paintjobs: Use "Universal" skins that act as an overlay, compatible with any weapon in the game.
• 3D Animated Charms (Keychains): Attach 3D accessories to your gun. They support GeckoLib animations (idle, shaking, etc.) and can be attached to any bone of the weapon model.
• Seamless TACZ Integration: No need for complex commands. GunCosmetics adds dedicated "Skin" and "Charm" slots directly into the TACZ Gun Modification Screen.
• Cosmetic Editor: A dedicated UI to preview cosmetics and fine-tune the position, rotation, and scale of your charms in real-time.
• Server-Side Sync: Content is automatically synced from the server to all connected clients. Players don't need to manually install resource packs to see each other's custom skins.
• Rarity System: Items come in five rarity tiers (Common to Legendary), each with distinct visual styling in the UI.

🛠️ Technical Overview

• Platform: Minecraft 1.20.1 (Forge)
• Dependencies: TACZ, GeckoLib
• Architecture: Built using Mixins and a custom data-loading pipeline to ensure zero impact on original TACZ gameplay performance.

---

🎨 Creator's Guide: Adding Your Own Content

GunCosmetics uses a Pack System similar to TACZ. You don't need to write any code — just JSON and assets.

1. Folder Structure

Create a folder or ZIP file in your .minecraft/guncosmetics/ directory with the following structure:

guncosmetics/
└── my_custom_pack/ (or my_custom_pack.zip)
    ├── pack.json
    ├── assets/ (Optional: for custom translations)
    │   └── mypack/lang/en_us.json
    ├── skins/
    │   ├── golden_ak47.json
    │   └── textures/
    │       └── golden_ak47.png
    └── keychains/
        ├── duck_charm.json
        ├── models/
        │   └── duck.geo.json
        ├── textures/
        │   └── duck.png
        └── animations/
            └── duck_idle.animation.json

2. Pack Metadata (pack.json)

Every pack must have a pack.json at its root.

{
  "id": "mypack",
  "name": "My Epic Cosmetic Pack",
  "author": "CreatorName",
  "version": "1.0.0",
  "description": "High quality skins for your arsenal."
}

3. Adding a Skin (skins/*.json)

Skins can be "specific" (for one gun) or "universal".

Example: Specific Skin

{
  "id": "mypack:golden_ak47",
  "display_name": "Golden AK-47",
  "target_gun": "tacz:ak47",
  "type": "specific",
  "rarity": "epic",
  "texture": "textures/golden_ak47.png"
}

4. Adding a Charm (keychains/*.json)

Charms use GeckoLib models (.geo.json) and can include animations.

Example: Charm

{
  "id": "mypack:rubber_duck",
  "display_name": "Rubber Duck",
  "rarity": "rare",
  "model": "models/duck.geo.json",
  "texture": "textures/duck.png",
  "animation": "animations/duck_idle.animation.json",
  "default_attachment": {
    "bone": "stock",
    "offset": [0.0, -1.5, 0.0],
    "rotation": [0.0, 90.0, 0.0],
    "scale": [1.0, 1.0, 1.0]
  }
}

Note: The bone field specifies which part of the gun model the keychain sticks to.

---

🚀 Installation

1. Ensure you have Forge 1.20.1, TACZ, and GeckoLib installed.
2. Download the GunCosmetics jar and place it in your mods folder.
3. Launch the game. A guncosmetics folder will be created in your game directory.
4. Drop your custom packs (folders or ZIPs) into .minecraft/guncosmetics/.
5. Use /guncosmetics reload in-game to see your changes!

---

📜 Commands

• /guncosmetics open: Opens the standalone Cosmetic Editor.
• /guncosmetics reload: Reloads all cosmetic packs from the disk (OP only).
• /guncosmetics give <player> skin/keychain <id>: Grants a specific skin/keychain item.