Skip to content

Portable item definitions

Class-based portable items keep item behavior in recognizable item classes while the SDK owns loader registration and event wiring. A definition is ordinary Java 17 and does not extend a Minecraft or loader class:

public final class WrenchItem implements PortableItem {
    private static final ItemDataKey<Integer> USES = ItemDataKey.integer(
            ResourceId.parse("example:uses"), 0, 1_000_000);

    @Override
    public void configure(ItemSpec.Builder properties) {
        properties.maxStackSize(1)
                .durability(256)
                .repairItem(ResourceId.parse("minecraft:iron_ingot"))
                .data(USES)
                .tooltip("tooltip.example.wrench.summary")
                .shiftHint("tooltip.example.hold_shift")
                .shiftTooltip("tooltip.example.wrench.details");
    }

    @Override
    public void onUseOnBlock(ModContext context, InteractionEvent event) {
        MutableItemData data = event.itemData().orElseThrow();
        int uses = data.getOrDefault(USES, 0) + 1;
        data.set(USES, uses);
        MutableItemStack stack = event.itemStack().orElseThrow();
        if (!event.creativeMode()) {
            stack.damage(1);
        }
        context.players().actionBar(event.playerId(),
                "Wrench uses: " + uses + ", durability: " + stack.remainingDurability());
        event.handle();
    }
}

Register it without a terminal build() call:

private static final Registration.Items ITEMS = Registration.items(MOD_ID);
public static final ItemRef WRENCH = ITEMS.item("wrench", WrenchItem::new);

public static void register(ModContext context) {
    Registration.register(context, ITEMS);
}

The factory runs once during registration preflight. configure runs before optional registration-site overrides, so a registry class can deliberately adjust a reusable definition:

ITEMS.item("reinforced_wrench", WrenchItem::new,
        properties -> properties.durability(512));

The SDK routes unhandled server-side right-click-item and use-on-block events on all supported targets. onUseOnBlock receives the exact block location, held item, main/off-hand identity and crouching state through the interaction event. It runs before the target portable block callback; leaving the event untouched allows block and native fallback behavior to continue.

Minecraft predicts interactions on the client before the authoritative server callback. When a portable item is known to handle a particular target, declare that lightweight decision separately so the client does not send a second vanilla item-use action:

@Override
public InteractionPrediction predictUseOnBlock(InteractionEvent event) {
    return event.target().equals(CONFIGURABLE_BLOCK.id())
            ? InteractionPrediction.HANDLE : InteractionPrediction.PASS;
}

Prediction receives only the portable event and must not change game state. HANDLE suppresses vanilla fallback, CANCEL rejects the predicted action, and PASS preserves normal block/item/other-mod behavior. The SDK still runs onUseOnBlock only on the server.

itemStack() is a safe view of the real held stack. It exposes count, stack limit, damage, maximum and remaining durability, plus server-only damage, repair, and consume operations. Negative mutations are rejected, repairs clamp at zero damage, consumption clamps at the current count, and durability damage reports whether the item broke. creativeMode() lets a definition follow vanilla-style no-cost creative use. These deterministic operations do not roll Unbreaking automatically; call them only after the portable action has actually succeeded.

Durable items may declare one anvil repair source with either repairItem(ResourceId) for one exact item or repairTag(ResourceId) for every item in a vanilla or modded item tag. A tag is the portable way to accept several repair materials. Declaring both, declaring either one more than once, or adding a repair source to a non-durable item fails during registration. The bridge uses the native repair-item hook on 1.20.1/1.21.1 and the native repairable item component on 1.21.4 and newer targets; portable mod code remains identical.

Tooltip lines can be literal or translated, coloured, and shown always, while Shift is held, while Shift is not held, or only with advanced tooltips. The short builder methods above cover the common translated Shift pattern; use tooltip(TooltipLine) for full control.

Portable stack data supports bounded strings, booleans, integers, longs and doubles. Every key must be declared with properties.data(key). Undeclared or differently bounded keys fail instead of silently writing arbitrary data. Interaction callbacks receive the actual held stack and may mutate it only on the server. The bridge stores the data under an SDK-owned compound in legacy item NBT on 1.20.1 and vanilla CUSTOM_DATA on component-era targets. Minecraft therefore copies, saves, drops and synchronizes it as part of the normal item stack.

For serverbound editors, never trust a native inventory index and mutate it directly. Use a logical PlayerInventorySlot, the expected ItemRef, and the player manager:

PlayerInventorySlot slot = PlayerInventorySlot.carried(packet.slot());
boolean updated = context.players().updateItemData(playerId, slot, LETTER, data -> {
    data.set(LETTER_TEXT, packet.text());
    data.set(LETTER_AUTHOR, playerName);
});

Slots are expressed as hotbar 0-8, main inventory 0-26, or off-hand; armor is not silently addressable. The native bridge rechecks the online player, server thread, actual slot item and expected registered item before exposing its declared keys. A stale packet therefore returns false rather than writing to whatever item replaced the editor's original stack. itemData(...) provides the matching typed read path.

Portable menus can now own the editable screen as well. Declare bounded fields directly in the menu layout; no client entrypoint, packet class, native widget, or loader-specific screen registration is needed:

MenuRef editor = context.menus().register("letter_editor",
        MenuSpec.builder("Letter")
                .size(230, 190)
                .textInput(MenuTextInput.multiline(
                        "letter.text", "Write...", 15, 35, 200, 100, 288, 16))
                .button(MenuButton.of("save", "Save", 15, 150, 60))
                .build(), action -> {
                    context.players().updateItemData(action.playerId(), slotFrom(action.state()),
                            LETTER, data -> data.set(LETTER_TEXT, action.input("letter.text")));
                    action.close();
                });

Drafts remain on the client until a declared action is pressed. The runtime sends every declared field together, then validates the active session, action, exact field set, Unicode code-point limit, UTF-8 byte limit, single/multiline policy and line count before calling consumer code. Slot identity still belongs in server-owned MenuState; never accept it from an editable field. The persistent preview's /enderfall_letter_edit command demonstrates Save, Sign, Cancel, reopening existing text and stale-slot rejection. Live copy/drop/reconnect acceptance remains a manual gameplay check.