Hologram API

You can find the source code for CMI-API, and download it as a .jar file from github.com/Zrips/CMI-API

Add to pom.yml

<dependency>
  <groupId>com.github.Zrips</groupId>
  <artifactId>CMI-API</artifactId>
  <version>9.8.6.4</version>
  <scope>provided</scope>
</dependency>
<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

Long Term Holograms

Holograms can be in two types, long term or quick ones. If you need to show simple information for short period then utilize quick type, as its optimized to be way more efficient in comparison to long term holograms which need to recalculate way more information before showing to the player to be more efficient in long term.

Creating simple hologram example

CMIHologram hologram = new CMIHologram("CustomHoloName", loc); 
CMIHologramPages pages = hologram.getPages();
pages.setLines(Arrays.asList("Line one", "Line Two", "ICON:Stone"));
hologram.show();

Different than quick holograms, when creating one you only need to provide its name (preferably unique one, or existing one with same name will be replaced with new one, but in that case you should get a record of existing hologram and modify it accordingly to be more efficient) and provide its starting location.
Hologram text lines are technically optional, but without any added there is nothing to be shown.
Calling show() method will trigger appropriate recalculations for this hologram, this include view and update ranges, so set those before triggering show method.
Holograms created by this method will be saved to the file by default, if you only want it to persist until server restart then you will need to disable saving into file with

hologram.getSettings().setSaveToFile(false);

Quick Holograms

In case you need quick and efficient hologram to be shown for single player for specified period use code as

new CMIHologram(@Player, @Location, @List<String>, @long);

or

CMIHologram.quickShow(playerReference, loc, lines, 50);

for example

List<String> lines = Arrays.asList("Line one", "Line Two", "ICON:Stone");
CMIHologram.quickShow(playerReference, loc, lines, 50);

which will show hologram with 3 lines, from which last one will be icon. It will show up at defined location for defined player, and it will disappear after 50 ticks on its own. No need to call anything else, everything is done automatically when you call this specific method/constructor

CMIHologramSettings baseSettings = hologram.getSettings();

Configuration methods for controlling hologram behavior, appearance, positioning, visibility, and persistence.

Billboard

baseSettings.setBillboard(@CMIBillboard);

Changes how the hologram rotates relative to the viewing player. Defaults to CENTER.

Scale

baseSettings.setScale(@CMIVector2D);

Changes the hologram’s display scale on the X and Y axes. Defaults to 1, 1.

Yaw

baseSettings.setYaw(double);

Sets the hologram’s horizontal rotation in degrees. Values are normalized to 0–360.

Pitch

baseSettings.setPitch(double);

Sets the hologram’s vertical rotation in degrees. Values are clamped between -90 and 90.

Direction

baseSettings.setDirection(@CMIVector3D);

Sets the hologram’s complete rotation direction using X, Y, and Z values.

Light Level

baseSettings.setLightLevel(@CMIVector2D);

Sets the hologram’s sky and block light levels. Defaults to 15, 15.

Sky Level

baseSettings.setSkyLevel(int);

Sets the hologram’s sky light level independently. Values correspond to the X component of the light level.

Block Level

baseSettings.setBlockLevel(int);

Sets the hologram’s block light level independently. Values correspond to the Y component of the light level.

Offset

baseSettings.setOffset(@CMIVector3D);

Moves the hologram relative to its center position. Defaults to 0, 0, 0.

Group

baseSettings.setGroup(String);

Assigns the hologram to a group. This can be used to associate or manage multiple holograms under the same group name.

Permission Requirement

baseSettings.setPermissionRequirement(boolean);

Determines whether viewing the hologram requires the appropriate permission. Defaults to false.

Save to File

baseSettings.setSaveToFile(boolean);

Determines whether the hologram is saved to the hologram data file. Defaults to true.

Line of Sight

baseSettings.setCheckLineOfSight(boolean);

Determines whether the hologram is only displayed when the player has a direct line of sight to it. Defaults to false.

Visibility Range

baseSettings.setVisibilityRange(int);

Sets the maximum distance at which the hologram is visible to players.

The value cannot be lower than the update range.

Update Range

baseSettings.setUpdateRange(int);

