Utilities

Overview

Matthiesen Lib API provides several utility classes and abstractions to simplify common tasks in mod development. These utilities help reduce boilerplate code and provide cross-platform implementations.

ItemBuilder

The ItemBuilder class provides a fluent API for creating and modifying ItemStack instances with custom properties.

Basic Usage

import dev.matthiesen.common.matthiesen_lib_api.utility.ItemBuilder;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.Items;

ItemStack customItem = new ItemBuilder(Items.DIAMOND_SWORD)
    .setCustomName(Component.literal("Legendary Sword"))
    .addLore(new Component[] {
        Component.literal("A powerful weapon"),
        Component.literal("Deals extra damage")
    })
    .build();

Creating from Item

Create a new ItemStack from an Item:

ItemStack stack = new ItemBuilder(Items.GOLDEN_APPLE)
    .setCustomName(Component.literal("Enchanted Apple"))
    .build();

Creating from ItemStack

Modify an existing ItemStack:

ItemStack existingStack = new ItemStack(Items.BOOK);
ItemStack modified = new ItemBuilder(existingStack)
    .setCustomName(Component.literal("Spell Book"))
    .addLore(new Component[] {
        Component.literal("Contains ancient spells")
    })
    .build();

Available Methods

addLore(Component[] newLore)

Add lore (tooltip text) to the item:

new ItemBuilder(Items.DIAMOND)
    .addLore(new Component[] {
        Component.literal("A precious gem"),
        Component.literal("Very rare!")
    })
    .build();

Features:

• Appends to existing lore if any
• Automatically disables italic formatting
• Returns the builder for method chaining

setCustomData(CustomData data)

Set custom NBT data on the item:

import net.minecraft.nbt.CompoundTag;
import net.minecraft.world.item.component.CustomData;

CompoundTag tag = new CompoundTag();
tag.putString("owner", "PlayerName");
tag.putInt("power", 100);

new ItemBuilder(Items.STICK)
    .setCustomData(CustomData.of(tag))
    .build();

Features:

• Merges with existing custom data
• Sets max stack size to 1 automatically
• Returns the builder for method chaining

hideAdditionalTooltip()

Hide additional tooltip information:

new ItemBuilder(Items.DIAMOND_SWORD)
    .hideAdditionalTooltip()
    .build();

This hides enchantments, attributes, and other default tooltip information.

setCustomName(Component name)

Set a custom display name for the item:

new ItemBuilder(Items.IRON_SWORD)
    .setCustomName(Component.literal("Excalibur")
        .withStyle(ChatFormatting.GOLD, ChatFormatting.BOLD))
    .build();

setCustomModelData(int value)

Set custom model data for resource pack support:

new ItemBuilder(Items.STICK)
    .setCustomModelData(1)  // References custom model #1
    .build();

This is commonly used with resource packs to display different models for the same item.

build()

Finalize and return the ItemStack:

ItemStack result = new ItemBuilder(Items.DIAMOND)
    .setCustomName(Component.literal("Super Diamond"))
    .build();

Important: After calling build(), do not use the ItemBuilder instance anymore.

Complete Example

import dev.matthiesen.common.matthiesen_lib_api.utility.ItemBuilder;
import net.minecraft.ChatFormatting;
import net.minecraft.nbt.CompoundTag;
import net.minecraft.network.chat.Component;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.item.Items;
import net.minecraft.world.item.component.CustomData;

public class CustomItems {
    public static ItemStack createLegendarySword() {
        CompoundTag tag = new CompoundTag();
        tag.putString("tier", "legendary");
        tag.putInt("damage_bonus", 50);

        return new ItemBuilder(Items.DIAMOND_SWORD)
            .setCustomName(Component.literal("Dragonslayer")
                .withStyle(ChatFormatting.DARK_RED, ChatFormatting.BOLD))
            .addLore(new Component[] {
                Component.literal("Forged in dragon fire")
                    .withStyle(ChatFormatting.GRAY),
                Component.literal("+50 Damage")
                    .withStyle(ChatFormatting.RED),
                Component.literal("Legendary Tier")
                    .withStyle(ChatFormatting.GOLD)
            })
            .setCustomData(CustomData.of(tag))
            .setCustomModelData(1)
            .hideAdditionalTooltip()
            .build();
    }

