API

#API

Read holograms, turn their pages, or create holograms of your own from code.

#Maven Repository

<repositories>
    <repository>
        <id>phoenixplugins</id>
        <url>https://repo.phoenixplugins.com/</url>
    </repository>
</repositories>

#Dependency

<dependency>
    <groupId>com.phoenixplugins.phoenixholograms</groupId>
    <artifactId>api</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

#Getting started

Add PhoenixHolograms to your plugin.yml so your plugin loads after it.

depend: [PhoenixHolograms]

PhoenixHologramsAPI.get() returns the service as an Optional, empty while the plugin is not enabled. Call it from the main thread.

PhoenixHologramsAPI.get().ifPresent(holograms -> holograms.setPage(player, "lobby", 2));

Method	Returns
getIdentifiers(), exists(String id)	The ids of every hologram, and whether one exists
getLocation(String id)	Where a hologram stands, as an Optional
getPage(Player, String id), getPageCount(String id)	The page a player sees, from 1, and how many pages there are
setPage(Player, String id, int page)	Shows a player a page, from 1
refresh(String id)	Redraws a hologram
isValidIdentifier(String id)	Whether an id is allowed
create(Plugin owner, String id, Location location)	A new hologram of your own, see below
attach(Plugin owner, String id, Entity entity, double x, double y, double z)	A new hologram of your own that follows an entity
getHandle(String id)	The handle of a hologram, as an Optional
remove(String id), removeAll(Plugin owner)	Removes one hologram, or every hologram your plugin made
createPersistent(String id, Location location)	A new saved hologram, the same as one made with /pholo create, see below
registerAction(String type, String syntax, HologramActionHandler handler)	Adds a click action type, see Custom Actions
unregisterAction(String type)	Removes an action type you added

#Holograms Made by Code

A hologram made with create or attach is never saved and never listed in the editor or /pholo list. It stays through /pholo reload and is removed when your plugin disables.

The returned HologramHandle changes it: setLines, setLine, setPages, setLocation, teleport, attachTo, attachToPlayer, detach, setHideFromTarget, setVisibleTo, setManualVisibility, setManualViewer, setViewDistance, setUpdateInterval, setScale, setBackground, setLeaderboard and remove. Lines take the same text as the editor, placeholders and tokens included.

setLocation redraws the hologram, while teleport slides it to the new spot and is cheap enough to call every tick. After setManualVisibility(true) only the players added with setManualViewer see the hologram, still within its view distance.

HologramHandle handle = holograms.create(this, "my_plugin_spawn", location);

handle.setLines(Arrays.asList("&6&lSpawn", "&7Welcome, %player%"));

setLeaderboard takes a LeaderboardSpec, built with LeaderboardSpec.builder(namePlaceholder, valuePlaceholder) and the same options as a leaderboard.

#Saved Holograms

createPersistent makes a hologram that belongs to the server rather than your plugin: it is saved to its own file, listed in the editor, and admins edit or delete it like any other. It takes the defaults of config.yml and needs a location in a loaded world. The returned handle fills it in, for example with a leaderboard.

#Custom Actions

A registered type shows in the editor's action builder with a single text field, and runs on hologram and line clicks like the built-in ones. The handler gets the hologram's id, the player and everything after the type. Return false to stop the actions after it.

holograms.registerAction("QUEST", "<quest>", (hologram, player, argument) -> quests.start(player, argument));

Unregister it in your onDisable. PhoenixCurrencies uses this for its currency actions.