Bubble Anyway

Bubble Anyway

Bubble Anyway is an API-first information notification overlay for Minecraft.
Other mods can call the provided API directly from quest completion, machine
state changes, achievements, login events, or any other game event and display
clear, customizable message bubbles above most vanilla and modded GUI screens.
Commands and KubeJS are also available for integrations that do not need a
direct Java dependency.

Features

• Display multiple bubbles at the same time, with priority, replacement, IDs,
  and per-player clearing.
• Give other mods a direct Java API for player-specific, multi-player, and
  server-wide notifications without executing commands.
• Trigger bubbles from server events, commands, server-side APIs, KubeJS, or
  client-side KubeJS scripts.
• Render over most HUD and GUI screens through a high-priority overlay layer.
• Automatically size bubbles from their text, line breaks, wrapping, and item
  icons. Fixed minimum width and height are also supported.
• Use nine anchors: TOP_LEFT, CENTER_TOP, TOP_RIGHT, CENTER_LEFT,
  CENTER, CENTER_RIGHT, BOTTOM_LEFT, CENTER_BOTTOM, and BOTTOM_RIGHT.
• Use FADE or slide-in animations from the left, right, top, or bottom edge
  of the screen.
• Customize text color, size, alignment, bold, italic, underline, strikethrough,
  obfuscated text, shadow, wrapping, and line breaks.
• Add a Minecraft item icon with configurable size, gap, and independent X/Y
  offsets for both the icon and text.
• Use custom background colors or PNG textures with nine-slice scaling.
• Play a configurable sound when a bubble appears. The default is the vanilla
  button click sound.
• Define reusable themes so a server can send a theme ID and text instead of
  repeating every visual setting in each message.
• Include two built-in nine-slice backgrounds:
  bubble_anyway:textures/gui/background.png and
  bubble_anyway:textures/gui/background_modern.png.

API For Other Mods

Bubble Anyway is designed to be embedded by other mods. A mod can trigger a
bubble directly from its own Java event handlers without constructing a command
or requiring the player to interact with chat.

The common server entry point is:

import com.bubbleanyway.api.BubbleServerApi;

// Call this from a server-side event, such as quest completion.
BubbleServerApi.showJson(player,
    "{\"id\":\"quest_complete\",\"text\":\"Quest complete!\",\"priority\":100}");

// Use a local theme and only send the text when the style is predefined.
BubbleServerApi.showTheme(player, "my_mod:quest_notice", "Quest complete!");

Available server-side integration methods include:

• show(player, spec) and show(players, spec)
• showJson(player, json) and showJson(players, json)
• showAll(server, spec) and showAllJson(server, json)
• showTheme(player, themeId, text) and showThemeJson(player, themeId, overridesJson)
• showAllTheme(server, themeId, text) and showAllThemeJson(server, themeId, overridesJson)
• clear(player), clear(players), and clearAll(server)

These APIs allow an addon mod to decide when a notification appears while
Bubble Anyway handles layout, animation, text formatting, icons, sounds,
themes, and delivery to the client. Theme-based calls also avoid repeating a
large style JSON object for every event.

For KubeJS integrations, use BubbleKubeJSServerApi on the server or
BubbleKubeJSBindings on the client. This makes Bubble Anyway useful as a
shared notification service for quest, progression, economy, machine, and
content mods.

Supported Versions

All included targets are version 1.0.0. Install the file matching both your
Minecraft version and mod loader.

Command Example

/bubble show @a {"theme":"bubble_anyway:defualt","text":"Welcome to the server\nHave fun!"}

The legacy JSON form is also supported:

/bubble show @a {"text":"Server restart in 5 minutes","anchor":"CENTER_TOP","y":18,"animation":"SLIDE_FROM_TOP","duration":100,"priority":200}

Clear bubbles with:

/bubble clear

Client KubeJS

const BubbleAnyway = Java.loadClass('com.bubbleanyway.kubejs.BubbleKubeJSBindings');

BubbleAnyway.showJson(JSON.stringify({
  id: 'local_notice',
  theme: 'bubble_anyway:defualt',
  text: 'Client KubeJS is ready\nThis bubble is local only.'
}));

Client KubeJS bubbles do not require a server command or server event.

Server KubeJS

const BubbleServer = Java.loadClass('com.bubbleanyway.kubejs.BubbleKubeJSServerApi');

PlayerEvents.loggedIn(event => {
  BubbleServer.showJson(event.player, JSON.stringify({
    id: 'welcome',
    theme: 'bubble_anyway:defualt',
    text: 'Welcome back!'
  }));
});

Server-side calls send the notification to the selected player, a collection
of players, or everyone on the server.

JSON Example

{
  "id": "quest_complete",
  "theme": "bubble_anyway:morden",
  "text": "Quest complete!\nYou received a diamond.",
  "icon": "minecraft:diamond",
  "iconSize": 16,
  "iconGap": 6,
  "anchor": "CENTER_TOP",
  "y": 18,
  "animation": "SLIDE_FROM_TOP",
  "fadeIn": 8,
  "fadeOut": 12,
  "duration": 100,
  "priority": 100,
  "replace": true
}

When theme is present, unspecified fields are loaded from the local theme.
Explicit JSON fields override the theme for that bubble.

Themes

Default themes are copied to config/bubble_anyway/themes.json on first
startup. Existing user configuration is preserved. A theme can contain any
supported bubble field, so a complete theme only needs a theme ID and text at
call time.

Forge targets also support server data-pack themes and server-side theme
synchronization. Other loader targets use the packaged/client configuration
theme system.

Example configuration:

{
  "themes": {
    "my_mod:warning": {
      "textColor": "#FFFFFFFF",
      "backgroundColor": "#D9A83232",
      "padding": 10,
      "anchor": "CENTER_TOP",
      "y": 18,
      "animation": "SLIDE_FROM_TOP",
      "fadeIn": 8,
      "fadeOut": 12,
      "duration": 100,
      "priority": 200,
      "shadow": false
    }
  }
}

Use /reload on supported server configurations to reload theme data. The
client also reads local theme configuration without requiring the full theme
definition in every bubble packet.

Nine-Slice Backgrounds

Set background to a texture resource path and set backgroundBorder to the
edge size in pixels:

{
  "background": "bubble_anyway:textures/gui/background.png",
  "backgroundBorder": 8,
  "backgroundGuide": 1,
  "padding": 10
}

backgroundBorder keeps the four corners and four edge strips at their native
size while stretching only the center regions. backgroundGuide excludes
reference-line pixels from every slice and from the final rendering. This is
useful for a 66×66 source image containing 1-pixel guide lines between the
usable nine-slice regions.

Custom textures can be supplied by a resource pack or another mod. The PNG
resource must be available on the client.

Important Compatibility Note

Bubble Anyway is designed to render above normal HUD and GUI content. A mod
that draws directly after the overlay pass, replaces the screen framebuffer,
or uses a custom rendering pipeline can still draw over it. Such screens may
require loader- or mod-specific integration.

License

All Rights Reserved. See the repository license for usage permissions.