Modular Toasts API

A lightweight, server-safe notification “toast” API for Forge mods. If you are a normal player download the jar WITHOUT "dev" in the name! 

Modular Toasts allows mods to display clean, in-game notifications with icons, sounds, stacking rules, tiered visuals, and mergeable behavior to prevent spam.

FOR PLAYERS

If a mod requires Modular Toasts API, install this mod alongside it.

This mod provides:
• Clean notification popups
• Optional item icons
• Optional sound effects
• Tier-based styling (Common, Rare, Epic)
• Smart stacking & priority handling
• Anti-spam merging
• Server-safe behavior

Installation (Client + Server)

Place this file in your mods folder:

modulartoasts-<version>.jar

Do NOT use the "dev" jar if you are not a developer!

Modpacks: use the normal jar!

If a mod depends on Modular Toasts API, it must be installed on:
• Client
• Dedicated Server (if applicable)

FOR DEVELOPERS

Github download for dev jar: ModularToastsAPI

Modular Toasts provides a simple API to create and send custom notifications.

Important: Two-Jar System

Because Minecraft uses mapped names in dev environments and obfuscated names in runtime, this project generates two jars:

• modulartoasts-<version>.jar → Player / Server jar
• modulartoasts-<version>-dev.jar → Development jar

Use the correct jar:

Development workspace → use the -dev.jar
CurseForge / modpacks / servers → use the normal jar

Using the player jar in a dev workspace will cause NoSuchFieldError crashes.

How To Add It To Your Mod (Without Maven)

Recommended Setup:

1. Place the development jar inside your mod:

YourMod
└── libs
  └── modulartoasts-<version>-dev.jar

1. In your build.gradle:

repositories
 flatDir { dir "libs" }

dependencies
 compileOnly fg.deobf(files("libs/modulartoasts-<version>-dev.jar"))
 runtimeOnly fg.deobf(files("libs/modulartoasts-<version>-dev.jar"))

1. Add dependency in your mods.toml:

[[dependencies.yourmodid]]
modId="modulartoasts"
mandatory=true
versionRange="[1.0.0,)"
ordering="NONE"
side="BOTH"

Developer Guidelines

Server-Side Safe Usage

Never call client-only classes from server logic.

When sending a notification from the server, use:

Network.sendNotification(ServerPlayer player, Notification notification)

The API handles delivery to the client safely.

Client-Only Usage

If you are already on the client thread:

NotificationQueue.enqueue(notification);

Thread Safety

Notifications must be sent from the main thread.

The network handler safely enqueues notifications on the client thread automatically.

Preventing Spam

For rapid events (XP, skills, ticks, etc.):

Use:
mergeable = true

This prevents flooding the UI.

Creating Notifications

Import:

import com.fishguy129.modulartoasts.api.Notifications;

Create a basic custom notification:

Notification n = Notifications.custom(
 "Quest Complete!",
 "You defeated the boss",
 null,
 new ItemStack(Items.DIAMOND),
 80,
 null,
 null,
 false
);

Send it to a player (recommended server → client):

Network.sendNotification(player, n);

Built-In Notification Presets

I recommend using the Custom preset, but here are some pre-built ones!

Skill Gain
Notifications.skillGain("Mining", 5, null);
• “Skill Up!”
• Short duration
• Mergeable

Loot Crate Spawn
Notifications.lootCrateSpawn("Supply Crate", null);
• “World Event” styling
• Epic tier visuals

Auction Sold
Notifications.auctionSold(itemStack, price, "$", null);
• Auto currency formatting
• Rare tier styling

Customization Options

Every notification supports:

Content
• Title
• Message
• Optional value line
• Optional ItemStack icon

Timing
• Custom duration (ticks)

Theme
• Default theme
• Fully custom ARGB colors
 Accent
 Background
 Title
 Text
 Outline

Sound
• Optional SoundEvent

Spam Control
• mergeable = true

Display Behavior
• Anchor position
• Max visible count
• Priority
• Stack or replace

Server Compatibility

• Safe on dedicated servers
• UI renders only on client
• Uses packets for server → client delivery

Why Use Modular Toasts?

• Cleaner than chat messages
• More immersive than actionbar spam
• Fully customizable
• Designed for mod interoperability
• Lightweight & API-focused

FAQ

Player Questions

What does this mod do?

Modular Toasts API adds a notification system used by other mods.
It does not add gameplay features by itself.

Do I need this on both client and server?

Yes — if a mod requires Modular Toasts API, it must be installed on both the client and the dedicated server.

I installed this and nothing changed.

That’s normal.
This is an API/library mod. It only shows notifications when another mod uses it.

Is this safe for servers?

Yes.
Modular Toasts is server-safe and does not load client-only classes on dedicated servers.

Does this affect performance?

No noticeable impact under normal usage.
Notifications are lightweight and only render when visible. Mods using this API should enable mergeable notifications for high-frequency events.

Developer Questions

Which jar do I use?

Use:

• modulartoasts-<version>-dev.jar → For development (/libs folder)
• modulartoasts-<version>.jar → For players and modpacks

Using the wrong jar in a dev environment will cause crashes.

Can I call the notification queue directly from server code?

No.

Server-side code must send notifications through the provided packet:

Network.sendNotification(ServerPlayer player, Notification notification)

Client-only queue usage should only happen on the client thread.

Is it safe to send notifications frequently?

Yes, but:

For rapid events (XP gain, skill ticks, etc.), set:

mergeable = true

This prevents UI flooding.

Can I fully customize colors?

Yes.

You can:
• Use the default RPG theme
• Provide a custom NotificationTheme
• Use customColors() to define:

• Accent color
• Background color
• Title color
• Text color
• Outline color

All colors use ARGB format.

Can I control where notifications appear?

Yes.

NotificationDisplay allows you to configure:
• Anchor position
• Maximum visible notifications
• Priority
• Stack or replace behavior

Does this mod work without networking?

No.

Notifications are designed to be safely sent from server → client using packets.
If you are already on the client, you may enqueue directly.

Can I make this an optional dependency?

Yes.

If your mod only enhances visuals when present:

mandatory=false
side="CLIENT"

If your mod requires it to function:

mandatory=true
side="BOTH"

Why do I get NoSuchFieldError in dev?

You are likely using the player (reobf) jar in a development workspace.

Use the -dev.jar for development.

Why does my server crash with client class errors?

This happens if:
• You directly reference client-only classes in server code
• Or you improperly install jars

Modular Toasts itself is server-safe when installed correctly.

Is this compatible with large modpacks?

Yes.

The API is lightweight and does not modify core mechanics.
It only renders UI elements on the client.

Want to cooperate to the cause?

Consider joining my Patreon! Even the free tier is massive support :)

Patreon