🍞Overview

Simple wrapper for making and sending toasts

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

Example toast being created, with automatically gathered information

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.

Minecraft has 5 slots available to any given toast, and a given toast can be up to 5 slots in height. Any toasts not able to immediately be placed on the screen will be queued until there is space.

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);

Toast cycling through a list of 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.

An example of all the shipped toast formats, and their vanilla uses.

It is possible to create your own formats with according text and progress bar colours; simply create your own instance of the ToastFormat record. However, for multi-version mods the format varies depending on the version you are targeting:

• For 1.20.2 and above, create a GUI sprite as normal, as seen here.

• For 1.20.1 and below, you will need to supply the sprite and UV information in the code, as seen here.

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.

Make sure you remember to complete the progress bar if this is the case, either through CustomToast.setProgress or ToastBuilder.progressPuller. Otherwise, they may never disappear off the user's screen.