Equipment resource pack → datapack converter

A Python script that converts Minecraft equipment resource packs into datapacks. It generates item modifier files and check functions so custom armor and elytra textures work with the equipment system.

Minecraft Version: 1.21.4+ (tested on 1.21.10)

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Usage
  • Local usage
  • GitHub Actions (automated)
• How It Works
• File Structure
• Examples
• Troubleshooting
• Contributing

---

Overview

The script scans a Minecraft resource pack for equipment JSON files (armor and elytra) and generates:

1. Item modifier JSON files that apply custom equipment textures
2. MCFunction check files that detect custom-named items and apply the appropriate modifiers
3. A datapack folder structure including pack.mcmeta

The generated datapack follows Minecraft 1.21.4+ equipment system conventions (tested on 1.21.10).

---

Features

• Automatic detection: scans equipment JSON files in the resource pack
• Layer recognition: detects humanoid, humanoid_leggings, and wings layers
• Filename conversion to display names (for example, dragon_armor → Dragon Armor)
• Material support: chainmail, copper, diamond, gold, iron, leather, netherite, turtle
• Elytra support: generates elytra check functions
• Turtle helmet special case: creates only helmet modifiers for turtle
• ZIP support: works with zipped or unzipped resource packs
• Custom namespace option for the generated datapack

---

Requirements

• Python 3.7+ (uses only standard library)
• No external dependencies required
• For GitHub Actions: Just a direct download URL to your resource pack

---

Installation

Option 1: Download equipment_to_datapack_converter.py and run it locally.

Option 2: Clone the repository:

git clone https://github.com/yourusername/equipment-to-datapack-converter.git
cd equipment-to-datapack-converter

---

Usage

Local usage

Basic command:

python equipment_to_datapack_converter.py <resource_pack_path> <output_datapack_path> [namespace]

Parameters:

• resource_pack_path (required): path to the resource pack (folder or ZIP)
• output_datapack_path (required): target directory for the generated datapack
• namespace (optional): datapack namespace (default: mccat)

Examples:

Convert a ZIP resource pack:

python equipment_to_datapack_converter.py ./MyResourcePack.zip ./output_datapack mccat

Convert an unzipped resource pack:

python equipment_to_datapack_converter.py ./MyResourcePack ./my_datapack custom

Using the default namespace:

python equipment_to_datapack_converter.py ./pack.zip ./output_pack

GitHub Actions (automated)

This repository includes GitHub Actions workflows that automatically convert resource packs:

Option 1: Submit via Issue

1. Go to the Issues tab
2. Create a new issue with your resource pack download URL
3. The workflow will automatically convert it and post a direct download link in the issue comments

Option 2: Manual workflow

1. Go to the Actions tab
2. Run the "Convert Resource Pack" workflow with your pack URL
3. Download the generated datapack artifact

For detailed instructions, see GITHUB_ACTIONS_GUIDE.md.

---

How it works

Step 1: resource pack scanning

The script searches for equipment JSON files in the following structure:

assets/
  minecraft/
    equipment/
      chainmail/
        dragon_armor.json
        shogun.json
      diamond/
        ellegaard.json
      elytra/
        15_year_elytra.json
      gold/
        shogun.json
      netherite/
        shogun.json
      ...

Step 2: layer detection

For each equipment JSON file, the script analyzes the layers field and generates the appropriate modifiers:

• wings → elytra item modifier
• humanoid / humanoid_leggings → armor modifiers (head, chest, legs, feet)
• Special case: turtle → helmet only

Step 3: item modifier generation

For armor:

{
  "function": "minecraft:set_components",
  "components": {
    "minecraft:equippable": {
      "slot": "head",
      "asset_id": "minecraft:netherite/shogun"
    }
  }
}

Generated file: data/mccat/item_modifier/netherite_shogun_head.json

For Elytra:

{
  "function": "minecraft:set_components",
  "components": {
    "minecraft:equippable": {
      "slot": "chest",
      "asset_id": "minecraft:elytra/15_year_elytra"
    }
  }
}

