Hycompanion Players Speech Bubbles Plugin

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

If you are looking for Speech Bubble for NPCs, use Hycompanion NPCs Speech Bubbles Plugin instead.

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. INSTALL THE PLUGIN FROM CURSEFORGE or Build the plugin:

   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:

# 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

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.

Usage

Basic API Usage

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

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:

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

SpeechBubbleOptions

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+

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:

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/hycompanion-speech-bubbles-players