Developer API

MasuHolograms provides a Java API for other mods to create, manage, and interact with holograms programmatically.

Getting the API

Singleton Access

MasuHologramsAPI api = MasuHologramsAPI.get();

HologramManager hologramManager = api.getHologramManager();
AnimationManager animationManager = api.getAnimationManager();
PlaceholderManager placeholderManager = api.getPlaceholderManager();

Static Convenience Methods (MHAPI)

import com.masuary.masuholograms.api.MHAPI;

The MHAPI class provides static methods for common operations.

Creating Holograms

Basic Creation

// Create at a position with default content
Hologram hologram = MHAPI.createHologram("my_hologram", serverLevel, new Vec3(100.5, 65.0, -200.5));

// Create with initial lines
Hologram hologram = MHAPI.createHologram("my_hologram", serverLevel, position,
    "&6Welcome!",
    "&7Line two",
    "#ICON:DIAMOND"
);

Deleting Holograms

MHAPI.deleteHologram("my_hologram");

Getting Existing Holograms

Hologram hologram = MHAPI.getHologram("my_hologram");
if (hologram != null) {
    // hologram exists
}

Managing Lines

Hologram hologram = MHAPI.getHologram("my_hologram");

// Add a line to page 0
MHAPI.addLine(hologram, 0, "&aNew line content");

// Set line content (page 0, line 0)
MHAPI.setLine(hologram, 0, 0, "&bUpdated content");

// Remove a line (page 0, line 2)
MHAPI.removeLine(hologram, 0, 2);

Managing Pages

// Add a new empty page
MHAPI.addPage(hologram);

Moving Holograms

MHAPI.moveHologram(hologram, serverLevel, new Vec3(200.5, 70.0, -100.5));

Custom Placeholders

Register custom placeholders that can be used in any hologram:

PlaceholderManager placeholderManager = MasuHologramsAPI.get().getPlaceholderManager();

// Simple placeholder
placeholderManager.register("my_placeholder", (player, argument) -> {
    return "Hello, " + player.getGameProfile().getName();
});

// Placeholder with argument support
placeholderManager.register("my_data", (player, argument) -> {
    if ("score".equals(argument)) {
        return String.valueOf(getPlayerScore(player));
    }
    return "unknown";
});

Usage in holograms:

{my_placeholder}          → "Hello, Steve"
{my_data:score}           → "42"

Unregistering Placeholders

placeholderManager.unregister("my_placeholder");

Custom Click Actions

Register custom action types:

ActionType.register("MY_ACTION", (player, args) -> {
    // args = everything after "MY_ACTION:"
    // Return true to continue action chain, false to stop
    doSomething(player, args);
    return true;
});

Usage in commands:

/mh page addaction myHolo 1 RIGHT MY_ACTION:some_argument

Events

MasuHolograms fires Forge events that you can listen to:

HologramClickEvent

Fired when a player clicks on a hologram page. Cancellable.

@SubscribeEvent
public void onHologramClick(HologramClickEvent event) {
    ServerPlayer player = event.getPlayer();
    Hologram hologram = event.getHologram();
    HologramPage page = event.getPage();
    ClickType clickType = event.getClickType();

    // Cancel to prevent default actions from running
    if (someCondition) {
        event.setCanceled(true);
    }
}

HologramRegisterEvent

Fired when a hologram is registered with the manager.

@SubscribeEvent
public void onHologramRegister(HologramRegisterEvent event) {
    Hologram hologram = event.getHologram();
    // React to new hologram creation
}

HologramUnregisterEvent

Fired when a hologram is unregistered (deleted).

@SubscribeEvent
public void onHologramUnregister(HologramUnregisterEvent event) {
    Hologram hologram = event.getHologram();
    // Clean up related data
}

Dependency Setup

To use MasuHolograms as a dependency in your mod:

build.gradle

dependencies {
    compileOnly files('libs/masuholograms-x.x.x.jar')
}

Optional Dependency (Recommended)

Make your mod work with or without MasuHolograms:

// Check if MasuHolograms is loaded
if (ModList.get().isLoaded("masuholograms")) {
    // Safe to use MasuHolograms API
    MyHologramCompat.register();
}

Put all MasuHolograms API calls in a separate class to avoid ClassNotFoundException when the mod isn't present:

public class MyHologramCompat {
    public static void register() {
        PlaceholderManager pm = MasuHologramsAPI.get().getPlaceholderManager();
        pm.register("my_stat", (player, arg) -> getStatValue(player));
    }
}

Thread Safety Notes

• Hologram operations should be performed on the server thread
• Placeholder resolve functions are called on the server thread during tick updates
• Action handlers are called on the netty thread (from packet handling) — schedule to main thread if needed
• HologramManager uses concurrent collections for thread-safe access