Sets the maximum distance at which the hologram is actively updated.

The value cannot be higher than the visibility range.

Update Interval

baseSettings.setUpdateIntervalTicks(int);

Sets how often the hologram is updated, measured in Minecraft ticks.

20 ticks = approximately 1 second. 0 allows updates without an interval delay.

CMIHologramTextSettings textSettings = hologram.getTextSettings();

Configuration methods for controlling the appearance and rendering behavior of text holograms.

Text Alignment

baseSettings.setTextAlignment(@CMITextAlignment);

Changes the horizontal alignment of the hologram text. Defaults to CENTER.

Background Color

baseSettings.setBackgroundColor(@CMIChatColor);

Changes the background color displayed behind the hologram text. Defaults to BLACK.

Background Alpha

baseSettings.setBackgroundAlpha(int);

Changes the transparency of the text background.

Values range from 0 to 255:

  • 0 = fully transparent
  • 255 = fully opaque

Defaults to 125.

Text Alpha

baseSettings.setTextAlpha(int);

Changes the transparency of the hologram text itself.

Values range from 0 to 255:

  • 0 = fully transparent
  • 255 = fully opaque

Defaults to 255.

Double Sided

baseSettings.setDoubleSided(boolean);

Determines whether the text is rendered from both the front and back sides. Defaults to false.

Shadowed

baseSettings.setShadowed(boolean);

Determines whether the hologram text has a shadow. Defaults to true.

See Through

baseSettings.setSeeThrough(boolean);

Determines whether the hologram text can be rendered through blocks and other objects. Defaults to false.

Line Width

baseSettings.setLineWidth(int);

Sets the maximum width of a text line before the text is wrapped onto another line.

Values are clamped between 1 and 10000. Defaults to 1000.

Filler Amount

baseSettings.setFillerAmount(int);

Sets the amount of filler space used when rendering text lines.

Values are clamped between 1 and 10000. Defaults to 245.

CMIHologramIconSettings iconSettings = hologram.getIconSettings();

Configuration methods for controlling the appearance, rotation, positioning, and billboard behavior of icon holograms.

Billboard

baseSettings.setBillboard(@CMIBillboard);

Changes how the icon rotates relative to the viewing player. Defaults to no billboard behavior (null) which then inherits its behavior from base billboard type.

Offset

baseSettings.setOffset(@CMIVector3D);

Moves the icon relative to its hologram position. Defaults to 0, 0, 0.

Scale

baseSettings.setScale(double);

Sets a uniform scale for the icon across the X, Y, and Z axes. Defaults to 1, 1, 1.

baseSettings.setScale(@CMIVector3D);

Sets the icon’s scale independently on the X, Y, and Z axes. Defaults to 1, 1, 1.

Direction

baseSettings.setDirection(@CMIVector3D);

Sets the icon’s complete rotation using X, Y, and Z values.

Pitch

baseSettings.setPitch(int);

Sets the icon’s vertical rotation in degrees.

Yaw

baseSettings.setYaw(int);

Sets the icon’s horizontal rotation in degrees.

Roll

baseSettings.setRoll(int);

Sets the icon’s rotation around its forward axis in degrees.

CMIHologramInteraction interactionSettings = hologram.getInteractionSettings();

Configuration methods for controlling hologram interaction areas, commands, hover/click effects, particle effects, and interaction-related text prefixes.

Commands

baseSettings.setCommands(@List<String>);

Adds commands to the hologram’s global interaction command list. These commands can be executed when interacting with the hologram.

The supplied commands are added to the existing command list rather than replacing it.

Interactable

baseSettings.setInteractable(boolean);

Determines whether the hologram can be interacted with by players. Defaults to false.

Interaction Dimensions

baseSettings.setDimensions(@CMIVector2D);

Sets the additional width and height of the hologram’s interaction area. Defaults to 0, 0.

Interaction Offset

baseSettings.setOffset(@CMIVector3D);

Moves the interaction area relative to the hologram’s position. Defaults to 0, 0, 0.

Particle Dimensions

baseSettings.setParticleDimensions(@CMIVector2D);

Sets the width and height of the area in which interaction particles are displayed. Defaults to 0, 0.

