Skip to content

Developer Guide

Jump to bottom
cech12 edited this page May 5, 2026 · 57 revisions

Add a Bucket

Adding BucketLib to your project:

Add the following to your build.gradle file:

repositories {
    maven {
      name 'Jitpack'
      url 'https://jitpack.io'
    }
}

Neoforge:

dependencies {
    implementation "com.github.cech12.BucketLib:neoforge:${bucketlib_version}"
}

Forge:

dependencies {
    implementation "com.github.cech12.BucketLib:forge:${bucketlib_version}"
}

Fabric:

dependencies {
    //required dependency by bucketlib
    modImplementation("me.shedaniel.cloth:cloth-config-fabric:${cloth_config_version}") {
        exclude(group: "net.fabricmc.fabric-api")
    }
    modImplementation("com.github.cech12.BucketLib:fabric:${bucketlib_version}")
}

Replace ${bucketlib_version} with the version of BucketLib that you want to use. The actual versions can be found here or on the Github Releases page. If you are planning to support a version range, please consider my versioning description to choose the right range.

Forge specific: BucketLib adds mixins and developers need to make sure to tweak their run configurations in order to launch the game in their development environment. Add both of these lines to the configureEach {} run configuration block in the build.gradle (or to both the client {} and server {}). These can be placed anywhere within the run configuration, the order does not matter. (not required for versions before BucketLib 1.19.3-1.2.0.0)

property 'mixin.env.remapRefMap', 'true'
property 'mixin.env.refMapRemappingFile', "${buildDir}/createSrgToMcp/output.srg"

Don't forget to re-generate your IDE runs. (genIntellijRuns, genEclipseRuns, or genVSCodeRuns)

Before BucketLib 1.20.6-3.3.0.0 (Forge)

In 1.20.6 Forge removed the obfuscation. So, before that version, the build.gradle adjustments were differently:

dependencies {
    implementation fg.deobf("com.github.cech12.BucketLib:forge:${bucketlib_version}")
}

Before BucketLib 1.20.2-3.0.0.0

The build.gradle adjustments were differently:

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly fg.deobf("com.github.cech12:BucketLib:${bucketlib_version}:api")
    runtimeOnly fg.deobf("com.github.cech12:BucketLib:${bucketlib_version}")
}

All other adjustments are the same. (see above)

Create your bucket

To create a bucket, you only need to register a new item of the class UniversalBucketItem and register it via an IMC message at the BucketLib mod by using the BucketLibApi::registerBucket method.

Here is an example of a Forge mod:

//...
import de.cech12.bucketlib.api.BucketLibApi;
import de.cech12.bucketlib.api.item.UniversalBucketItem;
//...

@Mod(MOD_ID)
public class YourMod {

    public static final String MOD_ID = "yourmod";
    public static final DeferredRegister<Item> ITEMS = DeferredRegister.create(ForgeRegistries.ITEMS, MOD_ID);

    public static final RegistryObject<Item> YOUR_BUCKET = ITEMS.register("your_bucket", () -> new UniversalBucketItem(
        //configure your bucket by changing the properties (this example sets the durability of the bucket to 100)
        new UniversalBucketItem.Properties().durability(100)
    ));

    public YourMod() {
        IEventBus modEventBus = FMLJavaModLoadingContext.get().getModEventBus();
        //example of registering your bucket item
        ITEMS.register(modEventBus);
        //register for IMC event (can also be done by using "@SubscribeEvent")
        modEventBus.addListener(this::sendImc);
    }

    private void sendImc(InterModEnqueueEvent evt) {
        //register your bucket at the BucketLib mod to activate all features for your bucket
        BucketLibApi.registerBucket(YOUR_BUCKET.getId());
    }

}

Configure your bucket

Your bucket can be configured by changing the passed UniversalBucketItem.Properties object.

Here is an example of the Ceramic Bucket Forge mod (a NeoForge version can also be found there):

    public static final RegistryObject<Item> CERAMIC_BUCKET = ITEMS.register("ceramic_bucket", () -> new UniversalBucketItem(
            new UniversalBucketItem.Properties()
                    .upperCrackingTemperature(ServerConfig.CERAMIC_BUCKET_BREAK_TEMPERATURE)
                    .crackingFluids(ModTags.Fluids.CERAMIC_CRACKING)
                    .milking(ServerConfig.MILKING_ENABLED)
                    .entityObtaining(ServerConfig.FISH_OBTAINING_ENABLED)
                    .dyeable(14975336) //dyeable was removed in 1.21.4-4.3.0.0 in favor of defining tints in the model files
                    .durability(ServerConfig.CERAMIC_BUCKET_DURABILITY)
    ));

It adds server config objects to the properties upperCrackingTemperature, entityObtaining, milking and durability to let the users decide the values. The property crackingFluids can be set via a list of fluids or (in this case) with a fluid tag. This enables the possibility to change the fluids with datapacks or mods like CraftTweaker. The property dyeable contains a hard coded color and enables the possibility to dye the bucket.

A list of all properties can be found in the class UniversalBucketItem.Properties.

Since 26.1