Generated file: data/mccat/item_modifier/elytra_15_year_elytra.json

Step 4: check function generation

For armor (example check_helmet_netherite.mcfunction):

execute if entity @s[nbt={equipment:{head:{id:"minecraft:netherite_helmet",components:{"minecraft:custom_name":'"Shogun"'}}}}] run item modify entity @s armor.head mccat:netherite_shogun_head
execute if entity @s[nbt={equipment:{head:{id:"minecraft:netherite_helmet",components:{"minecraft:custom_name":'"Dragon Armor"'}}}}] run item modify entity @s armor.head mccat:netherite_dragon_armor_head

For Elytra (check_elytra.mcfunction):

execute if entity @s[nbt={equipment:{chest:{id:"minecraft:elytra",components:{"minecraft:custom_name":'"15 Year Elytra"'}}}}] run item modify entity @s armor.chest mccat:elytra_15_year_elytra

Step 5: display name formatting

The script converts filenames to display names:

Filename	Display Name
dragon_armor	Dragon Armor
15_year_elytra	15 Year Elytra
ellegaard	Ellegaard
ill_elytra	Ill Elytra
mc_helmet	Mc Helmet

Important: The custom name in-game must match these generated display names exactly!

---

File structure

Input (resource pack)

MyResourcePack/
├── pack.mcmeta
└── assets/
    └── minecraft/
        ├── equipment/
        │   ├── chainmail/
        │   │   └── shogun.json
        │   ├── diamond/
        │   │   └── shogun.json
        │   ├── elytra/
        │   │   └── 15_year_elytra.json
        │   ├── gold/
        │   │   └── shogun.json
        │   ├── iron/
        │   │   └── shogun.json
        │   ├── leather/
        │   │   └── shogun.json
        │   ├── netherite/
        │   │   └── shogun.json
        │   └── turtle/
        │       └── turtle.json
        └── textures/
            └── entity/
                └── equipment/
                    ├── humanoid/
                    │   ├── chainmail/
                    │   │   └── shogun.png
                    │   ├── diamond/
                    │   │   └── shogun.png
                    │   └── ...
                    ├── humanoid_leggings/
                    │   └── ...
                    └── wings/
                        └── elytra/
                            └── 15_year_elytra.png

Output (Datapack)

my_datapack/
├── pack.mcmeta
├── Converted By ImHer0.txt
└── data/
    ├── mccat/
    │   ├── advancement/
    │   │   └── armor_changed.json
    │   ├── item_modifier/
    │   │   ├── chainmail_shogun_head.json
    │   │   ├── chainmail_shogun_chest.json
    │   │   ├── chainmail_shogun_legs.json
    │   │   ├── chainmail_shogun_feet.json
    │   │   ├── diamond_shogun_head.json
    │   │   ├── diamond_shogun_chest.json
    │   │   ├── diamond_shogun_legs.json
    │   │   ├── diamond_shogun_feet.json
    │   │   ├── elytra_15_year_elytra.json
    │   │   └── ...
    │   └── function/
    │       ├── load.mcfunction
    │       ├── 200ticks.mcfunction
    │       ├── check_all.mcfunction
    │       ├── check_condition.mcfunction
    │       ├── check_helmet_chainmail.mcfunction
    │       ├── check_chestplate_chainmail.mcfunction
    │       ├── check_leggings_chainmail.mcfunction
    │       ├── check_boots_chainmail.mcfunction
    │       ├── check_helmet_diamond.mcfunction
    │       ├── check_elytra.mcfunction
    │       ├── revoke.mcfunction
    │       └── ...
    └── minecraft/
        └── tags/
            └── function/
                ├── load.json
                └── tick.json

---

Examples

Example 1: Converting "Shogun Armor Pack"

Resource Pack Structure:

