Players Speech Bubbles

A Hytale server plugin that automatically displays floating speech bubbles above players when they chat. Chat messages are shown as bubbles to nearby players (except the sender). There is also another plugin for NPCs.

Read Technical Details and Limitations.

Features

Automatic Chat Bubbles - When players chat, their message appears as a bubble above their head
Nearby Players Only - Bubbles are only shown to players within configured range
Sender Excluded - Players don't see their own bubble (they can still see their chat in the chat box)
Edge Clamping - Bubbles stay visible at screen edges when player is off-screen or behind camera
3D Positioning - Full 3D projection with pitch and yaw camera rotation support
Configurable Duration - Set how long bubbles remain visible
Styling Options - Customize text color, background opacity, and bubble offset
Chat Truncation - Long messages are automatically truncated to fit in bubbles
API for Other Plugins - Simple API for integration with other plugins

Installation

1. DOWNLOAD THE FILE HERE or Build the plugin yourself:

Code:

   compile-plugin.bat

1. Copy the generated JAR from target/hycompanion-speech-bubbles-players.jar to your Hytale server's mods/ folder

2. The plugin will create a default config.yml on first run

Configuration

Edit mods/dev.hycompanion_SpeechBubblesPlayers/config.yml:

Code:

# Speech Bubbles Players Configuration

# Default settings for speech bubbles
defaults:
  # Display duration in milliseconds
  duration: 5000
  # Maximum width in pixels (based on bubble image)
  maxWidth: 626
  # Maximum height in pixels (based on bubble image)
  maxHeight: 349
  # Text color (hex)
  textColor: "#FFFFFF"
  # Background opacity (0.0 - 1.0)
  backgroundOpacity: 0.9
  # Field of view for 3D projection (degrees)
  fov: 75.0
  # Offset above entity head in blocks (can be negative)
  headOffset: -0.75

# Maximum visibility distance in blocks (bubble won't show if entity is farther)
maxDistance: 25

# Maximum chat message length to display in bubble (longer messages are truncated)
maxChatLength: 150

# Cleanup interval in seconds
cleanupInterval: 30

Configuration Options

| Option |Default |Description |
| ----------------- |--------- |------------------------------------------------ |
| <code>duration</code> |5000 |Display duration in milliseconds |
| <code>maxWidth</code> |626 |Maximum bubble width in pixels |
| <code>maxHeight</code> |349 |Maximum bubble height in pixels |
| <code>textColor</code> |"#FFFFFF" |Text color in hex format |
| <code>backgroundOpacity</code> |0.9 |Background opacity (0.0-1.0) |
| <code>fov</code> |75.0 |Field of view for 3D projection (degrees) |
| <code>headOffset</code> |-0.75 |Vertical offset above entity head (blocks) |
| <code>maxDistance</code> |25 |Maximum visibility distance in blocks |
| <code>maxChatLength</code> |150 |Maximum characters to display from chat messages |
| <code>cleanupInterval</code> |30 |Cleanup task interval in seconds |

How It Works

When a player sends a chat message:

1. The plugin captures the PlayerChatEvent
2. It finds all other players within maxDistance blocks
3. For each nearby player, it displays a speech bubble above the sender's head
4. The sender does NOT see their own bubble
5. The bubble disappears automatically after duration milliseconds

Command messages (starting with /) are ignored.

Basic API Usage

Other plugins can also use the API to display speech bubbles:

Code:

import dev.hycompanion.speechbubblesplayers.api.SpeechBubbleAPI;
import dev.hycompanion.speechbubblesplayers.api.SpeechBubbleOptions;

// Show a simple speech bubble (5 second duration)
UUID playerUuid = ...;  // The player's entity UUID
UUID viewerUuid = ...;  // The viewer's UUID
SpeechBubbleAPI.showBubble(playerUuid, viewerUuid, "Hello, adventurer!");

// With custom duration (milliseconds)
SpeechBubbleAPI.showBubble(playerUuid, viewerUuid, "Welcome!", 6000);

// With full options
SpeechBubbleOptions options = new SpeechBubbleOptions()
    .duration(10000)
    .maxWidth(300)
    .textColor("#FFD700")
    .fov(90.0f);
SpeechBubbleAPI.showBubble(playerUuid, viewerUuid, "Check this out!", options);

// Show to all players
SpeechBubbleAPI.showBubbleToAll(playerUuid, "Hello everyone!");

Optional Dependency Pattern (Recommended)

For a truly optional dependency that doesn't require the plugin JAR at compile time, use reflection with Hytale's PluginManager:

Code:

import com.hypixel.hytale.common.plugin.PluginIdentifier;
import com.hypixel.hytale.server.core.HytaleServer;
import com.hypixel.hytale.server.core.plugin.PluginBase;
import com.hypixel.hytale.server.core.plugin.PluginManager;
import com.hypixel.hytale.server.core.plugin.PluginState;
import java.lang.reflect.Method;
import java.util.UUID;

public class SpeechBubblePlayersIntegration {

