Modular Toasts API

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