    public static ItemStack createEnchantedBook() {
        return new ItemBuilder(Items.BOOK)
            .setCustomName(Component.literal("Ancient Tome")
                .withStyle(ChatFormatting.DARK_PURPLE))
            .addLore(new Component[] {
                Component.literal("Contains forbidden knowledge"),
                Component.literal("Use with caution")
                    .withStyle(ChatFormatting.ITALIC, ChatFormatting.RED)
            })
            .build();
    }
}

Universal Metrics

Matthiesen Lib API includes a utility for collecting and submitting metrics to faststats with a unified API that works across both Fabric and NeoForge. This allows mod developers to easily gather usage data and error reports from their mods without needing to implement separate solutions for each platform.

Getting Started

To enable metrics collection for your mod, simply include the matthiesen-lib-api dependency and follow the steps listed below to configure and use the metrics system. Metrics collection is opt-in, so you have full control over what data is collected and submitted.

Configuration

Create a new class file or include the following code in your main mod class to configure metrics:

import dev.matthiesen.common.matthiesen_lib_api.MatthiesenLibApi;
import dev.matthiesen.common.matthiesen_lib_api.core.MatthiesenLibApiMetricsManager;
import dev.matthiesen.common.matthiesen_lib_api.core.metric.UniversalMetricContext;
import dev.matthiesen.libs.faststats.ErrorTracker;
import dev.matthiesen.libs.faststats.Metrics;

public final class MetricManager {
    public static final ErrorTracker ERROR_TRACKER = MatthiesenLibApiMetricsManager.getErrorTracker();
    private static final UniversalMetricContext metricContext = MatthiesenLibApiMetricsManager.makeErrorMetricsContext(
            "MOD_ID", // Replace with your mod's ID
            "METRICS_TOKEN", // Replace with your faststats metrics token
            ERROR_TRACKER
    );

    public static void ready() {
        MatthiesenLibApi.registerModToMetrics(Constants.MOD_ID); // Optional: Register your mod with Matthiesen Lib API's metrics system
    }
}

After setting up the MetricManager, call MetricManager.ready() during your mod’s initialization to start the metrics system.

Metrics Configuration

Since this API clones the original faststats plugins/mods, you can customize your metricContext with additional options provided by the faststats library, which has been mirrored and re-packaged under the dev.matthiesen.libs.faststats package. This includes options for debug logging, additional metrics collection, error reporting, and more. Refer to the faststats documentation for more details on available features and configuration options.

Platform Utilities

Check if Mod is Loaded

Check if a specific mod is loaded:

import dev.matthiesen.common.matthiesen_lib_api.MatthiesenLibApi;

if (MatthiesenLibApi.isModLoaded("jei")) {
    // JEI is loaded, enable integration
}

if (MatthiesenLibApi.isModLoaded("create")) {
    // Create mod is loaded
}

Check Development Environment

Determine if running in a development environment:

import dev.matthiesen.common.matthiesen_lib_api.MatthiesenLibApi;

if (MatthiesenLibApi.isDevelopmentEnvironment()) {
    // Enable debug features
    enableDebugLogging();
}

This is useful for:

• Enabling extra logging in development
• Showing debug information
• Loading development-only features
• Testing and debugging

Best Practices

ItemBuilder

• Always call build() when finished
• Don’t reuse an ItemBuilder after calling build()
• Chain methods for cleaner code
• Use meaningful component styling

Platform Checks

• Check for mod compatibility early (during initialization)
• Use development checks to avoid debug code in production
• Cache the results of platform checks if used frequently