Hylograms

Hylograms

A powerful hologram plugin for Hytale servers with multi-line text, item displays, animations, and an easy-to-use API.

Note: Hytale nameplates currently do not expose rich text formatting for holograms, so color/style text formatting is not available yet. I tried to use Mixin and it wasn't happy :(

---

What Is New In 1.1

• Expanded developer API (lifecycle, interaction context, per-player runtime, image pipeline, stats)
• Per-player rendering improvements and lifecycle-safe spawn/despawn on world/player transitions
• Better interaction support (configurable hitbox, collision config, built-in action handlers)
• Resolution-aware image plane generation for image:<id> lines
• Runtime image asset hot-reload (/holo image reload)
• Runtime stats command (/holo stats)

---

Commands

All commands are under /hologram (alias: /holo).

Main

• /holo create <id> [--text="..."] [--temporary=true]
• /holo delete <id>
• /holo list
• /holo move <id>
• /holo teleport <id>
• /holo save
• /holo reload
• /holo respawn [id]
• /holo stats

Lines

• /holo addline <id> --text="..."
• /holo setline <id> <line> --text="..."
• /holo removeline <id> <line>
• /holo alignline <id> <line> --x=.. --y=.. --z=.. [--clear=true]

Visibility

• /holo visibility <hide|show|toggle|status>
• Alias: /holo vis <hide|show|toggle|status>

Interactions

• /holo interact <id> <line> <enable|disable> [--hint="..."] [--collision=SoftCollision] [--width=.. --height=.. --depth=..] [--action="..."]

Built-in action formats:

• player-command:<command>
• user-command:<command> (alias of player-command)
• console-command:<command>
• message:<text>

Images

• /holo image <reload|list|path>
• Alias: /holo images <reload|list|path>

Animations

• /holo anim list
• /holo anim create <name> [--loop=true] [--autoplay=false]
• /holo anim delete <name>
• /holo anim keyframe <name> <time> [--x=.. --y=.. --z=.. --pitch=.. --yaw=.. --roll=.. --scale=.. --easing=..]
• /holo anim assign <id> <line> <animation>
• /holo anim clear <id> <line>
• /holo anim play <id> <line>
• /holo anim stop <id> <line>

---

Core Features

• Persistent holograms in HylogramsFramework/holograms.json
• Persistent animation library in HylogramsFramework/animations.json
• Temporary holograms (persistent=false) that do not save to disk
• Text, item, block, entity/model, and image line support
• Per-line XYZ offsets (alignline)
• Per-line interactions with action callbacks
• Per-line animation assignment and runtime play/stop
• Optional PlaceholderAPI integration for per-player text rendering
• Per-player hide/show toggle
• Safe respawn/despawn flow on startup, world load/unload, and shutdown

---

Line Formats

• Text: Welcome to spawn
• Item: item:<itemId>[:scale[:pitch:yaw:roll]]
• Block: block:<blockTypeId>[:scale[:pitch:yaw:roll]]
• Entity/Model: entity:<modelId>[:scale[:pitch:yaw:roll]]
• Image: image:<imageId>[:scale[:pitch:yaw:roll]]

Notes:

• Rotation values are degrees.
• Scale defaults to 1.0.
• Invalid line assets fall back safely to readable text output.

---

Image Assets

Input folder:

• HylogramsFramework/images-input

Supported input:

• .png, .jpg, .jpeg (jpg/jpeg are converted to .png at runtime)

Generated output:

• HylogramsFramework/image-assets
• Mirrored live asset pack: mods/Hylograms

The plugin watches images-input and can hot-reload via:

• /holo image reload

---

Config

Configuration file:

• HylogramsFramework/config.properties

Main options:

• line-spacing
• item-spacing-factor
• text-line-interaction-y-offset
• autosave-on-change
• check-for-updates
• default-per-player-rendering
• placeholder-refresh-enabled
• placeholder-refresh-interval-seconds
• placeholder-refresh-max-holograms-per-run
• placeholder-refresh-only-when-placeholders
• debug

---

Permission Nodes

Core:

