fabricpy 0.2.0

A lightweight helper library for writing Fabric mods in Python

fabricpy

Python Library that allows you to create Fabric Minecraft mods in Python! Write your mod logic in Python and automatically generate a complete, buildable Fabric mod project with Java source files, assets, and testing integration.

Features

✨ Easy Mod Creation: Define items, tools, blocks, and food with simple Python classes 🔧 Full Fabric Integration: Generates complete mod projects compatible with Fabric Loader
⛏️ Mining Configuration: Hardness, resistance, tool types, mining levels, and per-tool speed overrides
🧪 Built-in Testing: Automatically generates unit tests and game tests
🎨 Custom Creative Tabs: Create your own creative inventory tabs
📝 Recipe Support: Define crafting recipes with JSON
🎲 Loot Tables: Native loot table support with builder methods for common drop patterns
🚀 One-Click Building: Compile and run your mod directly from Python

Installation

Install fabricpy using pip:

pip install fabricpy

External Requirements

Before using fabricpy, you need to install these external dependencies:

1. Java Development Kit (JDK)

• Version Required: JDK 17 or higher (recommended JDK 21)
• Purpose: Compiles the generated Minecraft Fabric mod code
• Installation:
  • macOS: brew install openjdk@21 or download from Oracle
  • Windows: Download from Oracle or use winget install Oracle.JDK.21
  • Linux: sudo apt install openjdk-21-jdk (Ubuntu/Debian) or sudo yum install java-21-openjdk-devel (CentOS/RHEL)

2. Git

• Version Required: 2.0 or higher
• Purpose: Version control and cloning Fabric mod templates
• Installation:
  • macOS: brew install git or install Xcode Command Line Tools
  • Windows: Download from git-scm.com
  • Linux: sudo apt install git (Ubuntu/Debian) or sudo yum install git (CentOS/RHEL)

3. Gradle (Optional but recommended)

• Version Required: 8.0 or higher
• Purpose: Build system for Minecraft mods (auto-downloaded by Gradle Wrapper if not installed)
• Installation:
  • macOS: brew install gradle
  • Windows: choco install gradle or download from gradle.org
  • Linux: sudo apt install gradle or download from gradle.org

Quick Start

import fabricpy

# Create mod configuration
mod = fabricpy.ModConfig(
    mod_id="mymod",
    name="My Awesome Mod",
    version="1.0.0",
    description="Adds cool items to Minecraft",
    authors=["Your Name"]
)

# Create and register an item
item = fabricpy.Item(
    id="mymod:cool_sword",
    name="Cool Sword",
    item_group=fabricpy.item_group.COMBAT
)
mod.registerItem(item)

# Create a tool
pickaxe = fabricpy.ToolItem(
    id="mymod:ruby_pickaxe",
    name="Ruby Pickaxe",
    durability=500,
    mining_speed_multiplier=8.0,
    attack_damage=3.0,
    mining_level=2,
    enchantability=22,
    repair_ingredient="minecraft:ruby"
)
mod.registerItem(pickaxe)

# Create a food item
apple = fabricpy.FoodItem(
    id="mymod:golden_apple",
    name="Golden Apple", 
    nutrition=6,
    saturation=12.0,
    always_edible=True
)
mod.registerFoodItem(apple)

# Create a block
block = fabricpy.Block(
    id="mymod:ruby_block",
    name="Ruby Block",
    item_group=fabricpy.item_group.BUILDING_BLOCKS,
    loot_table=fabricpy.LootTable.drops_self("mymod:ruby_block")
)
mod.registerBlock(block)

# Compile and run
mod.compile()
mod.run()

Examples

Additional example scripts can be found in the examples directory.

Script	What it shows
basic_mod.py	Minimal mod — one item, one block, mod config
food_items.py	Food items with nutrition, smelting recipes, always_edible
blocks_and_recipes.py	Blocks with recipes, textures, click events, subclasses
custom_item_group.py	Custom creative tabs and assigning items to them
tool_item.py	Defining and registering a custom ToolItem
loot_table.py	Loot table patterns: self-drops, fortune, silk touch, entity & chest loot
mining_blocks.py	Mining config: hardness, tool types, mining levels, per-tool speeds
full_mod.py	Complete mod tying together every library feature

