Plush API

Plush API

Butterfly API includes a reusable system for creating interactive plush blocks.

Butterfly plushes use normal Minecraft block models and do not use GeckoLib.

A Butterfly plush includes:

• A placed block
• A matching block item
• A shared plush block entity type
• A honk sound
• Squish state when interacted with
• Normal block-model lighting
• Cutout texture support

Creating a Plush Entrypoint

Create a class that implements PlushEntrypoint.

package com.example;

import moth.butterflyapi.plush.PlushEntrypoint;
import moth.butterflyapi.plush.PlushRegistrar;

public final class ExamplePlushes
        implements PlushEntrypoint {

    @Override
    public void registerPlushes(
            PlushRegistrar registrar
    ) {
        registrar.plush(
                ExampleMod.MOD,
                "glow_moth_plush"
        );
    }
}

Register the Entrypoint

Add your plush entrypoint to fabric.mod.json.

{
  "entrypoints": {
    "butterfly_api:plush": [
      "com.example.ExamplePlushes"
    ]
  }
}

Butterfly will call this entrypoint and register your plushes.

Customizing a Plush

Pass a builder callback when the plush needs additional settings.

registrar.plush(
        ExampleMod.MOD,
        "heavy_plush",
        plush -> plush
                .sound("glow_moth_plush_honk")
                .blockSettings(
                        AbstractBlock.Settings.create()
                                .strength(0.5F)
                                .sounds(
                                        BlockSoundGroup.WOOL
                                )
                                .nonOpaque()
                                .dynamicBounds()
                )
                .itemSettings(
                        ExampleMod.MOD
                                .itemSettings(
                                        "heavy_plush"
                                )
                                .maxCount(16)
                )
                .onUse(
                        blockEntity ->
                                blockEntity.markDirty()
                )
);

Custom Sound

Override the normal plush sound with:

.sound("glow_moth_plush_honk")

The default sound ID for a plush is:

<modid>:<plush_path>_honk

For example:

example_mod:glow_moth_plush_honk

Custom Block Settings

Use .blockSettings(...) when the plush needs different block properties.

.blockSettings(
        AbstractBlock.Settings.create()
                .strength(0.5F)
                .sounds(BlockSoundGroup.WOOL)
                .nonOpaque()
                .dynamicBounds()
)

Custom Item Settings

Use .itemSettings(...) to modify the matching plush item.

.itemSettings(
        ExampleMod.MOD
                .itemSettings("heavy_plush")
                .maxCount(16)
)

Interaction Callback

Use .onUse(...) to add custom behavior when the plush is used.

.onUse(
        blockEntity ->
                blockEntity.markDirty()
)

Plush Tags

Registered plush blocks are automatically added to:

ButterflyApiTags.PLUSH_BLOCKS

Registered plush items are automatically added to:

ButterflyApiTags.PLUSH_ITEMS

These shared tags can be used when code needs to recognize Butterfly-compatible plushes.

Basic Resource List

A plush normally uses:

assets/<modid>/blockstates/<plush>.json
assets/<modid>/models/block/<plush>.json
assets/<modid>/models/item/<plush>.json
assets/<modid>/items/<plush>.json
assets/<modid>/textures/block/<plush>.png
assets/<modid>/sounds.json
assets/<modid>/sounds/<plush>_honk.ogg

data/<modid>/loot_table/blocks/<plush>.json
data/<modid>/recipe/<plush>.json

See Plush Resources for the resource setup reference.

Related Pages

• Plush Resources
• Shared Tags
• Resource Conventions
• Troubleshooting