    private static final PluginIdentifier PLUGIN_ID =
        new PluginIdentifier("dev.hycompanion.speech", "SpeechBubblesPlayers");
    private static final String API_CLASS =
        "dev.hycompanion.speechbubblesplayers.api.SpeechBubbleAPI";

    private Method showBubbleMethod;
    private boolean available = false;

    public SpeechBubblePlayersIntegration() {
        detectPlugin();
    }

    private void detectPlugin() {
        try {
            PluginManager pm = HytaleServer.get().getPluginManager();
            PluginBase plugin = pm.getPlugin(PLUGIN_ID);

            if (plugin == null || plugin.getState() != PluginState.ENABLED) {
                return;
            }

            ClassLoader cl = plugin.getClass().getClassLoader();
            Class<?> apiClass = Class.forName(API_CLASS, true, cl);
            showBubbleMethod = apiClass.getMethod("showBubble",
                UUID.class, UUID.class, String.class, long.class);

            available = true;
        } catch (Exception e) {
            // Plugin not available
        }
    }

    public boolean isAvailable() {
        return available;
    }

    public void showBubble(UUID entityUuid, UUID playerUuid, String text, long durationMs) {
        if (!available || showBubbleMethod == null) {
            return;
        }
        try {
            showBubbleMethod.invoke(null, entityUuid, playerUuid, text, durationMs);
        } catch (Exception e) {
            // Ignore errors
        }
    }
}

API Reference

SpeechBubbleAPI

| Method |Description |
| ------------------------------------------ |------------------------------ |
| <code>isAvailable()</code> |Check if plugin is loaded |
| <code>showBubble(entity, player, text)</code> |Show simple bubble (5s) |
| <code>showBubble(entity, player, text, duration)</code> |Show with custom duration (ms) |
| <code>showBubble(entity, player, text, options)</code> |Show with full options |
| <code>showBubbleToAll(entity, text)</code> |Show to all players |
| <code>showBubbleToAll(entity, text, options)</code> |Show to all with options |
| <code>hideAllBubblesForPlayer(player)</code> |Hide all for player |
| <code>hideAllBubblesForEntity(entity)</code> |Hide all for entity |

#### SpeechBubbleOptions

| Method |Default |Description |
| ------------------- |------- |------------------------------- |
| <code>duration(ms)</code> |5000 |Display duration |
| <code>maxWidth(px)</code> |626 |Maximum width |
| <code>maxHeight(px)</code> |349 |Maximum height |
| <code>textColor(hex)</code> |#FFFFFF |Text color |
| <code>backgroundOpacity()</code> |0.9 |Background opacity (0.0-1.0) |
| <code>fov(degrees)</code> |75.0 |Field of view for 3D projection |

Technical Details and Limitations

FPS / TPS mode

The Speech Bubble Plugin works better in first person camera mode. Otherwise there is a drift in third person view. Will be fixed in next update.

Screen Resolution

The plugin uses 1920x1080 as a reference resolution. The Hytale UI system internally scales coordinates based on the client's actual resolution.

16:9 resolutions (1080p, 1440p, 4K): Work well with proportional scaling
Ultrawide (21:9): May be slightly off-center, but bubbles remain visible
Other aspect ratios: Half off-screen clamping ensures bubbles stay visible

Edge Clamping

When entities are off-screen or behind the camera:

Bubbles are clamped to screen edges
Half off-screen allowed: Up to 50% of the bubble can extend off-screen
When behind the camera, bubbles stick to the nearest edge

Compatibility with NPC Speech Bubbles

This plugin (SpeechBubblesPlayers) can run alongside the original NPC Speech Bubbles plugin (SpeechBubbles). They use different:

Package names: dev.hycompanion.speechbubblesplayers vs dev.hycompanion.speechbubbles
Plugin identifiers: SpeechBubblesPlayers vs SpeechBubbles
Config folders: dev.hycompanion_SpeechBubblesPlayers vs dev.hycompanion_SpeechBubbles

Building from Source

Requirements:

Java 25 (OpenJDK)
Maven 3.8+

Code:

cd hycompanion-speech-bubbles-players
mvn clean package
# JAR will be in target/hycompanion-speech-bubbles-players.jar

Troubleshooting

Bubbles Not Appearing

Check if plugin is loaded:

Code:

PluginManager pm = HytaleServer.get().getPluginManager();
PluginBase plugin = pm.getPlugin(new PluginIdentifier("dev.hycompanion.speech", "SpeechBubblesPlayers"));
System.out.println("Plugin state: " + (plugin != null ? plugin.getState() : "NOT FOUND"));

Bubble Position Too High/Low

Adjust headOffset in config:

Positive: Higher above head (e.g., 0.5)
Negative: Lower/closer to head (e.g., -0.5)

Messages Too Long

Adjust maxChatLength in config to truncate messages at a different point.

License

MIT License - See LICENSE file for details

Repository (Source Code)

[https://github.com/Ultdx/hycompanio...com/Ultdx/hycompanion-speech-bubbles-players)

Players Speech Bubbles v1.0.1

Overview History