Advanced Features

Custom Creative Tabs

# Create a custom creative tab
custom_tab = fabricpy.ItemGroup(
    id="my_weapons",
    name="My Weapons"
)

# Use the custom tab
sword = fabricpy.Item(
    id="mymod:diamond_sword",
    name="Diamond Sword",
    item_group=custom_tab
)

Crafting Recipes

# Define a shaped recipe
recipe = fabricpy.RecipeJson({
    "type": "minecraft:crafting_shaped",
    "pattern": ["###", "#X#", "###"],
    "key": {
        "#": "minecraft:gold_ingot",
        "X": "minecraft:apple"
    },
    "result": {"id": "mymod:golden_apple", "count": 1}
})

# Attach recipe to item
apple = fabricpy.FoodItem(
    id="mymod:golden_apple",
    name="Golden Apple",
    recipe=recipe
)

💡 Tip: Use the Crafting Recipe Generator to easily create crafting recipe JSON files with a visual interface!

Loot Tables

# Block that drops itself
block = fabricpy.Block(
    id="mymod:ruby_block",
    name="Ruby Block",
    loot_table=fabricpy.LootTable.drops_self("mymod:ruby_block")
)

# Ore with fortune-affected drops
ore = fabricpy.Block(
    id="mymod:ruby_ore",
    name="Ruby Ore",
    loot_table=fabricpy.LootTable.drops_with_fortune(
        "mymod:ruby_ore", "mymod:ruby",
        min_count=1, max_count=2
    )
)

# Silk-touch-only glass
glass = fabricpy.Block(
    id="mymod:crystal_glass",
    name="Crystal Glass",
    loot_table=fabricpy.LootTable.drops_with_silk_touch("mymod:crystal_glass")
)

# Entity loot table
from fabricpy import LootPool, LootTable

zombie_loot = LootTable.entity([
    LootPool()
        .rolls(1)
        .entry("mymod:fang", weight=3)
        .entry("mymod:eye", weight=1)
])
mod.registerLootTable("custom_zombie", zombie_loot)

Mining Tools & Speeds

Configure how blocks are mined, which tools are required, and per-tool speed overrides:

# Ore that requires an iron pickaxe
ruby_ore = fabricpy.Block(
    id="mymod:ruby_ore",
    name="Ruby Ore",
    hardness=3.0,
    resistance=3.0,
    tool_type="pickaxe",
    mining_level="iron",
    loot_table=fabricpy.LootTable.drops_with_fortune(
        "mymod:ruby_ore", "mymod:ruby",
        min_count=1, max_count=3,
    )
)

# Block with per-tool speed overrides (pickaxe fast, shovel slower)
mixed_ore = fabricpy.Block(
    id="mymod:mixed_ore",
    name="Mixed Ore",
    hardness=4.0,
    resistance=4.0,
    requires_tool=True,
    mining_level="stone",
    mining_speeds={
        "pickaxe": 8.0,
        "shovel": 3.0,
    },
)

# Tough block that needs a diamond pickaxe
reinforced = fabricpy.Block(
    id="mymod:reinforced_block",
    name="Reinforced Block",
    hardness=25.0,
    resistance=600.0,
    tool_type="pickaxe",
    mining_level="diamond",
)

Valid tool types: "pickaxe", "axe", "shovel", "hoe", "sword". Valid mining levels: "stone", "iron", "diamond".

Testing Integration

fabricpy automatically generates comprehensive tests for your mod:

# Run unit tests
./gradlew test

# Run game tests (in-game testing)
./gradlew runGametest

Documentation

📚 Full Documentation

Code Coverage

📊 Code Coverage Report

Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• @danielkorkin

---

Made with ❤️ for the Minecraft modding community