原创 娱乐 FotiaCosmetic｜高性能时装与武器皮肤｜CraftEngine 1.0.2

[MD] **FotiaCosmetic** 是一套面向现代 Paper 服务器的时装与武器皮肤系统。它把玩家拥有权、穿戴状态、菜单、显示策略、CraftEngine 物品和跨服数据整合到一个插件中，同时允许服主按服务器、世界、部位自由选择 `ACTUAL`、`VIRTUAL` 或 `HIDDEN` 模式。 无需客户端模组，只要玩家加载服务器资源包，就能获得完整的时装与武器外观体验。 ## 你可以用它做什么？ - 为玩家提供 **帽子、胸甲、裤子、鞋子、背饰、副手、气球** 7 类时装。 - 为 **剑、弓、斧、镐、弩、重锤、矛、三叉戟、盾牌** 配置独立武器皮肤。 - 将时装作为商城商品、通行证奖励、活动奖励、任务奖励或身份特权发放。 - 给予永久或限时时装；限时权益到期后自动卸下并清理。 - 向指定玩家、离线玩家或全部已知玩家批量发放时装。 - 通过共享 MySQL/MariaDB，让玩家的拥有权与选择状态在多台服务器之间持久化。 ## 一套插件，两种真正不同的使用方式 | 模式 | 适合场景 | 行为 | | --- | --- | --- | | `VIRTUAL` | 大厅、RPG、装扮展示、不希望改动真实物品 | 通过数据包投影外观，保留玩家原有装备与物品；背饰、气球不会在世界中生成普通 Bukkit 实体。 | | `ACTUAL` | 武器交易、掉落、拾取，以及希望皮肤成为物品本身的玩法 | 将皮肤写入实际物品；物品被丢出、交易或由其他玩家拾取后，皮肤身份仍可保留。 | | `HIDDEN` | 禁用世界、竞技场、特殊玩法服 | 保留玩家数据，但在指定服务器或世界中停止显示对应类型。 | 显示规则支持 **世界 > 服务器 > 全局** 的分层覆盖。大厅可以使用虚拟时装，生存服可以使用实际武器，竞技世界则可以隐藏背饰和气球，不需要为每台服务器维护不同版本的插件。 ## 不只是“换一个模型” ### 专用时装菜单 - 菜单只显示玩家真正拥有的时装，不会把未解锁内容铺满界面。 - 普通时装按部位分类，支持内容翻页。 - 武器皮肤拥有独立菜单；武器类型和皮肤列表均可分别翻页，方便长期扩充。 - 玩家可以直接选择、切换或卸下当前时装。 - 菜单标题、布局、按钮、物品名称和 Lore 均由 YAML 配置。 ### CraftEngine 深度适配 FotiaCosmetic 可直接使用 CraftEngine 自定义物品作为图标、虚拟模型或实际物品。当前项目面向 **CraftEngine 26.8** 集成，无需再维护一套重复的模型映射。 对于三叉戟，插件还单独处理了手持、蓄力、投掷、落地、回收与拾取流程，避免皮肤在投出或回到背包时突然变回原版外观。 ### 背饰与气球 背饰使用客户端虚拟载体并与玩家乘客关系同步，移动与转身时持续校正朝向，减少高速移动时“甩在身后”的视觉延迟。气球的模型、锚点和绳端位置可以独立配置，并使用相对位置跟随，避免玩家高度变化导致气球位置突变。 ### 完整的拥有权系统 - 永久拥有与限时拥有。 - 在线、离线和全服批量操作。 - 选择前验证玩家是否拥有对应时装。 - 收回时装后自动清理已穿戴状态。 - 提供独立 API 模块，便于商城、任务、活动或其他插件对接。 ## 为多人服务器设计的性能策略 FotiaCosmetic 并不是每个 Tick 对所有玩家和所有观察者进行完整重算： - 只向配置视距内、同世界且可见的观察者发送虚拟外观。 - 使用脏状态合并刷新，避免同一 Tick 内重复计算同一玩家。 - 背饰与气球采用增量相对移动；只有超出协议范围时才进行绝对位置同步。 - 虚拟配饰通过 PacketEvents 发送客户端实体，不向服务器世界注册普通实体。 - 在线玩家资料使用内存快照，数据库加载与保存异步执行。 - SQLite、MySQL、MariaDB 均通过连接池管理，并支持自动保存间隔配置。 ### 综合基准对比 ![FotiaCosmetic 与 HMCCosmetics 综合性能对比] 在项目内置的 **100 名佩戴者 × 100 名观察者 × 60 秒混合负载** 基准中，以 HMC 参考实现为 100： | 指标 | HMC 参考实现 | FotiaCosmetic | 降低 | | --- | ---: | ---: | ---: | | CPU 第 95 百分位耗时 | 4,112 μs | 2,277 μs | 44.6% | | 数据包数量 | 1,182 万 | 418 万 | 64.6% | | 协议传输量 | 408.6 MB | 190.8 MB | 53.3% | | 内存分配量 | 12.48 GB | 2.75 GB | 78.0% | > 测试说明：以上结果来自项目内置的模型化混合负载与 JMH 基准，用于对比等价渲染策略的计算、数据包和内存成本，并不是对任意服务器 TPS 的绝对保证。实际结果会受到硬件、在线人数、视距、资源包和其他插件影响，建议服主在自己的生产配置下复测。 ## 数据库与多语言 - 默认使用 SQLite，开箱即用。 - 支持 MySQL 与 MariaDB，适合群组服共享玩家数据。 - 内置简体中文、繁体中文、英语、日语、韩语、德语、法语、西班牙语和巴西葡萄牙语。 - 菜单、提示消息、名称与 Lore 均可配置。 ## 安装要求 - Java 21 或更高版本。 - Paper 1.21.4 API 及兼容分支（如 Leaf）；具体兼容版本以发布说明为准。 - **PacketEvents 2.13.x**：必需依赖。 - **CraftEngine 26.8**：可选依赖；使用 CraftEngine 自定义物品时需要安装。 - 玩家需要加载包含对应模型和纹理的资源包。 ## 五分钟快速开始 1. 安装 PacketEvents；需要 CraftEngine 物品时同时安装 CraftEngine。 2. 将 FotiaCosmetic JAR 放入服务器 `plugins` 目录并启动一次服务器。 3. 在 `plugins/FotiaCosmetic/cosmetics/` 中添加时装与武器皮肤定义。 4. 在 `display-rules.yml` 中选择各部位的显示模式。 5. 根据需要修改 `menus/main.yml`、`menus/weapons.yml` 与语言文件。 6. 使用 `/fc reload` 重新加载配置，再向玩家发放时装。 显示策略示例： ```yaml global: slots: head: VIRTUAL back: VIRTUAL balloon: VIRTUAL weapons: sword: ACTUAL trident: ACTUAL ``` ## 玩家命令 ```text /fc /cosmetic ``` 打开自己的时装菜单。默认权限 `fotiacosmetic.use` 对所有玩家开放。 ## 管理命令示例 ```text # 给予一名玩家永久背饰 /fc grant Steve slot back <时装ID> 永久 # 给予全部已知玩家 7 天三叉戟皮肤 /fc grant * weapon trident <皮肤ID> 7d # 为玩家选择某个武器皮肤 /fc equip Steve weapon sword <皮肤ID> # 卸下指定部位 /fc unequip Steve slot back # 查看玩家拥有与穿戴数量 /fc info Steve # 打开玩家菜单 / 重载配置 /fc open Steve /fc reload ``` 管理员可使用总权限 `fotiacosmetic.admin`，也可以按 `grant`、`revoke`、`equip`、`unequip`、`open.other`、`info` 和 `reload` 分别授权。 ## 适合哪些服务器？ - RPG、MMO 与剧情服：为职业、阵营、任务和 Boss 掉落制作专属外观。 - 生存与群组服：用实际武器皮肤支持交易、掉落和跨服持久化。 - 大厅与小游戏服：用虚拟模式展示背饰和气球，同时保持玩家真实装备不变。 - 商城与通行证：通过永久、限时和全服发放能力快速接入现有奖励系统。 ## 项目地址 **GitHub：** https://github.com/Ti-Avanti/FotiaCosmetic 问题反馈与功能建议可提交到 GitHub Issues。欢迎试用、反馈真实服务器数据，也欢迎为项目点一个 Star。 如果你正在寻找一套既能展示复杂时装，又认真处理武器生命周期、跨服数据与多人性能的系统，FotiaCosmetic 值得放进你的测试服亲自体验。 [/MD]