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();
Hologram hologram = api.getHologram("my_hologram");
Collection<Hologram> all = api.getHolograms();
The hologram and animation managers exist while a server is running (from ServerStartingEvent on); the placeholder manager exists for the whole lifetime of the mod.
Static Convenience Methods (MHAPI)
The MHAPI class provides static methods for common operations.
Creating Holograms
Basic Creation
// Create at a position with one empty page
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"
);
createHologram returns null when the name is already taken (names are case-insensitive) or starts with lectern_, which is reserved for lectern holograms. A new hologram is saved to config/masuholograms/holograms/ within a second.
Deleting Holograms
This removes the hologram from every viewer and deletes its file.
Getting Existing Holograms
Hologram hologram = MHAPI.getHologram("my_hologram");
if (hologram != null) {
// hologram exists
}
Collection<Hologram> all = MHAPI.getHolograms();
Managing Lines
Indices in the API are 0-based (the commands are 1-based).
Hologram hologram = MHAPI.getHologram("my_hologram");
// Add a line to page 0
MHAPI.addLine(hologram, 0, "&aNew line content");
// Insert a line at position 1 of page 0
MHAPI.insertLine(hologram, 0, 1, "&eInserted line");
// 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);
Replacing a Whole Page
To rebuild a page (for example a scoreboard), replace all its lines at once instead of removing and adding them one by one:
HologramPage page = hologram.getPage(0);
page.setLines(List.of("&6&lTop Players", "&e1. Steve", "&e2. Alex"));
Viewers see the new lines in one update.
Managing Pages
// Add a new empty page
HologramPage page = MHAPI.addPage(hologram);
// Remove page 1 (a hologram always keeps at least one page)
MHAPI.removePage(hologram, 1);
Moving Holograms
Showing Changes and Saving
- Changes made through the API reach current viewers by themselves, at most one update per hologram per tick.
createHologramandmoveHologrammark the hologram for saving. After other changes (lines, pages, actions, settings), callhologram.markDirty()so it is written within a second, or save it at once:
Saves are written by a background thread, crash-safe, and keep a .bak of the previous file. See Storage & Backups.
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:
- Names are case-insensitive. Registering an existing name replaces it.
- Registered placeholders stay registered for the lifetime of the mod:
/mh reloadand switching singleplayer worlds keep them, so registering once (for example at mod setup) is enough. - The function runs on the server thread, for each viewer on the hologram's update interval. Keep it fast.
- If it throws, the token is shown as written and the error is logged once per placeholder. If it throws a
LinkageError(for example a class of an optional mod is missing), the placeholder is turned off until restart.
Unregistering Placeholders
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:
Register your types at mod setup. A file that names a type nobody registered keeps the action as written: it does nothing (and lets the rest of the chain run) until the type is registered, and every save writes it back under the same type name. Action.hasRegisteredType() and Action.getTypeName() tell such actions apart; getType() returns ActionType.NONE for them. /mh page addaction refuses types that are not registered.
Events
MasuHolograms fires Forge events on MinecraftForge.EVENT_BUS. All of them are posted on the server thread.
HologramClickEvent
Fired when a player's click on a hologram counts (in reach, past the cooldown; see Click Actions) and the page being viewed has actions for some click type. Not fired for holograms with the DISABLE_ACTIONS flag. Cancellable.
@SubscribeEvent
public void onHologramClick(HologramClickEvent event) {
ServerPlayer player = event.getPlayer();
Hologram hologram = event.getHologram();
int pageIndex = event.getPageIndex(); // 0-based
ClickType clickType = event.getClickType();
// Cancel to prevent the page's actions from running
if (someCondition) {
event.setCanceled(true);
}
}
HologramRegisterEvent
Fired when a hologram is registered with the manager: when it is created (command, API or lectern), loaded at server start or /mh reload, cloned, or registered under its new name after a rename.
@SubscribeEvent
public void onHologramRegister(HologramRegisterEvent event) {
Hologram hologram = event.getHologram();
// React to new hologram creation
}
HologramUnregisterEvent
Fired when a hologram leaves the manager: when it is deleted, renamed (under its old name), and for every hologram on /mh reload and server stop (their files stay).
@SubscribeEvent
public void onHologramUnregister(HologramUnregisterEvent event) {
Hologram hologram = event.getHologram();
// Clean up related data
}
An exception thrown by a register or unregister listener is logged and does not stop the operation.
Dependency Setup
To use MasuHolograms as a dependency in your mod:
build.gradle
repositories {
maven { url 'https://cursemaven.com' }
}
dependencies {
// <file id>: the number at the end of the file's CurseForge page URL
compileOnly fg.deobf("curse.maven:masuholograms-1468611:<file id>")
}
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
- Create, change and delete holograms on the server thread only.
- Placeholder functions, click actions and all events run on the server thread.
- Only file writes happen on a background thread (
MasuHolograms-Save); the hologram is converted to JSON on the server thread before that.