• hylograms.create
• hylograms.addline
• hylograms.setline
• hylograms.removeline
• hylograms.alignline
• hylograms.move
• hylograms.teleport
• hylograms.delete
• hylograms.list
• hylograms.stats
• hylograms.interact
• hylograms.save
• hylograms.reload
• hylograms.respawn
• hylograms.image

Animation:

• hylograms.anim.list
• hylograms.anim.create
• hylograms.anim.delete
• hylograms.anim.keyframe
• hylograms.anim.assign
• hylograms.anim.clear
• hylograms.anim.play
• hylograms.anim.stop

Update-notify admin checks (join notifications):

• *
• hylograms.*
• hylograms.admin
• hylograms.notifyupdates
• hylograms.reload

---

Developer API

Primary entrypoint:

• dev.ehko.hylograms.framework.api.HylogramsApi

Compatibility entrypoint:

• dev.ehko.hylograms.api.HologramsAPI

Main interface:

• dev.ehko.hylograms.framework.api.HylogramsDeveloperApi

Creating Holograms

import com.hypixel.hytale.math.vector.Vector3d;
import com.hypixel.hytale.math.vector.Vector3f;
import dev.ehko.hylograms.api.HologramsAPI;
import dev.ehko.hylograms.framework.api.HylogramsDeveloperApi;

HylogramsDeveloperApi api = HologramsAPI.get();

api.create(
    "shop",
    "overworld",
    new Vector3d(100, 65, 200),
    new Vector3f(0, 180, 0),
    "Welcome to the Shop!"
);

api.addLine("shop", "item:Items/Weapons/Sword_Iron");
api.addLine("shop", "Click to browse");
api.respawn("shop");

Modifying Holograms

import java.util.List;

HylogramsDeveloperApi api = HologramsAPI.get();

api.setLine("shop", 1, "Shop is OPEN!");
api.alignLine("shop", 2, 0.5, 0.0, 0.0);
api.setLines("shop", List.of(
    "Welcome to the Shop!",
    "item:Items/Weapons/Sword_Iron:1.3",
    "Best prices in town"
));

api.setLineInteractable(
    "shop",
    1,
    "Open Shop",
    1.8,
    0.9,
    0.8,
    "SoftCollision",
    "player-command:/shop"
);

api.respawn("shop");
api.saveNow();

Animations

import com.hypixel.hytale.math.vector.Vector3d;
import com.hypixel.hytale.math.vector.Vector3f;
import dev.ehko.hylograms.framework.animation.EasingType;
import dev.ehko.hylograms.framework.animation.Keyframe;

HylogramsDeveloperApi api = HologramsAPI.get();

api.createAnimation("spin", true, false);
api.addAnimationKeyframe("spin", new Keyframe(
    0.0f,
    new Vector3d(0, 0, 0),
    new Vector3f(0, 0, 0),
    1.0f,
    EasingType.LINEAR
));
api.addAnimationKeyframe("spin", new Keyframe(
    2.0f,
    new Vector3d(0, 0, 0),
    new Vector3f(0, 360, 0),
    1.0f,
    EasingType.LINEAR
));

api.assignLineAnimation("shop", 2, "spin");
api.playLineAnimation("shop", 2);

Utilities

HylogramsDeveloperApi api = HologramsAPI.get();

if (api.exists("shop")) {
    api.delete("shop");
}

api.list();                  // List<HologramDefinition>
api.listAnimations();        // List<AnimationData>
api.getStats();              // Runtime snapshot
api.respawnAllLoaded();      // Queue full respawn
api.reloadFromDiskAndRespawn();

Per-Player Runtime Controls

HylogramsDeveloperApi api = HologramsAPI.get();

// Queue periodic per-player placeholder refresh work
api.refreshPerPlayerHolograms(20, true);

Image Asset Controls

HylogramsDeveloperApi api = HologramsAPI.get();

if (api.isImageServiceAvailable()) {
    api.reloadImageAssets();
    api.listImageAssets();
    api.getImageInputDirectory();
}

---

Installation

1. Download the Hylograms plugin build.
2. Place it in your server mods/ folder.
3. Start or restart the server.
4. Configure HylogramsFramework/config.properties if needed.
5. Use /holo create ... to start building holograms.

---

Optional Dependency

Placeholder support target:

• HelpChat:PlaceholderAPI

When present, %placeholder% tokens can be resolved per player.