Particle Position

baseSettings.setParticlePosition(short);

Sets the position used for the particle effect. Defaults to 0.

Particle Spacing

baseSettings.setParticleSpacing(double);

Sets the spacing between individual particles when displaying the interaction particle effect. Defaults to 0.1.

Particle Count

baseSettings.setParticleCount(int);

Sets the number of particles displayed by the interaction effect.

Values are clamped between 0 and 2000. Defaults to 1.

Hover Effect

baseSettings.setHoverEffect(@CMIEffect);

Sets the complete particle effect displayed when the player hovers over the hologram.

baseSettings.setHoverEffect(@CMIParticle);

Sets the particle type used for the hover effect. The effect is initialized with an amount of 0 and speed of 1.

Defaults to SMALL_SMOKE.

Show Hover Particle

baseSettings.setShowHoverParticle(boolean);

Determines whether the particle effect is displayed while the player is hovering over the hologram. Defaults to true.

Particle Offset

baseSettings.setParticleOffset(@CMIVector3D);

Moves the interaction particles relative to the hologram’s position. Defaults to 0, 0, 0.

Show Click Particle

baseSettings.setShowClickParticle(boolean);

Determines whether the particle effect is displayed when the hologram is clicked. Defaults to true.

Base Prefix

baseSettings.setBasePrefix(String);

Sets the text prefix used for the hologram’s normal, non-hover state. Defaults to an empty string.

Hover Prefix

baseSettings.setHoverPrefix(String);

Sets the text prefix used when the player is hovering over the hologram. Defaults to an empty string.

CMIHologramAnimationSettings animationSettings = hologram.getAnimationSettings();

Configuration methods for controlling hologram fade animations and automatic rotation.

Fade In Animation

baseSettings.setFadeInAnimation(int);

Enables and sets the speed of the hologram’s fade-in animation.

Values are clamped between 0 and 600. A value of 0 disables the animation. Defaults to 0.

Fade Out Animation

baseSettings.setFadeOutAnimation(int);

Enables and sets the speed of the hologram’s fade-out animation.

Values are clamped between 0 and 600. A value of 0 disables the animation. Defaults to 0.

Auto Rotate

baseSettings.setAutoRotate(int);

Enables automatic rotation of the hologram and sets its rotation speed.

The value is normalized using a 1080-degree modulus. A value of 0 disables automatic rotation. Defaults to 0.

CMIHologramBoardSettings boardSettings = hologram.getBoardSettings();

Configuration methods for controlling the optional board behind a hologram, including its size, position, rotation, and material.

Enabled

baseSettings.setEnabled(boolean);

Enables or disables the hologram board. Defaults to false.

Extra Dimensions

baseSettings.setExtraDimensions(@CMIVector3D);

Sets the additional width, height, and depth of the board around the hologram. Dimensions are auto calculated based on input text, while these settings defines additional offset for precalculated size

The vector components represent:

  • X = extra width
  • Y = extra height
  • Z = extra depth

Defaults to 0, 0, 0.01.

Offset

baseSettings.setOffset(@CMIVector3D);

Moves the board relative to the hologram’s position. Defaults to 0, 0, 0.

Direction

baseSettings.setDirection(@CMIVector3D);

Sets the board’s rotation using X, Y, and Z direction values. Defaults to 0, 0, 0. Can only be rotated by 90 degree increments

Material

baseSettings.setMaterial(@CMIMaterial);

Sets the Minecraft material used to render the hologram board. Defaults to ACACIA_LOG.

AIR can also be used to effectively render the board without a visible material.

CMIHologramPageSettings pageSettings = hologram.getPageSettings();

Configuration methods for controlling hologram page rotation and automatic pagination.

Auto Pagination

baseSettings.setAutoPagination(boolean);

Enables or disables automatic switching between the hologram’s pages. Defaults to false.

Page Change Interval

baseSettings.setPageChangeIntervalTicks(int);

Sets how often the hologram automatically switches to the next page, measured in Minecraft ticks.

Values are clamped between 0 and 20000.

20 ticks = approximately 1 second.

Defaults to the interval configured by HologramManager.getDefaultpageChangeInterval().