The vanilla dye recipe changed and you need to add your own recipe to enable dyeing at the crafting table:

Example:

{
  "type": "minecraft:crafting_dye",
  "category": "misc",
  "dye": "#minecraft:dyes",
  "result": {
    "id": "ceramicbucket:ceramic_bucket"
  },
  "target": "ceramicbucket:ceramic_bucket"
}

Since 1.21.4

The dyeable method was removed in favor of defining tints in the model files, to not hardcode the colors any longer.

Since 1.20.6

Handling enchantment and dyeable behaviour were moved to item tags in vanilla Minecraft. Therefore it is recommended to add your bucket to the following item tags:

  • minecraft:dyeable when you configured your custom bucket with the dyeable method. (enables the dye recipe)
  • minecraft:enchantable/durability when you configured your custom bucket with the durability method. (enables the unbreaking enchantment)

Models & Textures

since 1.21.4-4.3.0.0

To have a dynamic item model for your new bucket, you should use the given model type bucketlib:universal_bucket wihtin your item model (assets/YOURMOD/items/your_bucket.json). It automatically adds the content textures (fluids, blocks, entities) and provides standard textures for the base, lowerBase, fluidMask, crackedBase, crackedLowerBase, crackedFluidMask.

The lower textures are needed for entity buckets, because the textures of them are placed lower than for fluid or block buckets. Example textures can be found here and in the Ceramic Bucket mod.

The cracked textures only need to be overridden if your bucket uses cracking properties like upperCrackingTemperature or lowerCrackingTemperature.

You can add a tint color, if your bucket is dyeable. Don't forget to add your bucket to the "minecraft:dyeable" item tag, if you want it to be dyeable using dye at the crafting table.

It is recommended to not overwrite the fluid masks and to have a similar position for the bucket contents to support the textures of other mods entities & blocks, that can be picked up by a bucket.

Here is an example of the Ceramic Bucket mod:

{
  "model": {
    "type": "bucketlib:universal_bucket",
    "textures": {
      "base": "ceramicbucket:item/ceramic_bucket",
      "lowerBase": "ceramicbucket:item/ceramic_bucket_lower",
      "crackedBase": "ceramicbucket:item/ceramic_bucket_cracked",
      "crackedLowerBase": "ceramicbucket:item/ceramic_bucket_cracked_lower"
    },
    "tints": [
      {
        "type": "minecraft:dye",
        "default": -1801880
      }
    ]
  }
}

before 1.21.4-4.3.0.0

To have a dynamic item model for your new bucket, you should use the given parent model bucketlib:item/universal_bucket wihtin your item model (assets/YOURMOD/models/item/your_bucket.json). It automatically adds the content textures (fluids, blocks, entities) and provides standard textures for the base, lowerBase, fluidMask, crackedBase, crackedLowerBase, crackedFluidMask.

You can overwrite the standard textures to add your own design to your bucket.

The lower textures are needed for entity buckets, because the textures of them are placed lower than for fluid or block buckets. Example textures can be found here and in the Ceramic Bucket mod.

The cracked textures only need to be overridden if your bucket uses cracking properties like upperCrackingTemperature or lowerCrackingTemperature.

It is recommended to not overwrite the fluid masks and to have a similar position for the bucket contents to support the textures of other mods entities & blocks, that can be picked up by a bucket.

Here is an example of the Ceramic Bucket mod:

{
  "parent": "bucketlib:item/universal_bucket",
  "textures": {
    "base": "ceramicbucket:item/ceramic_bucket",
    "lowerBase": "ceramicbucket:item/ceramic_bucket_lower",
    "crackedBase": "ceramicbucket:item/ceramic_bucket_cracked",
    "crackedLowerBase": "ceramicbucket:item/ceramic_bucket_cracked_lower"
  }
}

Example Mods

Make your mod compatible

Classes & interfaces

Fluids

Every registered fluid that returns through its getBucket() method a bucket item which extends the BucketItem class is compatible with this library mod.

Blocks

Your mod adds bucket items which contain blocks (like powder snow)? To be compatible with this library mod, these bucket items need to extend the vanilla SolidBucketItem class.

Entities

When your mod adds entities that can be picked up with a bucket, some things must be followed to be compatible with this library mod.

The bucket items must extend the vanilla class MobBucketItem and the corresponding entities must implement the vanilla interface Bucketable.

Textures

The textures of your bucket contents (blocks & entities) must be placed in the following directory:

assets/YOURMOD/textures/item/bucket_content/ID_OF_CONTENT.png

Example: Your mod with the mod id epicmod adds a new block with the id epicmod:quicksand. Your texture should be placed here: assets/epicmod/textures/item/bucket_content/quicksand.png

Since 1.20.1-2.3.6.0, 1.20.4-3.2.3.0, 1.20.6-3.3.2.0, 1.21-4.1.3.0 and 1.21.3-4.2.1.0 you can also oversteer the fluid textures in the same way like for entities and blocks.

Example: You don't want to use the animated texture of your "bestmod:special_lava" fluid, then place an overlay texture to that place in your resource pack: assets/bestmod/textures/item/bucket_content/special_lava.png

Example Mods

Clone this wiki locally