ShogunPack/
└── assets/
    └── minecraft/
        └── equipment/
            ├── chainmail/shogun.json
            ├── diamond/shogun.json
            ├── gold/shogun.json
            ├── iron/shogun.json
            └── netherite/shogun.json

Command:

python equipment_to_datapack_converter.py ./ShogunPack.zip ./shogun_datapack custom_armor

Result:

• Creates 20 item modifiers (5 materials × 4 slots)
• Creates check functions for each armor material and slot
• Generates advancement and tick system for automatic detection
• Namespace: custom_armor
• Output ZIP: MCCAT-ShogunPack.zip

Example 2: Converting "Elytra Collection"

Resource Pack Structure:

ElytraCollection/
└── assets/
    └── minecraft/
        └── equipment/
            └── elytra/
                ├── dragon_wings.json
                ├── angel_wings.json
                └── demon_wings.json

Command:

python equipment_to_datapack_converter.py ./ElytraCollection ./elytra_pack

Result:

• Creates 3 elytra item modifiers
• Creates check function for elytra detection
• Generates advancement and tick system
• Namespace: mccat (default)
• Output ZIP: MCCAT-ElytraCollection.zip

---

Troubleshooting

Issue: "No equipment files found"

Cause: the script couldn't find any JSON files in assets/*/equipment/

Fix:

• Verify the resource pack has the expected folder structure
• Confirm equipment JSON files exist in the correct locations
• For ZIP files, ensure the archive isn't double-nested (avoid pack.zip/pack/assets/...)

Issue: "JSON decode error"

Cause: one or more equipment JSON files are malformed

Fix:

• Validate the JSON files with a JSON validator
• Check for missing commas, brackets, or quotes
• Ensure UTF-8 encoding without BOM

Issue: generated names don't match in-game

Cause: display name formatting differs from in-game custom names

Fix:

• The script converts dragon_armor → Dragon Armor
• Ensure in-game names match this format exactly
• Rename items with an anvil if needed

Issue: turtle armor creates too many modifiers

Cause: turtle should only generate helmet modifiers

Fix:

• Check that the folder name is turtle
• Remember that folder name matching is case-sensitive on Linux/macOS

---

Naming conventions

Material name mapping

The script maps resource pack material folders to Minecraft item IDs:

Folder name	Minecraft item prefix
chainmail	chainmail_*
copper	copper_*
diamond	diamond_*
gold	golden_*
iron	iron_*
leather	leather_*
netherite	netherite_*
turtle	turtle_helmet (special)

Note: the gold folder maps to golden items in Minecraft.

Slot mapping

Equipment slot	Armor slot	Item modifier suffix
head	armor.head	_head
chest	armor.chest	_chest
legs	armor.legs	_legs
feet	armor.feet	_feet

---

Integration with existing datapacks

To integrate the generated datapack:

1. Copy generated item modifier files into your datapack
2. Merge check functions or append the generated commands to your existing functions
3. Use the namespace parameter to match your datapack namespace
4. Test in-game and rename items as needed

---

📝 License

This script is provided as-is for use with Minecraft datapacks and resource packs.

---

🤝 Contributing

Feel free to submit issues, fork the repository, and create pull requests for any improvements!

Potential Improvements:

• Custom name format configuration
• Support for custom advancement triggers
• Batch processing multiple resource packs
• GUI interface
• Direct ZIP output for datapack

---

📧 Support

If you encounter issues or have questions:

1. Check the Troubleshooting section
2. Review the Examples
3. Open an issue on GitHub with your resource pack structure

---

🙏 Credits

Created by ImHer0 for the Minecraft modding community.

This is a tool I wish already existed when I needed it, so I built it to help out people who are working with custom armor textures in Minecraft.

If you find this tool useful and want to support its development:

• PayPal: https://www.paypal.com/paypalme/ImHer0TM
• Ko-fi: https://ko-fi.com/imher0

---

Note

Every generated datapack includes a Converted By ImHer0.txt file with information about this tool and support links.

---

Happy Datapack Creating!