For Developers

Filament provides an API and registry for custom item, block and decoration behaviours.

Behaviours can inherit ItemBehaviour, BlockBehaviour and DecorationBehaviour.

Custom behaviours can be registered using the BehaviourRegistry.

When referencing a custom behaviour in a config file you will have to specify the whole id of the behaviour, by default filament parses behaviours without namespace in the filament namespace.

You can check out TSA: Decorations for an example Decoration Behaviour implementation or one of the various built-in behaviours.

Example for the 'instrument' item-behaviour

public class Instrument implements ItemBehaviour<Instrument.Config> {
    private final Config config;

    public Instrument(Config config) {
        this.config = config;
    }

    @Override
    @NotNull
    public Instrument.Config getConfig() {
        return this.config;
    }

    @Override
    public InteractionResult use(Item item, Level level, Player player, InteractionHand interactionHand) {
        ItemStack itemStack = player.getItemInHand(interactionHand);

        player.startUsingItem(interactionHand);
        play(level, player, config);
        if (config.useDuration > 0) player.getCooldowns().addCooldown(itemStack, config.useDuration);

        player.awardStat(Stats.ITEM_USED.get(item));

        return InteractionResult.CONSUME;
    }

    private static void play(Level level, Player player, Config instrument) {
        float f = instrument.range / 25.0F;
        level.playSound(null, player, SoundEvent.createVariableRangeEvent(instrument.sound), SoundSource.RECORDS, f, 1.0F);
        level.gameEvent(GameEvent.INSTRUMENT_PLAY, player.position(), GameEvent.Context.of(player));
    }

    public static class Config {
        public ResourceLocation sound = null;

        public int range = 0;

        public int useDuration = 0;
    }
}

Registering it

public static final BehaviourType<Instrument, Instrument.Config> INSTRUMENT = registerBehaviour("instrument", Instrument.class);

private static <T extends Behaviour<E>,E> BehaviourType<T, E> registerBehaviour(String name, Class<T> type) {
    return BehaviourRegistry.registerBehaviour(ResourceLocation.fromNamespaceAndPath(MOD_ID, name), type);
}

Filament also provides methods to load config files and blockbench models from mods using mod-ids.

This is needed in case you want your datapack to work client-side without the player having reload resources, since resources are loaded with datapacks when loading a world, and clients load the assets in earlier than that.

Blockbench models require an additional identifier for the model which are used to reference it in the decoration config files later on

public class MyMod implements ModInitializer {
    @Override
    public void onInitialize() {
        FilamentLoader.loadModels("my-modid", "mynamespace");
        FilamentLoader.loadItems("my-modid");
        FilamentLoader.loadBlocks("my-modid");
        FilamentLoader.loadDecorations("my-modid");
        PolymerResourcePackUtils.addModAssets("my-modid");
        PolymerResourcePackUtils.markAsRequired();
    }
}