原生 MHR 全息显示 26.10.2

[MD] # MeowHolographicRenderer 使用文档 永久存储的悬浮展示插件，三类条目统一管理： | 条目类型 | 说明 | 底层 | |----------|------|------| | **物品展示** | 手持任意物品创建的 3D 悬浮展示，支持自旋/多轴漂浮/环绕公转/脉冲缩放/附魔光效 | HologramLib IItemDisplay（FMBE 狐狸驱动） | | **悬浮字** | 多行彩色文字，支持 MeowPAPI 占位符定时刷新 | HologramLib IHologramText | | **形状渲染** | 线框调试渲染：框/线/圆/球/箭头 | HologramLib IShapeDrawer | 依赖 `HologramLib >= 1.9.0`（setGlint 附魔光效 API）。 --- ## 命令 命令注册为 Any，执行时内部自检 OP（`getCommandPermissionLevel >= 1`）。 | 命令 | 说明 | |------|------| | `/mhr` | 打开主菜单（三类条目统一入口） | | `/mhr list` | 聊天列出全部物品展示与状态摘要 | | `/mhr spawn [名称]` | 手持物品在脚下创建展示（快照 NBT，附魔物品自带光效） | | `/mhr menu <id>` | 直接打开某条展示的管理菜单 | | `/mhr here` | 把 16 格内**最近的**展示移到你面前（免查 id） | | `/mhr bring <id>` | 把指定展示移到你面前 | | `/mhr del <id>` | 删除指定展示（连带其悬浮字） | | `/mhr text list` | 列出全部悬浮字 | | `/mhr text create <内容>` | 在脚下创建悬浮字（`\n` 换行） | | `/mhr text menu <uid>` | 打开悬浮字管理表单 | | `/mhr text del <uid>` | 删除悬浮字 | | `/mhr shape list` | 列出全部形状 | | `/mhr shape create <类型>` | 在脚下创建形状（box/line/circle/sphere/arrow 或中文 框/线/圆/球/箭头） | | `/mhr shape menu <uid>` | 打开形状管理表单 | | `/mhr shape del <uid>` | 删除形状 | --- ## 菜单结构 ``` 主菜单（/mhr）—— 三类条目统一入口（无维度分类, 全部展示在一起） ├─ [+] 手持物品创建展示 创建后直接进入管理枢纽 ├─ [+] 新建悬浮字 ├─ [+] 新建形状 ├─ [物品展示] 所有展示 (N) ├─ [悬浮字] 所有悬浮字 (N) └─ [形状渲染] 所有形状 (N) 管理枢纽（物品展示） ├─ [传送] 移到我面前 [微调] 相对平移 ±8 格 [坐标] 精确输入 ├─ [旋转] 基础三轴 [自旋] 三轴角速度 ├─ [漂浮] 多轴漂浮 [环绕] 绕当前位置公转 ├─ [附魔光效] 紫色光效 开/关（点击直接切换） ├─ [缩放] 详细设置 [放大 ×1.25] [缩小 ×0.8] ├─ [悬浮字] [重命名] └─ [信息] 完整状态+生效表达式 [删除] 二次确认 [<< 返回列表] 悬浮字管理：内容(多行编辑) / 坐标 / 传送 / 重命名 / 删除 形状管理：类型切换(Dropdown) / 起终点坐标 / 传送 / 重命名 / 删除 ``` 交互约定：**每个操作完成后回到管理枢纽并给出结果反馈**（无死胡同）；所有按钮标签实时显示当前值；删除需二次确认；数值/函数/坐标输入错误会报具体原因并留在原表单。 --- ## 物品展示动效 所有动态效果由 Molang 表达式在客户端计算（`query.life_time` = 实体存活秒数，恒定递增），服务端零开销。 | 效果 | 生效公式 | 参数含义 | |------|----------|----------| | 漂浮（简单） | `基线 + sin(life_time × 速度) × 幅度` | 三轴独立：Y=上下、X=左右、Z=前后，幅度 0 = 该轴不动 | | 环绕公转 | `X=sin(θ)×r, Z=cos(θ)×r`（θ=相位+life_time×角速度） | 半径=轨道格数；角速度=度/秒；相位=起始方位 | | 自旋 | `基础角 + life_time × 角速度` | 三轴独立度/秒，负值反向 | | 脉冲缩放 | `基础 × (1 + sin(life_time × 速度) × 幅度)` | 幅度=相对基础缩放的比例 | | 附魔光效 | 物品 NBT 注入 1 级锋利 | 客户端渲染紫色流光 | - 漂浮与环绕可叠加（轨道 + 上下浮动 = 螺旋上升） - 数值范围：漂浮幅度 0~100 万格、周期 0.01~100 万秒、缩放 0.000001~100 万、自旋 ±100 万°/s（全部无实际限制） - 任何参数修改都会重置动画相位（从 0 重新开始），FMBE 技术的正常行为 ### 附魔光效与 NBT 快照 - `/mhr spawn` 时快照手持物品完整用户数据（SNBT）：自定义名称、附魔等全部保留，**附魔物品创建即自带光效** - 管理页 `[附魔光效]` 按钮：任何物品随时补开/关光效（注入 1 级锋利，仅取光效不影响其余 NBT） --- ## 经典数学函数（自定义运动） 漂浮与缩放都支持填写**经典数学表达式**，用课本语法描述随时间变化的函数： ``` 变量： x 或 t —— 时间（秒） 常量： pi, e 运算： + - * / %（取余） ^（幂，右结合） 支持隐式乘法：2x、2sin(x)、(x+1)(x-1) 函数： sin cos tan asin acos atan atan2（弧度制） abs sqrt floor ceil round exp ln log sign min max mod pow（多参数 min/max 自动嵌套） ``` **三角函数按经典数学弧度制**（内部自动换算 Bedrock Molang 的角度制），写出来的行为和数学课本一致。 ### 漂浮函数 f(x) 描述**相对原位置的上下位移**（自动叠加基线）： | 输入 | 效果 | |------|------| | `sin(x)*1.2` | 上下 ±1.2 格，周期 2π≈6.28s | | `2*sin(x/2)` | ±2 格，慢速（周期≈12.6s） | | `sin(x)+sin(3*x)/3` | 叠加谐波，起伏更自然 | | `abs(sin(x))*0.5` | 只向上弹跳（半周期反弹） | ### 缩放函数 f(x) 描述**缩放值本身**随时间的变化： | 输入 | 效果 | |------|------| | `0.5+sin(x*2)*0.1` | 0.4~0.6 之间呼吸 | | `0.375*(1+sin(x*3)*0.2)` | ±20% 脉冲 | | `x mod 2` | 锯齿波（每 2 秒归零一次, 演示用） | ### 专家逃生舱 以 `molang:` 前缀开头的内容**原样作为 Molang 表达式**下发，不做翻译： ``` molang:-4+math.sin(query.life_time*90)*1.2 ``` 适合直接复用社区 Molang 片段。可用变量参考 HologramLib 文档（`query.life_time`、`math.*` 系列，注意 Molang 三角函数为**角度制**）。 ### 语法校验 提交时逐字符校验，错误会报**位置和原因**（如 `位置 7: 未知名称 'sni'`）并停留在原表单，未保存的内容不会生效。 --- ## 悬浮字与 PAPI 占位符 - 文本支持 § 颜色码与多行编辑（`\n`） - 文本中任意位置含 `{xxx}` 时启用 MeowPAPI 占位符翻译，**每 1 秒自动重译刷新**（如 `{player_name}`、`{server_time}`） - RGBA 颜色可调（0~1）；PAPI 开关可关闭 --- ## 持久化 - 存档：`plugins/MeowHolographicRenderer/config/displays.json`（三类条目统一存储） - 物品展示 ID：创建时由 HologramLib `createRandom` 在随机段生成并查重；重启后 `createWithId` 原位恢复 - 悬浮字/形状：独立 uid 持久化，运行时 id 重启重建 - 展示携带的悬浮字与展示同生命周期（删除展示时一并销毁） - 旧存档自动迁移：旧版 NBT 附魔残留自动转为新的光效开关字段 ## 故障排查 | 现象 | 处理 | |------|------| | 启动报 `HologramLib 版本过低` | 把新版 HologramLib.dll（≥1.9.0）复制到 `plugins/HologramLib/` **根目录**后重启（build 目录产物不算部署） | | `/mhr` 提示未知命令 | 命令注册为 Any + OP 自检；跨服场景客户端可能隐藏命令，直接输入执行即可 | | 修改不生效 | 确认复制的是插件根目录的 dll 并重启 BDS；**服务器运行中 DLL 被锁定，必须先关服再复制** | | 漂浮/自旋不动 | 确认使用本版本（旧版有 `query.anim_time` 误用问题，本版已改 `query.life_time`） | | 进服看不到形状/悬浮字 | HologramLib ≥1.8 才有进服重发；确认两个插件都是新版（启动日志有 `进服重发` 记录） | | 修改一个展示另一个跟着变 | 已修复（幽灵动画清理）；确认 HologramLib 为 16:24 后构建的版本 | [/MD]