{"url":"https://levimc.org/mods/github.com/Ieckseyr/HologramLib/","tooth":"github.com/Ieckseyr/HologramLib","name":"HologramLib","description":"前置库：基岩版协议层统一悬浮显示库 / Library: Bedrock protocol-layer unified hologram & display library","owner":"Ieckseyr","icon":"https://avatars.githubusercontent.com/Ieckseyr?s=144","repository":"https://github.com/Ieckseyr/HologramLib","issues":"https://github.com/Ieckseyr/HologramLib/issues","releases":"https://github.com/Ieckseyr/HologramLib/releases","stars":8,"updated":"2026-10-29T06:44:47Z","published":"2026-08-23T03:05:26Z","created":"2026-08-22T12:58:14Z","license":"MIT","categories":["library"],"platforms":["lse"],"lang":"js","env":["server"],"gameVersions":["1.26.51"],"tags":["type:mod","platform:levilamina","library","lse"],"latest":{"variant":"","version":"26.51.6","install":"lip install github.com/Ieckseyr/HologramLib@26.51.6"},"readmes":[{"file":"README.md","lang":"zh-Hans","text":"<div align=\"center\">\n  <img src=\"docs/assets/HologramLib.png\" alt=\"HologramLib — 基岩版协议层统一悬浮显示库\" width=\"100%\">\n</div>\n\n<!-- 文档站: https://ieckseyr.github.io/HologramLib/ —— 由 .github/workflows/docs.yml 从本仓库 docs/ 构建并发布 -->\n[中文](README.md) · [English](README.en.md) · [文档](https://ieckseyr.github.io/HologramLib/)\n\nHologramLib 是基岩版服务端（LeviLamina / BDS）的**协议层显示库**：用一套 API 把形状、悬浮字、物品、实体、菜单这些内容直接「塞」给客户端 —— 不生成真实实体、不写存档、不改服务端世界状态。\n\n同一套能力有两个入口：**C++ 插件**（冻结的纯虚接口）与 **LSE 脚本**（`ll.import`）。\n\n| | |\n|---|---|\n| 插件版本 | `26.51.6` |\n| API 版本 | `1.32.0`（`HOLOGLIB_API_VERSION 0x012600`） |\n| 运行平台 | LeviLamina 26.51 · BDS 1.26.51（协议 2193） |\n| 对外接口 | 唯一公开头 `include/hologramlib/HologramLib.h`（19 个接口 / 343 槽）+ LSE 命名空间 `HologramLib`（339 个导出）。26.51.6 新增：掉落物 `IItemActor`、表单关闭 `IFormControl`、方位条 `ILocatorBar`、隐身 `IPlayerVisibility` |\n| 脚本前置 | `lrca`（LegacyRemoteCall）；缺失时导出调用是安全空操作，C++ 接口不受影响 |\n| 许可 | MIT（悬浮字「动态行」重构自 Phantom，按 LGPL-3.0） |\n\n本库是**纯前置库**，不是功能插件：只提供渲染原语、协议封装与时机通知。命令、表单、权限、占位符、数据持久化一律留给消费方。\n\n## 更新日志\n完整更新日志请看\n[更新日志](docs/versions/changelog.md)。\n\n# <font size=24>完整文档请见</font>\n<font size=16>[HologramLib文档站](https://ieckseyr.github.io/HologramLib)</font>\n\n## 如何编写\n\n### C++ 插件\n\n```cp0\n#include \"hologramlib/HologramLib.h\"\n\n// 编译期门住所需能力域；运行期握手兜住「库被换成旧版」\nstatic_assert(HOLOGLIB_API_VERSION >= 0x011B00, \"需要 1.21.0 (ITradeMenu)\");\n\nauto& lib = hologramlib::IHologramLib::getInstance();\n\n// 悬浮字：整块一个文本形状，多行用 \\n 合并，行内颜色用 § 代码\nauto holo = lib.holograms().create(0, 70, 0);\nlib.holograms().addLine(holo, \"§e欢迎来到主城\");\nlib.holograms().addLine(holo, \"在线: {online}\");           // {var} 按观看者解析\nlib.holograms().setDepthTest(holo, true);                  // true = 被方块遮挡（默认穿墙可见）\nlib.holograms().draw(holo);\n\n// 形状：线 + 颜色 + 生命周期\nauto line = lib.shapes().createLine(0, 64, 0, 10, 64, 10);\nlib.shapes().setColor(line, 1.0f, 0.2f, 0.2f, 1.0f);\nlib.shapes().draw(line);\n\n// 虚拟容器：任何输入设备都能点的列表界面（点击 = 一次物品拾取）\nhologramlib::ContainerMenuSpec menu;\nmenu.title = \"§8任务列表\";\nmenu.rows  = 3;                                            // 3 = 27 格；6 = 54 格\nmenu.items.resize(27);\nmenu.items[0].type = \"minecraft:diamond_sword\";\nmenu.items[0].name = \"§b试炼\";\nauto menuId = lib.containerMenus().open(\"Steve\", menu);\nlib.containerMenus().setItem(menuId, 0, {\"minecraft:barrier\", 1, 0, \"§c已完成\", {}});\n```\n\nxmake 接入：\n\n```lua\nadd_includedirs(\"../HologramLib/include\")\nadd_linkdirs(\"../HologramLib/build/windows/x64/release\")\nadd_links(\"HologramLib\")\n```\n\n### LSE 脚本\n\n> LSE 标准接口（`mc` / `ll` / `logger` / 事件 / NBT / 表单 / 数据库…）见 [LSE 文档站](https://lse.levimc.org/zh/apis/)；这里只列 HologramLib 自己的命名空间。\n\n```js\n// 统一命名空间 \"HologramLib\"，16 个前缀分域\nconst holoCreate      = ll.import(\"HologramLib\", \"holoCreate\");\nconst containerOpen   = ll.import(\"HologramLib\", \"containerOpen\");\nconst sensingIsTouch  = ll.import(\"HologramLib\", \"sensingIsTouch\");\n\n// 按客户端设备分流：触屏走虚拟容器（点击必然发包）\nif (sensingIsTouch(\"Steve\")) {\n    const id = containerOpen(\"Steve\", \"§8任务列表\", 3);\n    // 点击在守护 / 定时里取（取走并清空）\n    for (const line of ll.import(\"HologramLib\", \"containerPollClicks\")()) {\n        // \"player=Steve menuId=1 slot=0 closed=0\"\n    }\n}\n```\n\n## 安装\n\nLip 安装（推荐）：\n\n```\nlip install github.com/Ieckseyr/HologramLib\n```\n\n手动安装：\n\n1. 关服。\n2. 解压发布包 `HologramLib.zip`，把得到的 `HologramLib` 文件夹整个放进服务端 `plugins/`，最终为 `plugins/HologramLib/`（内含 `HologramLib.dll`、`manifest.json`、`tooth.json`，以及脚本导入层 `lib/`）。\n3. 开服。启动顺序没有要求：库在 enable 期检测 LSE 兼容层，没检测到就在 `ServerStarted` 兜底重试。\n\n消费方插件只需在 `enable()` 里 `getInstance()`，不必声明前置依赖。\n\n正式产物完全静默：所有诊断日志编译期关闭，日志字符串不进二进制。排障时临时打开 `xmake f --holo_diag=y && xmake build -y`，发布前复位（`--holo_diag=n`）。\n\n\n## 版本\n\n| 编号 | 位置 | 用途 |\n|---|---|---|\n| 插件版本 | `manifest.json` 的 `version` | 部署用，与 git tag 同名（形如 `26.51.6`） |\n| API 版本 | 本文档上方的 `1.32.0` | 人读的能力版本 |\n| `HOLOGLIB_API_VERSION` | `include/hologramlib/HologramLib.h` | 代码里唯一的版本依据，`0x012600` |\n\n三者的完整对应表、编码规律，以及两次 API 收缩的原因，见 [版本与 ABI 对照](docs/versions/api-version-matrix.md)。\n\n## 许可\n\nMIT 许可（见 [LICENSE](LICENSE)）。\n\n悬浮字「动态行」实现（`FloatingTextLine` 的内容池 / 轮播间隔 / 行级变量开关、按间隔时间取模轮播、0.5s 节流刷新与逐玩家重发、内容去重）重构自 [Phantom](https://github.com/GroupMountain/Phantom)（LeviLamina 基岩版悬浮字插件，GNU Lesser General Public License v3.0）。\n\n依 LGPL-3.0 要求标注来源：该重构部分及其演绎作品按 LGPL-3.0 分发，版权归 Phantom 贡献者（GroupMountain）所有；库其余部分仍为 MIT。分发包含该部分的产物时需同时满足 LGPL-3.0：保留版权与许可声明、提供对应源码（来源位置：`src/FloatingTextManager.h` 文件头、`src/FloatingTextManager.cpp` 相应函数上方标注、本 README 与 `docs/versions/api-version-matrix.md`），并保证该部分可被替换 / 独立重建。\n"},{"file":"README.en.md","lang":"en","text":"<div align=\"center\">\n  <img src=\"docs/assets/HologramLib.png\" alt=\"HologramLib — unified protocol-layer hologram & display library for Bedrock servers\" width=\"100%\">\n</div>\n\n<!-- Docs site: https://ieckseyr.github.io/HologramLib/ — built and published from this repo's docs/ by .github/workflows/docs.yml -->\n[中文](README.md) · [English](README.en.md) · [Docs](https://ieckseyr.github.io/HologramLib/en/)\n\nHologramLib is a **protocol-layer display library** for Bedrock servers (LeviLamina / BDS): one API that pushes shapes, holograms, items, entities and menus straight to the client — no real entities spawned, nothing written to the save, no server-side world state touched.\n\nThe same capabilities are reachable two ways: **C++ plugins** (frozen pure-virtual interfaces) and **LSE scripts** (`ll.import`).\n\n| | |\n|---|---|\n| Plugin release | `26.51.6` |\n| API version | `1.30.0` (`HOLOGLIB_API_VERSION 0x012400`) |\n| Platform | LeviLamina 26.51 · BDS 1.26.51 (protocol 2193) |\n| Public surface | One public header, `include/hologramlib/HologramLib.h`, plus the LSE namespace `HologramLib` (273 exports) |\n| Script prerequisite | `lrca` (LegacyRemoteCall); when absent every export call is a safe no-op and the C++ interface is unaffected |\n| License | MIT (the floating-text \"dynamic lines\" feature is derived from Phantom, LGPL-3.0) |\n\nThis is a **prerequisite library, not a feature plugin**: it provides rendering primitives, protocol wrappers and timing notifications only. Commands, forms, permissions, placeholders and persistence belong to the consumer.\n\n## Changelog\nThe complete changelog lives in\n[the changelog](docs/versions/changelog.en.md).\n\n# <font size=24>Full documentation</font>\n<font size=16>[HologramLib docs site](https://ieckseyr.github.io/HologramLib/en/)</font>\n\n## How to write\n\n### C++ plugin\n\n```cp0\n#include \"hologramlib/HologramLib.h\"\n\n// Gate the capability at compile time; handshake at runtime in case an older build is installed\nstatic_assert(HOLOGLIB_API_VERSION >= 0x011B00, \"requires 1.21.0 (ITradeMenu)\");\n\nauto& lib = hologramlib::IHologramLib::getInstance();\n\n// Holographic text: one text shape per block, lines joined with \\n, inline colours via § codes\nauto holo = lib.holograms().create(0, 70, 0);\nlib.holograms().addLine(holo, \"§eWelcome to spawn\");\nlib.holograms().addLine(holo, \"Online: {online}\");         // {var} resolves per viewer\nlib.holograms().setDepthTest(holo, true);                  // true = occluded by blocks (default is see-through)\nlib.holograms().draw(holo);\n\n// Shapes: line + colour + lifetime\nauto line = lib.shapes().createLine(0, 64, 0, 10, 64, 10);\nlib.shapes().setColor(line, 1.0f, 0.2f, 0.2f, 1.0f);\nlib.shapes().draw(line);\n\n// Virtual container: a list UI any input device can click (a click is an item pickup)\nhologramlib::ContainerMenuSpec menu;\nmenu.title = \"§8Quest list\";\nmenu.rows  = 3;                                            // 3 = 27 slots; 6 = 54 slots\nmenu.items.resize(27);\nmenu.items[0].type = \"minecraft:diamond_sword\";\nmenu.items[0].name = \"§bTrial\";\nauto menuId = lib.containerMenus().open(\"Steve\", menu);\nlib.containerMenus().setItem(menuId, 0, {\"minecraft:barrier\", 1, 0, \"§cDone\", {}});\n```\n\nxmake integration:\n\n```lua\nadd_includedirs(\"../HologramLib/include\")\nadd_linkdirs(\"../HologramLib/build/windows/x64/release\")\nadd_links(\"HologramLib\")\n```\n\n### LSE script\n\n> The standard LSE interfaces (`mc`, `ll`, `logger`, events, NBT, forms, databases …) are covered by the [LSE docs](https://lse.levimc.org/apis/); this section only covers HologramLib's own namespace.\n\n```js\n// One namespace, \"HologramLib\", with 16 domain prefixes\nconst holoCreate      = ll.import(\"HologramLib\", \"holoCreate\");\nconst containerOpen   = ll.import(\"HologramLib\", \"containerOpen\");\nconst sensingIsTouch  = ll.import(\"HologramLib\", \"sensingIsTouch\");\n\n// Route by client device: touch players get the virtual container (clicks always send a packet)\nif (sensingIsTouch(\"Steve\")) {\n    const id = containerOpen(\"Steve\", \"§8Quest list\", 3);\n    // Drain clicks from a guard/timer loop (reading empties the queue)\n    for (const line of ll.import(\"HologramLib\", \"containerPollClicks\")()) {\n        // \"player=Steve menuId=1 slot=0 closed=0\"\n    }\n}\n```\n\n## Installation\n\n1. Stop the server.\n2. Extract the release archive `HologramLib.zip` and drop the resulting `HologramLib` folder into the server's `plugins/`, giving `plugins/HologramLib/` (containing `HologramLib.dll` and `manifest.json`).\n3. Start the server. Load order does not matter: the library checks for the LSE compatibility layer during `enable()` and retries on `ServerStarted`.\n\nConsumers only need `getInstance()` in `enable()`; there is no declared dependency to add.\n\nRelease builds are completely silent: all diagnostic logging is disabled at compile time and the log strings never enter the binary. To debug, temporarily enable it with `xmake f --holo_diag=y && xmake build -y`, and reset it (`--holo_diag=n`) before shipping.\n\n\n## Versions\n\n| Number | Where | Purpose |\n|---|---|---|\n| Plugin release | `version` in `manifest.json` | For deployment; matches the git tag (e.g. `26.51.6`) |\n| API version | `1.30.0` above | Human-readable capability version |\n| `HOLOGLIB_API_VERSION` | `include/hologramlib/HologramLib.h` | The only version source in code, `0x012400` |\n\nThe full mapping, the encoding rule, and the reasons behind the two documented API shrinks are in the [version & ABI matrix](docs/versions/api-version-matrix.en.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nThe holographic-text \"dynamic lines\" feature (the `FloatingTextLine` content pool, rotation interval, per-line variable toggle, interval-modulo rotation, 0.5 s throttled refresh with per-player resend, and content deduplication) is derived from [Phantom](https://github.com/GroupMountain/Phantom) (a LeviLamina Bedrock hologram plugin, GNU Lesser General Public License v3.0).\n\nAs required by LGPL-3.0, the origin is stated here: that derived part and its derivative works are distributed under LGPL-3.0, copyright held by the Phantom contributors (GroupMountain); the rest of the library remains MIT. Distributions that include that part must also satisfy LGPL-3.0: keep the copyright and licence notices, provide the corresponding source (locations: the file header of `src/FloatingTextManager.h`, the comments above the relevant functions in `src/FloatingTextManager.cpp`, this README and `docs/versions/api-version-matrix.md`), and keep that part replaceable / independently rebuildable.\n"}],"gallery":[],"variants":[{"label":"","versions":["26.51.6"]}],"versions":[{"version":"26.51.6","prerelease":false,"released":"2026-10-29T06:44:47Z","releaseUrl":"https://github.com/Ieckseyr/HologramLib/releases/tag/v26.51.6","manifestUrl":"https://github.com/Ieckseyr/HologramLib/blob/v26.51.6/tooth.json","info":{"name":"HologramLib","description":"前置库：基岩版协议层统一悬浮显示库 / Library: Bedrock protocol-layer unified hologram & display library","tags":["type:mod","platform:levilamina","library","lse"],"avatar_url":""},"variants":[{"label":"","platform":"win-x64","dependencies":{"github.com/LiteLDev/LeviLamina":"26.51.*","github.com/LiteLDev/LegacyRemoteCall":"0.22.*"},"leviLamina":"26.51.*","install":"lip install github.com/Ieckseyr/HologramLib@26.51.6"}]}],"dependencies":{"github.com/liteldev/levilamina":{"tooth":"github.com/LiteLDev/LeviLamina","name":"LeviLamina","owner":"LiteLDev","url":"https://levimc.org/mods/github.com/LiteLDev/LeviLamina/"},"github.com/liteldev/legacyremotecall":{"tooth":"github.com/LiteLDev/LegacyRemoteCall","name":"LegacyRemoteCall","owner":"LiteLDev","url":"https://levimc.org/mods/github.com/LiteLDev/LegacyRemoteCall/"}},"requiredBy":[]}