EliteHolographics 是一款基于 Spigot/Paper API 构建的现代高性能 Minecraft 服务器插件。与依赖隐形盔甲架和包操纵的传统全息图插件不同,本插件利用 Minecraft 1.19.4 引入的原生 TextDisplay(文本显示)和 Interaction(交互)实体。
架构亮点
- 原生渲染: 通过利用
TextDisplay 实体,该插件将渲染开销完全转移至客户端。这极大地减少了服务器端的实体更新和延迟。
- 现代文本引擎: 全面集成 Kyori Adventure API 和 MiniMessage。这使得服务器管理员可以使用高级格式设置,包括 RGB 渐变、十六进制颜色、悬停事件以及清晰的字体样式。
- 智能区块与世界管理: 监听区块和世界加载事件以动态管理实体生命周期。当区块卸载/加载时,它会自动清理或重生显示内容,防止出现“幽灵实体”或重复的全息图。
- 异步友好任务: 动画缩放和占位符解析通过计划的 Bukkit 任务处理,防止主线程阻塞。
要求
要成功运行此插件,您的服务器环境必须满足以下条件:
- 服务器平台: Paper (推荐使用 Paper,因为它们原生捆绑了本代码中使用的 Kyori Adventure 库)。
- Minecraft 版本: Minecraft 1.21 或更高版本(需要支持
TextDisplay 和 Interaction 实体)。
- Java 版本: Java 21 或更高版本。
可选依赖项
- PlaceholderAPI (PAPI): 如果存在,插件会自动钩入它以允许实时更新服务器占位符。
⚠️ 关于 PAPI 的技术说明: 插件在解析占位符时会传递一个 null 玩家对象(PlaceholderAPI.setPlaceholders(null, text))。这意味着只有全局占位符(例如 %server_tps%、%server_online%)能正确显示。玩家特定的占位符(例如 %player_name%)不支持在全息图文本本身中显示,尽管 {player} 支持在交互式点击动作内部使用。
核心功能
1. 高级文本格式设置 (MiniMessage)
不再需要尴尬的 &c 或 §e 颜色代码。该插件原生解释 MiniMessage。例如,将一行设置为:
"<gradient:gold:yellow>✦ Welcome to the Server ✦</gradient>" 将呈现平滑的颜色过渡。
2. 实时动画
该插件包含一个 AnimationManager,它从 plugins/EliteHolographics/animations/ 文件夹读取自定义配置。
- 动画通过 YAML 文件逐帧配置。
- 您可以定义自定义刻度间隔(例如
interval: 10 表示每秒两次)。
- 插件会在原地平滑地循环这些帧,而无需完全重新创建实体。
3. 交互性与点击动作
当全息图切换为交互模式时,插件会计算其确切的物理边界框(lines * 0.28f + 0.15f)并覆盖一个不可见的 Interaction 实体。当玩家右键单击此空间时,它会触发一系列动作,并带有 500 毫秒的反垃圾邮件冷却时间。支持的动作为:
COMMAND:强制玩家执行命令。
CONSOLE:通过服务器控制台执行命令。
MESSAGE:向点击的玩家发送私有的、格式化后的 MiniMessage。
BROADCAST:向服务器上的所有人发送格式化后的 MiniMessage。
4. 布局自定义
- 广告牌模式(默认): 全息图会自动旋转以完美地从任何方向面向玩家(
Billboard.CENTER)。
- 静态模式: 将面板锁定到固定方向(
north、south、east、west),使其看起来像平面墙壁显示器或告示牌。
- 自定义背景: 可以完全打开/关闭背景框,或使用十六进制代码进行着色(例如
#FF6600)。
命令参考与权限
所有操作均通过基础命令 /holo 运行。
管理命令
| 命令 |
描述 |
权限 |
/holo list |
列出服务器上创建的所有全息图。 |
elite.holo.use |
/holo info <name> |
预览全息图的行数和内部数据属性。 |
elite.holo.use |
/holo near [radius] |
查找特定半径内的所有全息图。 |
elite.holo.use |
/holo create <name> [text] |
在当前坐标生成新的全息图。 |
elite.holo.create |
/holo delete <name> |
永久移除全息图及其条目。 |
elite.holo.delete |
/holo reload |
清除所有活动任务,重新加载文件并重生实体。 |
elite.holo.reload |
修改命令
| 命令 |
描述 |
权限 |
/holo addline <name> <text> |
在全息图底部追加新的一行。 |
elite.holo.edit |
/holo edit <name> <line#> <text> |
替换现有行号的文本。 |
elite.holo.edit |
/holo removeline <name> <line#> |
移除一行。(将阻止移除最后一行)。 |
elite.holo.edit |
/holo insertline <name> <line#> <text> |
在特定索引处插入文本,将其他行向下推。 |
elite.holo.edit |
/holo placeatme <name> |
将全息图直接传送到你当前的位置。 |
elite.holo.move |
/holo move <name> <x> <y> <z> |
将全息图移动到特定坐标。支持相对坐标 ~。 |
elite.holo.move |
外观与显示选项
| 命令 |
描述 |
权限 |
/holo static <north|south|east|west> <name> |
将全息图旋转锁定到固定的方位墙方向。 |
elite.holo.edit |
/holo bg <name> <on|off|reset> |
切换或重置原生的黑色半透明背景框。 |
elite.holo.edit |
/holo bgc <name> <#RRGGBB> |
恢复背景并使用十六进制代码为其着色。 |
elite.holo.edit |
/holo papi <name> <on|off> |
决定全局 PAPI 占位符是否每秒刷新。 |
elite.holo.edit |
交互命令
| 命令 |
描述 |
权限 |
/holo interactive <name> |
开启或关闭右键点击功能。 |
elite.holo.edit |
/holo actions <name> |
显示现有点击动作的编号配置列表。 |
elite.holo.use |
/holo addaction <name> <TYPE> <val> |
绑定执行 COMMAND、CONSOLE、MESSAGE 或 BROADCAST。 |
elite.holo.edit |
/holo removeaction <name> <index> |
根据列表索引号移除特定的动作脚本。 |
elite.holo.edit |
/holo clearactions <name> |
清除所有已配置的点击脚本并关闭交互功能。 |
elite.holo.edit |
动画引擎命令
| 命令 |
描述 |
权限 |
/holo listanim |
列出系统中所有已解析的动画配置。 |
elite.holo.use |
/holo newanim <name> |
在插件目录中生成一个模板动画 YAML 文件。 |
elite.holo.create |
/holo createanim <name> <anim> |
创建一个直接绑定到基于文件的循环的新全息图。 |
elite.holo.create |
/holo setanim <name> <anim> |
将静态全息图升级为运行特定的基于文件的循环。 |
elite.holo.edit |
/holo removeanim <name> |
从全息图上移除动画,使其恢复为静态文本。 |
elite.holo.edit |
文件结构与使用指南
存储的全息图 (holos.yml)
全息图以扁平化形式保存在 plugins/EliteHolographics/holos.yml 中。以下是插件代码生成的示例布局:
holos:
spawn_welcome:
world: world
x: 100.5
y: 64.0
z: -200.5
lines:
- "<gradient:gold:yellow>⭐ WELCOME TO ELITE MC ⭐</gradient>"
- "<gray>Players Online: <aqua>%server_online%</aqua></gray>"
isStatic: false
yaw: 0.0
showBackground: true
papiRefresh: true
interactive: true
actions:
- "MESSAGE:<green>You clicked the server info board!"
- "CONSOLE:eco give {player} 10"
创建动画
- 要构建动画,请运行
/holo newanim pulse。这会在 plugins/EliteHolographics/animations/pulse.yml 中生成一个清晰的布局模板。您可以打开此文件并配置帧循环,如下所示:
interval: 10
frames:
- - "<red>●</red> <white>Server Feature</white>"
- "<gray>Click here to learn more!</gray>"
- - "<gold>●</gold> <white>Server Feature</white>"
- "<yellow>Click here to learn more!</yellow>"
编辑完成后,输入 /holo reload 将其加载到内存中,然后通过 /holo setanim <hologram_name> pulse 将其附加到您的显示对象上。
EliteHolographics is a modern, high-performance Minecraft server plugin built using the Spigot/Paper API. Unlike legacy hologram plugins that rely on invisible armor stands and packet manipulation, this plugin utilizes native TextDisplay and Interaction entities (introduced in Minecraft 1.19.4).
Architectural Highlights
- Native Rendering: By leveraging
TextDisplay entities, the plugin shifts the rendering overhead entirely to the client. This dramatically reduces server-side entity ticking and lag.
- Modern Text Engine: Fully integrates the Kyori Adventure API and MiniMessage. This allows server administrators to use advanced formatting, including RGB gradients, hex colors, hover events, and clean font styles.
- Smart Chunk & World Management: Listens to chunk and world loading events to dynamically manage entity lifecycles. It automatically cleans up or respawns displays when chunks unload/load, preventing "ghost entities" or duplicated holograms.
- Asynchronous-Friendly Tasks: Animation scaling and placeholder parsing are handled via scheduled Bukkit tasks, preventing main-thread stalling.
Requirements
To run this plugin successfully, your server environment must meet the following criteria:
- Server Platform: Paper (Paper recommended as they natively bundle the Kyori Adventure libraries used in this code).
- Minecraft Version: Minecraft 1.21 or newer (Required for
TextDisplay and Interaction entity support).
- Java Version: Java 21 or higher.
Optional Dependencies
- PlaceholderAPI (PAPI): If present, the plugin automatically hooks into it to allow live-updating server placeholders.
⚠️ Technical Note on PAPI: The plugin passes a null player object when parsing placeholders (PlaceholderAPI.setPlaceholders(null, text)). This means only global placeholders (e.g., %server_tps%, %server_online%) will display properly. Player-specific placeholders (e.g., %player_name%) are not supported on the hologram text itself, though {player} is supported inside interactive click actions.
Core Features
1. Advanced Text Formatting (MiniMessage)
No more awkward &c or §e color codes. The plugin natively interprets MiniMessage. For example, setting a line to:
"<gradient:gold:yellow>✦ Welcome to the Server ✦</gradient>" will render a smooth color transition.
2. Live Animations
The plugin includes an AnimationManager that reads custom configurations from the plugins/EliteHolographics/animations/ folder.
- Animations are configured frame-by-frame via YAML files.
- You can define a custom tick interval (e.g.,
interval: 10 for twice per second).
- The plugin cycles through these frames smoothly in-place without needing to completely recreate the entity.
3. Interactivity & Click Actions
When a hologram is toggled to interactive, the plugin calculates its exact physical boundary box (lines * 0.28f + 0.15f) and overlays an invisible Interaction entity. When a player right-clicks this space, it triggers a chain of actions with a 500ms anti-spam cooldown. Supported actions:
COMMAND: Forces the player to run a command.
CONSOLE: Executes a command via the server console.
MESSAGE: Sends a private, formatted MiniMessage to the clicking player.
BROADCAST: Sends a formatted MiniMessage to everyone on the server.
4. Layout Customization
- Billboard Mode (Default): The hologram automatically rotates to face the player flawlessly from any direction (
Billboard.CENTER).
- Static Mode: Locks the panel to a fixed direction (
north, south, east, west) making it look like a flat wall display or sign.
- Custom Backgrounds: Background boxes can be toggled on/off completely or tinted using hexadecimal codes (e.g.,
#FF6600).
Command Reference & Permissions
All operations run through the base command /holo.
Management Commands
| Command |
Description |
Permission |
/holo list |
Lists all created holograms on the server. |
elite.holo.use |
/holo info <name> |
Previews a hologram's lines and internal data properties. |
elite.holo.use |
/holo near [radius] |
Locates all holograms within a specific radius. |
elite.holo.use |
/holo create <name> [text] |
Spawns a new hologram at your current coordinates. |
elite.holo.create |
/holo delete <name> |
Permanently removes a hologram and its entry from the file. |
elite.holo.delete |
/holo reload |
Clears all active tasks, reloads files, and re-spawns entities. |
elite.holo.reload |
Modification Commands
| Command |
Description |
Permission |
/holo addline <name> <text> |
Appends a brand new line to the bottom of the hologram. |
elite.holo.edit |
/holo edit <name> <line#> <text> |
Replaces the text of an existing line number. |
elite.holo.edit |
/holo removeline <name> <line#> |
Removes a line. (Will block removing the last remaining line). |
elite.holo.edit |
/holo insertline <name> <line#> <text> |
Inserts text at a specific index, pushing other lines down. |
elite.holo.edit |
/holo placeatme <name> |
Teleports a hologram directly to your current location. |
elite.holo.move |
/holo move <name> <x> <y> <z> |
Moves a hologram to specific coordinates. Supports relative ~. |
elite.holo.move |
Appearance & Display Options
| Command |
Description |
Permission |
/holo static <north|south|east|west> <name> |
Locks the hologram rotation to a fixed cardinal wall-direction. |
elite.holo.edit |
/holo bg <name> <on|off|reset> |
Toggles or resets the native black translucent background box. |
elite.holo.edit |
/holo bgc <name> <#RRGGBB> |
Restores background and colors it using a Hex code. |
elite.holo.edit |
/holo papi <name> <on|off> |
Dictates whether global PAPI placeholders refresh every second. |
elite.holo.edit |
Interactivity Commands
| Command |
Description |
Permission |
/holo interactive <name> |
Toggles right-click capabilities on or off. |
elite.holo.edit |
/holo actions <name> |
Displays a numbered configuration list of existing click actions. |
elite.holo.use |
/holo addaction <name> <TYPE> <val> |
Binds a COMMAND, CONSOLE, MESSAGE, or BROADCAST execution. |
elite.holo.edit |
/holo removeaction <name> <index> |
Removes a specific action script by its list index number. |
elite.holo.edit |
/holo clearactions <name> |
Wipes out all configured click scripts and turns off interactivity. |
elite.holo.edit |
Animation Engine Commands
| Command |
Description |
Permission |
/holo listanim |
Lists all parsed animation configurations available on the system. |
elite.holo.use |
/holo newanim <name> |
Generates a template animation YAML file in the plugin directory. |
elite.holo.create |
/holo createanim <name> <anim> |
Spawns a new hologram bound directly to a file-based loop. |
elite.holo.create |
/holo setanim <name> <anim> |
Upgrades a static hologram to run a specific file-based loop. |
elite.holo.edit |
/holo removeanim <name> |
Strips an animation off a hologram, reverting it to static text. |
elite.holo.edit |
File Structure & Usage Guide
Stored Holograms (holos.yml)
Holograms are flat-saved inside plugins/EliteHolographics/holos.yml. Here is an example layout generated by the plugin's code:
holos:
spawn_welcome:
world: world
x: 100.5
y: 64.0
z: -200.5
lines:
- "<gradient:gold:yellow>⭐ WELCOME TO ELITE MC ⭐</gradient>"
- "<gray>Players Online: <aqua>%server_online%</aqua></gray>"
isStatic: false
yaw: 0.0
showBackground: true
papiRefresh: true
interactive: true
actions:
- "MESSAGE:<green>You clicked the server info board!"
- "CONSOLE:eco give {player} 10"
Creating Animations
- To build an animation, run /holo newanim pulse. This produces a clean layout template inside plugins/EliteHolographics/animations/pulse.yml. You can open this file and configure frame cycles like this:
interval: 10
frames:
- - "<red>●</red> <white>Server Feature</white>"
- "<gray>Click here to learn more!</gray>"
- - "<gold>●</gold> <white>Server Feature</white>"
- "<yellow>Click here to learn more!</yellow>"
Once edited, type /holo reload to load it into memory, then attach it to your display via /holo setanim <hologram_name> pulse.
评论 0
登录后参与评分
还没有评论,来抢沙发吧