🍞Overview

The Toasts module is a simple way of showing Toasts to the player.

Toasts created by this module are composed of a background format, a title, an optional message, and optional icon made of an image file or ItemStack, and an optional progress bar along the bottom.

Getting Started

The simplest way to get a message across is to use Toasts.INSTANCE.sendFromMod():

Toasts.INSTANCE.sendFromMod("jackfredlib", 
        Component.literal("Common code and hooks for JackFred's mods."))

This automatically grabs the icon and title from the given mod ID, adds the given message, and adds a timer and matching progress bar. You can see it in action in the above GIF.

Using the Builder

For anything more interesting, you can use the builder from ToastBuilder.builder(). This allows you to use custom images, progress bar mechanics and colours.

List<ItemStack> ironArmour = List.of(
        Items.IRON_HELMET.getDefaultInstance(),
        Items.IRON_CHESTPLATE.getDefaultInstance(),
        Items.IRON_LEGGINGS.getDefaultInstance(),
        Items.IRON_BOOTS.getDefaultInstance()
);

var items = ToastBuilder.builder(ToastFormat.DARK, Component.literal("New Armour!"))
        .addMessage(Component.literal("You have unlocked iron armour!"))
        .withIcon(ToastIcon.items(ironArmour))
        .progressShowsVisibleTime()
        .expiresAfter(4000L)
        .build();
        
Toasts.INSTANCE.send(items);

Built-in Formats

There are 4 built-in formats for toasts, recreating the 4 types used in the vanilla game. They are available under the ToastFormat class.

Progress Bars

Progress bars are shown at the bottom of the toast. Their values range between 0f and 1f, and can be used in 3 different ways:

1. As an indicator for how long the toast has left, as seen in the above two examples;E

2. Pushing progress values from outside, by using CustomToast.setProgress() on the built toast object;

3. Pulling progress values from the toast every frame, by using ToastBuilder.progressPuller().

Images

Toasts can optionally have images, supplied via ToastBuilder.withIcon(). There are built-in methods to create icons that display textures, items or lists of items in the ToastIcon class.

// shows a diamond as the icon
ToastBuilder.builder(ToastFormat.DARK, literal("with items"))
    .withIcon(ToastIcon.item(Items.DIAMOND.getDefaultInstance()))
    .build();
    
// make the item twice as large
ToastBuilder.builder(ToastFormat.DARK, literal("with items but bigger"))
    .withIcon(ToastIcon.item(Items.DIAMOND.getDefaultInstance(), 2))
    .build();
    
// an image under assets/mymod/image.png, with a size of 128x128px
// rendered on the toast at 20x20px
ResourceLocation image = ResourceLocation.fromNamespaceAndPath("mymod", "image.png");
ToastBuilder.builder(ToastFormat.DARK, literal("with image"))
    .withIcon(ToastIcon.image(image, 128, 128))
    .build();
    
// enlarge the image so it fits 3 slots
ToastBuilder.builder(ToastFormat.DARK, literal("with image but massive"))
    .withIcon(ToastIcon.image(image, 3, 128, 128))
    .build();
    
// grab a mod's icon from a mod ID
// no image will be shown if mod doesn't have a resolvable icon
ToastBuilder.builder(ToastFormat.DARK, literal("with mod icon"))
    .withIcon(ToastIcon.modIcon("emi"))
    .build();

It is also possible to implement the ToastIcon interface yourself if you so wish.

Expiry

By default, toasts expire after a given number of milliseconds (modified by the accessibility multiplier). However, if you want it to disappear based on other criteria you can use expiresWhenProgressComplete(). This will cause the given toast to expire when progress is set to 1.