原创 工具 娱乐 Yiyun3DItems | 专为高版本打造的3D掉落物插件 | 支持Folia | 极低性能占用 | 1.21.4+ v0.1.0 - 测试版

[MD] # Yiyun3DItems **让掉落物自然落地，让世界更有细节。** Yiyun3DItems 是面向 Paper / Folia 的三维掉落物展示插件。工具平放、方块端正摆放、成组物品分层呈现，为采集、战斗和日常丢弃的物品增添更丰富的视觉效果。 **原版客户端可用 · 无额外服务端展示实体 · 原生 Folia 支持**  ## 好看，也兼顾服务器性能 **原生 ItemDisplay 展示，无额外服务端展示实体，无逐物品每 tick 跟随任务。** 相比在世界中生成真实盔甲架、再逐 tick 传送跟随掉落物的实现，Yiyun3DItems 将三维展示交给客户端，减少额外展示实体的服务端管理与位置同步开销。 | 性能设计 | 带来的优势 | | --- | --- | | **展示留在客户端** | 通过数据包创建客户端 ItemDisplay，无需在服务端世界中生成额外的盔甲架或展示实体。 | | **复用原版移动同步** | 展示挂接在原版掉落物上，随其移动，无需为每个物品运行每 tick 的跟随任务或持续发送额外的展示传送包。 | | **基于原版实体追踪** | 根据原版实体追踪数据更新展示，正常展示无需定时遍历玩家附近的世界实体。 | | **控制展示规模与切换节奏** | 支持显示距离与每位玩家的展示实体数量上限，优先展示近处物品，并分批新增展示，减缓批量切换时的瞬时发包压力。 | 数量上限包含堆叠展示的每一层；超出距离或数量限制的物品保持原版显示。服主可以按服务器规模和玩家需求，在展示效果与资源开销之间灵活调整。 ## 更自然的落地姿态 剑与工具平躺在地面，方块保持立体形态，盾牌、头颅、旗帜和床等物品也有各自的姿态配置。插件根据原版模型尺寸自动计算贴地位置与水平中心，搭配稳定的随机朝向，让地上的物品摆放更自然。 内置默认样式，安装后即可体验；也可以调整缩放、旋转和偏移，为服务器设计自己的掉落物风格。 ## 展示效果与使用体验 | 特色 | 带来的体验 | | --- | --- | | **数量分层** | 按物品数量增加展示层数，每层可独立设置旋转与偏移，让成组掉落更有层次。 | | **发光与队伍颜色** | 继承掉落物的发光效果与队伍颜色，也可设置自定义发光颜色。 | | **亮度与阴影** | 按物品类别调整亮度和展示阴影，配合服务器的整体视觉风格。 | | **玩家独立开关** | 每位玩家自由选择三维或原版显示，偏好会保存，重新登录后继续生效。 | | **灵活的显示范围** | 可按世界、物品类型和标签控制展示，给活动物品、特殊道具留出独立规则。 | | **资源包物品配置** | 沿用物品已有模型，支持按 `item_model` 为自定义物品设置专属姿态。 | | **保留原版拾取** | 真实掉落物及其拾取逻辑继续由服务器管理，玩家照常拾取物品。 | ## 适用环境 支持 **Paper / Folia**，面向与服务端同版本的 **Minecraft Java 版客户端**。 | Minecraft 版本 | Java 环境 | | --- | --- | | 1.21.4–1.21.11 | Java 21 | | 26.1.1、26.1.2、26.2、26.3 | Java 25 | ## 安装后，丢一个物品试试看 1. 将插件 JAR 放入服务器的 `plugins/` 目录。 2. 重启服务器，插件会生成默认配置并开启展示。 3. 进入游戏，丢出工具、方块或一组物品，体验不同的展示效果。 玩家无需安装客户端模组。展示原版物品无需额外资源包；使用自定义模型时，继续使用服务器原有的资源包。 ## 按你的服务器风格调整 配置文件位于 `plugins/Yiyun3DItems/`，修改后使用 `/y3di reload` 生效。 | 文件 | 可以调整什么 | | --- | --- | | config.yml | 总开关、世界范围、显示距离、数量上限、堆叠层数、发光和排除规则。 | | profiles.yml | 各类物品的缩放、旋转、偏移、自动贴地、亮度、阴影和分层姿态。 | | messages.yml | 命令反馈、提示文字与颜色。 | 姿态可以按物品类型、物品标签或自定义模型分别配置。例如，让某类道具直立展示、为工具放大一点尺寸，或为资源包中的特殊物品单独设置位置。自定义模型尺寸与原版差异较大时，可以关闭该配置的自动贴地与居中，手动微调姿态。 配置重载前会先检查内容，填写错误时保留原有配置，方便逐步调整。 ## 常用命令 主命令为 `/y3di`，也可以使用 `/yiyun3ditems`。输入 `/y3di help` 查看可用命令。 | 命令 | 用途 | 默认可用者 | | --- | --- | --- | | `/y3di toggle [on\|off]` | 切换自己的三维掉落物显示。 | 所有玩家 | | `/y3di reload` | 重载配置与提示文字。 | OP | | `/y3di status` | 查看插件状态与显示统计。 | OP | | `/y3di inspect` | 查看附近物品的显示状态与原因。 | OP | | `/y3di repair [玩家]` | 刷新自己或指定玩家的掉落物显示。 | OP | 需要按用户组控制显示时，可以使用 `yiyun3ditems.view` 权限；拥有 `yiyun3ditems.bypass` 权限的玩家保持原版显示。 部分物品保持原版显示时，可以使用 `/y3di inspect` 查看是否受个人开关、排除规则、距离或数量上限影响。需要切回原版时，玩家使用 `/y3di toggle off` 即可，服主也可以通过配置关闭展示。 --- 插件使用 [bStats](https://bstats.org/plugin/bukkit/Yiyun3DItems/34850) 匿名统计使用情况，可在 `plugins/bStats/config.yml` 中设置 `enabled: false` 关闭。 [/MD]