原创 闭源 前置/API 高版本[1.21.X-1.21.8]修仙服务器的玩法前置库 内置多种系统模块！[心境][天谴][怪物罪孽][资质]多种系统！ 1.5.1

[MD] # 【前置插件】YouLongLibs - 游龙前置库 ``` [ATTACH type="full" size="2730x1535"]117541[/ATTACH] ``` **🎮 支持 Paper / Purpur / [Leaf](https://www.minebbs.com/resources/leaf.9242/) 1.21.8** | **⚡ 高性能优化** | **🔌 完整API** | **🌍 中英双语** | **📊 PlaceholderAPI** --- ## 📖 插件简介 **YouLongLibs（游龙前置库）** 是一个专为修仙服务器设计的高性能前置插件，提供三大核心系统： | 系统 | 功能 | 特性 | |------|------|------| | 🧘 心境系统 | 玩家心境值管理 | 影响状态和恢复能力 | | 🌟 资质系统 | 玩家修炼资质 | 影响学习速度（0%-85%加成） | | ⚡ 天谴系统 | PK惩罚机制 | 击杀玩家增加天谴值 | 所有系统均提供完整的 **Java/Kotlin API**，供其他插件调用，实现功能复用和模块化开发。 --- ### ⚡ 高性能优化 - **多级缓存系统** — 内存缓存 + 定期刷新，TPS影响接近0 - **异步数据库操作** — 所有数据库操作异步执行，不卡服 - **批量处理机制** — 缓存批量写入，减少数据库压力 - **对象池技术** — StringBuilder池、Map池，减少GC压力 - **SQLite WAL模式** — 高性能并发读写 ### 🏗️ 架构设计 - **分层设计** — API层、业务层、存储层清晰分离 - **线程安全** — ConcurrentHashMap、读写锁、原子操作 - **事件驱动** — 完整的事件系统，可取消、可监听 - **模块化设计** — 易于扩展和集成 ### 🔌 API友好 - **同步/异步双接口** — 支持同步调用和CompletableFuture异步调用 - **Result模式** — 优雅的错误处理，链式调用 - **完整文档** — 所有公共API都有详细注释 - **事件系统** — 所有关键操作都触发事件 ### 📊 PlaceholderAPI集成 - **统一扩展** — 一个扩展管理所有变量 - **20+变量** — 心境、资质、天谴全覆盖 - **高性能** — 从内存缓存读取，< 0.1ms --- ## 🌟 功能详解 ### 1️⃣ 心境系统 (XinJing System) 玩家心境值管理系统，影响玩家状态和自然恢复能力。 #### 核心功能 **心境值管理（0-100）** - 自然恢复机制（可配置速率：0.5点/分钟） - 状态削弱（黄名50%、红名80%） - 死亡惩罚（可配置） - 完全可配置的恢复速率和间隔 **四种状态转换** | 状态 | 心境范围 | 效果 | |------|---------|------| | 🟢 正常状态 | 心境 > 70 | 正常恢复 | | 🟡 黄名状态 | 30 < 心境 ≤ 70 | 恢复速度削弱50% | | 🔴 红名状态 | 0 < 心境 ≤ 30 | 恢复速度削弱80% | | 🖤 魔化状态 | 心境 = 0 | 无法恢复，需要管理员解除 | **罪孽值系统（业障系统）** ⭐ 完整实现 - 与 **MythicMobs** 深度集成（读取怪物的 `zuinie` 字段） - 击杀怪物根据罪孽值自动扣除心境 - 完全可配置的罪孽等级（默认：无垢、微垢、污秽、邪祟） - 业障越低的生灵，击杀时扣除心境越多 - 支持任意数量的自定义等级 - 软依赖优雅降级（MythicMobs 未安装不报错） **罪孽等级示例**（修仙风格） | 等级 | 范围 | 心境损耗 | 说明 | |------|------|---------|------| | 🟢 无垢 | 0-10 | 10.0 | 纯净生灵 | | 🟡 微垢 | 11-30 | 0.2 | 轻微污秽 | | 🟠 污秽 | 31-60 | 0.1 | 较重污秽 | | 🔴 邪祟 | 61-100 | 0.05 | 邪恶生灵 | #### 管理员命令 ``` /xinjing check [修士] - 查看心境值 /xinjing set <修士> <数值> - 设定心境值（0-100） /xinjing add <修士> <数值> - 增益心境值 /xinjing remove <修士> <数值> - 损耗心境值 /xinjing mohua <修士> - 堕入魔障 /xinjing unmohua <修士> - 破除魔障 /xinjing reload - 重载术法 /xinjing debug <子命令> - 调试工具 ``` **别名**: `/xj`, `/mood` --- ### 2️⃣ 资质系统 (ZiZhi System) 玩家修炼资质管理系统，影响学习速度和悟性。 #### 核心功能 **资质值管理（0-100）** - 首次进入随机生成（可配置范围：30-70） - 完全由管理员或其他插件API控制 - 持久化存储（支持SQLite/MySQL） - 支持多服同步（MySQL模式） **10个品阶等级** | 品阶 | 资质范围 | 悟性加成 | 颜色 | |------|---------|---------|------| | 九品 | 0-9 | +0% | 灰色 | | 八品 | 10-19 | +28% | 白色 | | 七品 | 20-29 | +40% | 青色 | | 六品 | 30-39 | +49% | 黄色 | | 五品 | 40-49 | +56% | 绿色 | | 四品 | 50-59 | +63% | 深绿 | | 三品 | 60-69 | +69% | 粉色 | | 二品 | 70-79 | +75% | 紫色 | | 一品 | 80-89 | +80% | 红色 | | 极品 | 90-100 | +85% | 金色 | **事件系统** - 资质值变化事件（可取消） - 等级变化事件（升级/降级自动提示） - 首次进入欢迎消息 #### 管理员命令 ``` /zizhi check [修士] - 查看资质 /zizhi set <修士> <数值> - 重塑资质（0-100） /zizhi add <修士> <数值> - 提升资质 /zizhi remove <修士> <数值> - 折损资质 /zizhi reload - 重载术法 /zizhi help - 显示帮助 /zizhi debug <子命令> - 调试工具 ``` **别名**: `/zz` --- ### 3️⃣ 天谴系统 (TianQian System) PK惩罚系统，击杀玩家增加天谴值，达到阈值后触发惩罚。 #### 核心功能 **天谴值管理（0-100）** - 击杀玩家：+2点（可配置） - 特殊规则：被击杀者天谴值 ≥80 时，击杀者不增加 - 防止恶意刷天谴值 **四种状态** | 状态 | 天谴范围 | 掉落几率 | 掉落数量 | |------|---------|---------|---------| | 🟢 正常状态 | 天谴 < 50 | 无 | 无 | | 🟡 黄名状态 | 50 ≤ 天谴 < 80 | 10% | 1件物品 | | 🔴 红名状态 | 80 ≤ 天谴 < 100 | 20% | 3件物品 | | ⚡ 天雷状态 | 天谴 = 100 | 100% | 10件物品 | **天雷机制** - 达到100天谴值后，60秒倒计时 - ActionBar实时显示倒计时 - 倒计时结束后，天雷降临击杀玩家 - 真实雷电效果 + 1000点伤害 - 清除经验（可配置是否清除等级） - 100%触发掉落（默认10件物品） - **特殊保护**：入魔状态的玩家不会被天雷击杀 **掉落系统** - 每个状态独立配置掉落几率和数量 - 随机掉落物品（盔甲、主手、副手、背包） - 支持黑名单（指南针等不掉落） - 详细的掉落提示 **死亡保护期** | 死亡类型 | 保护时长 | 说明 | |---------|---------|------| | 黄名死亡 | 30秒 | 保护期内无法被攻击 | | 红名死亡 | 60秒 | 保护期内无法被攻击 | | 天雷死亡 | 180秒 | 保护期内无法被攻击 | #### 管理员命令 ``` /tianqian check [修士] - 查看天谴值 /tianqian set <修士> <数值> - 设定天谴值（0-100） /tianqian add <修士> <数值> - 增加天谴值 /tianqian remove <修士> <数值> - 减少天谴值 /tianqian clear <修士> - 清零天谴值 /tianqian reload - 重载术法 /tianqian help - 显示帮助 ``` **别名**: `/tq` --- ## 📊 PlaceholderAPI 变量 ### 心境系统变量 ``` %youlonglibs_xinjing_value% - 心境值（75.50） %youlonglibs_xinjing_value_int% - 心境值整数（76） %youlonglibs_xinjing_status% - 状态名称（正常） %youlonglibs_xinjing_colored_status% - 带颜色的状态（&a正常） %youlonglibs_xinjing_percent% - 百分比（75.5%） %youlonglibs_xinjing_bar% - 条形图（████████▓▓） %youlonglibs_xinjing_bar_20% - 20格条形图 %youlonglibs_xinjing_full% - 完整信息（&a75.50&7/100.0 &8[正常&8]） %youlonglibs_xinjing_is_mohua% - 是否魔化（true/false） ``` ### 资质系统变量 ``` %youlonglibs_zizhi% - 资质值（75.5） %youlonglibs_zizhi_int% - 资质值整数（76） %youlonglibs_zizhi_tag% - 资质称谓（&5二品） %youlonglibs_zizhi_tag_plain% - 资质称谓纯文本（二品） %youlonglibs_zizhi_speed% - 学习速度加成（75%） %youlonglibs_zizhi_speed_value% - 学习速度加成数值（0.75） %youlonglibs_zizhi_level% - 资质等级（二品） %youlonglibs_zizhi_color% - 资质颜色代码（&5） ``` ### 天谴系统变量 ``` %youlonglibs_tianqian% - 天谴值（50.0） %youlonglibs_tianqian_int% - 天谴值整数（50） %youlonglibs_tianqian_status% - 状态名称（黄名） %youlonglibs_tianqian_colored_status% - 带颜色的状态（&e黄名） %youlonglibs_tianqian_color% - 状态颜色代码（&e） %youlonglibs_tianqian_drop_chance% - 掉落几率（10%） %youlonglibs_tianqian_protection% - 保护期剩余时间（30秒） ``` ### 使用示例 **记分板配置** ```yaml scoreboard: title: "&6◆ 修仙信息 ◆" lines: - "" - "&b心境: &f%youlonglibs_xinjing_value% &7/ &f100.0" - "&7状态: %youlonglibs_xinjing_colored_status%" - "&7%youlonglibs_xinjing_bar_20%" - "" - "&6资质: &f%youlonglibs_zizhi% %youlonglibs_zizhi_tag%" - "&d悟性: &5+%youlonglibs_zizhi_speed%" - "" - "&c天谴: &f%youlonglibs_tianqian% %youlonglibs_tianqian_colored_status%" - "" ``` **聊天前缀** ```yaml chat: format: "%youlonglibs_zizhi_tag% &f{player}&8: &7{message}" # 显示效果: &5二品 &fMlssya&8: &7你好 ``` --- ## 🔌 开发者 API ### 依赖配置 **plugin.yml** ```yaml name: YourPlugin version: 1.0.0 depend: [YouLongLibs] # 硬依赖 ``` **build.gradle.kts** (Gradle) ```kotlin repositories { maven("https://repo.papermc.io/repository/maven-public/") maven("https://repo.tabooproject.org/repository/releases") } dependencies { compileOnly("io.papermc.paper:paper-api:1.21.8-R0.1-SNAPSHOT") compileOnly("org.example:YouLongLibs:1.5.1") } ``` ### 心境系统 API #### 基础操作 ```java import org.example.youlonglibs.xinjing.api.XinJingAPI; // 获取API实例（单例模式） XinJingAPI api = XinJingAPI.getInstance(); // 获取心境值 Double xinjing = api.getXinJing(playerId); // 设置心境值（0-100） api.setXinJing(playerId, 75.0, false); // 增加心境值 Double newValue = api.addXinJing(playerId, 10.0, false); // 减少心境值 Double reduced = api.reduceXinJing(playerId, 5.0, false); // 检查状态 boolean isMohua = api.isMohua(playerId); boolean isYellow = api.isYellowName(playerId); boolean isRed = api.isRedName(playerId); ``` #### 罪孽值系统 API ```java // 根据罪孽值计算心境扣除量 Double deduction = api.calculateDeduction(80); // 返回: 0.05 // 获取罪孽值对应的等级 ZuiNieLevel level = api.getZuiNieLevel(80); player.sendMessage("罪孽等级: " + level.getName()); // 输出: 邪祟 // 在击杀 MythicMobs 怪物时使用 @EventHandler public void onMythicMobKill(MythicMobDeathEvent event) { Player killer = event.getKiller(); int zuinie = event.getMobType().getConfig().getInt("zuinie", 0); // 计算心境扣除 Double deduction = api.calculateDeduction(zuinie); // 减少心境值 api.reduceXinJing(killer.getUniqueId(), deduction, false); killer.sendMessage("§6击杀 §f" + event.getMobType().getDisplayName() + " §6，心境损耗: §f" + deduction); } ``` #### 异步操作（推荐） ```java // 异步获取心境值 api.getXinJingAsync(playerId) .thenAccept(value -> { player.sendMessage("§6心境值: §f" + value); }) .exceptionally(ex -> { player.sendMessage("§c获取心境值失败"); return null; }); // 异步增加心境值 api.addXinJingAsync(playerId, 10.0, false) .thenAccept(newValue -> { player.sendMessage("§a心境值增加至: §f" + newValue); }); ``` #### Result模式（最佳实践） ```java // 使用Result模式处理错误 api.getXinJingResult(playerId) .onSuccess(value -> { player.sendMessage("§6心境值: §f" + value); }) .onFailure(error -> { player.sendMessage("§c错误: " + error.getMessage()); }); ``` ### 资质系统 API #### 基础操作 ```java import org.example.youlonglibs.zizhi.api.ZiZhiAPI; // 获取API实例 ZiZhiAPI api = ZiZhiAPI.getInstance(); // 获取资质值 Double zizhi = api.getZiZhi(playerId); // 获取资质等级（九品到极品） String level = api.getZiZhiLevel(playerId); // 返回: "二品" // 获取学习速度加成（0.0-0.85） Double speedBoost = api.getSpeedBoost(playerId); // 获取资质颜色代码 String colorCode = api.getZiZhiColor(playerId); // 返回: "&5" // 设置资质值 api.setZiZhi(playerId, 75.0, false); // 增加资质值 api.addZiZhi(playerId, 5.0, false); // 减少资质值 api.removeZiZhi(playerId, 3.0, false); ``` #### 实际应用示例 ```java // 示例1: 经验系统集成 @EventHandler public void onPlayerExpChange(PlayerExpChangeEvent event) { Player player = event.getPlayer(); ZiZhiAPI api = ZiZhiAPI.getInstance(); // 获取资质加成 Double speedBoost = api.getSpeedBoost(player.getUniqueId()); // 计算最终经验 int baseExp = event.getAmount(); int finalExp = (int) (baseExp * (1 + speedBoost)); event.setAmount(finalExp); player.sendMessage("§d获得经验: §f" + finalExp + " §d(资质加成: §5+" + (int)(speedBoost * 100) + "%§d)"); } // 示例2: 技能学习速度 public void teachSkill(Player player, String skillName) { ZiZhiAPI api = ZiZhiAPI.getInstance(); Double speedBoost = api.getSpeedBoost(player.getUniqueId()); // 基础学习时间: 100秒 long baseTime = 100000; // 毫秒 long finalTime = (long) (baseTime / (1 + speedBoost)); player.sendMessage("§6学习 §f" + skillName + " §6需要: §f" + (finalTime / 1000) + "§6秒"); } // 示例3: 资质突破奖励 @EventHandler public void onZiZhiLevelUp(ZiZhiChangeEvent event) { if (event.getOldValue() < 10 && event.getNewValue() >= 10) { // 突破到八品 Player player = Bukkit.getPlayer(event.getPlayerId()); if (player != null) { player.sendMessage("§d✦ 资质突破！晋升至 §5八品 §d品阶"); player.playSound(player.getLocation(), Sound.ENTITY_PLAYER_LEVELUP, 1, 1); } } } ``` ### 天谴系统 API #### 基础操作 ```java import org.example.youlonglibs.tianqian.api.TianQianAPI; // 获取API实例 TianQianAPI api = TianQianAPI.getInstance(); // 获取天谴值 Double tianqian = api.getTianQian(playerId); // 获取天谴状态 String status = api.getStatus(playerId); // 返回: "黄名"、"红名"、"天雷" // 增加天谴值 api.addTianQian(playerId, 2.0, false); // 减少天谴值 api.removeTianQian(playerId, 1.0, false); // 检查保护期 if (api.isInProtection(playerId)) { player.sendMessage("§c你在保护期内，无法被攻击"); } // 获取保护期剩余时间（秒） long protectionTime = api.getProtectionTime(playerId); // 获取掉落几率（0.0-1.0） Double dropChance = api.getDropChance(playerId); // 获取掉落物品数量 int dropCount = api.getDropCount(playerId); ``` #### PK系统集成示例 ```java // 示例1: 自定义PK系统 @EventHandler(priority = EventPriority.HIGHEST) public void onPlayerKill(PlayerDeathEvent event) { Player victim = event.getEntity(); Player killer = victim.getKiller(); if (killer == null) return; TianQianAPI api = TianQianAPI.getInstance(); // 1. 增加击杀者天谴值 Double newTianQian = api.addTianQian(killer.getUniqueId(), 2.0, false); killer.sendMessage("§c天谴值增加至: §f" + newTianQian); // 2. 检查被击杀者天谴值 Double victimTianQian = api.getTianQian(victim.getUniqueId()); String status = api.getStatus(victim.getUniqueId()); // 3. 根据状态处理掉落 if ("天雷".equals(status)) { victim.sendMessage("§c因天谴值过高，所有物品掉落！"); event.getDrops().clear(); } else if ("红名".equals(status)) { // 20%概率掉落3件物品 if (Math.random() < 0.2) { victim.sendMessage("§e因天谴值过高，部分物品掉落"); } } // 4. 设置保护期（由系统自动处理） victim.sendMessage("§a你获得了 " + api.getProtectionTime(victim.getUniqueId()) + " 秒的保护期"); } // 示例2: 天谴值显示 public void showTianQianInfo(Player player) { TianQianAPI api = TianQianAPI.getInstance(); Double tianqian = api.getTianQian(player.getUniqueId()); String status = api.getStatus(player.getUniqueId()); Double dropChance = api.getDropChance(player.getUniqueId()); player.sendMessage("§6━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"); player.sendMessage("§6天谴信息"); player.sendMessage("§7天谴值: §f" + tianqian + " §7/ §f100.0"); player.sendMessage("§7状态: §c" + status); player.sendMessage("§7掉落几率: §f" + (int)(dropChance * 100) + "%"); player.sendMessage("§6━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"); } // 示例3: 天雷倒计时监听 @EventHandler public void onTianQianStatusChange(TianQianStatusChangeEvent event) { if ("天雷".equals(event.getNewStatus())) { Player player = Bukkit.getPlayer(event.getPlayerId()); if (player != null) { player.sendMessage("§4⚡ 天雷将在 60 秒后降临！⚡"); player.playSound(player.getLocation(), Sound.ENTITY_LIGHTNING_BOLT_THUNDER, 1, 1); } } } ``` ### 事件系统 #### 完整事件列表 ```java // 心境系统事件 import org.example.youlonglibs.xinjing.api.event.XinJingChangeEvent; import org.example.youlonglibs.xinjing.api.event.XinJingStatusChangeEvent; @EventHandler public void onXinJingChange(XinJingChangeEvent event) { // 心境值变化时触发 UUID playerId = event.getPlayerId(); double oldValue = event.getOldValue(); double newValue = event.getNewValue(); if (event.isCancelled()) return; // 检查是否被取消 // 可以取消变化 if (newValue < 0) { event.setCancelled(true); } } // 资质系统事件 import org.example.youlonglibs.zizhi.api.event.ZiZhiChangeEvent; @EventHandler public void onZiZhiChange(ZiZhiChangeEvent event) { // 资质值变化时触发 UUID playerId = event.getPlayerId(); double oldValue = event.getOldValue(); double newValue = event.getNewValue(); String oldLevel = event.getOldLevel(); String newLevel = event.getNewLevel(); if (!oldLevel.equals(newLevel)) { // 等级发生变化 Player player = Bukkit.getPlayer(playerId); if (player != null) { player.sendMessage("§d资质晋升至: §5" + newLevel); } } } // 天谴系统事件 import org.example.youlonglibs.tianqian.api.event.*; @EventHandler public void onTianQianChange(TianQianChangeEvent event) { // 天谴值变化时触发 UUID playerId = event.getPlayerId(); double newValue = event.getNewValue(); } @EventHandler public void onTianQianThunder(TianQianThunderEvent event) { // 天雷降临时触发 UUID playerId = event.getPlayerId(); Player player = Bukkit.getPlayer(playerId); if (player != null) { player.sendMessage("§4天雷击杀！"); } } @EventHandler public void onTianQianDrop(TianQianDropItemEvent event) { // 物品掉落时触发 UUID playerId = event.getPlayerId(); List<ItemStack> droppedItems = event.getDroppedItems(); // 可以修改掉落物品 event.setDroppedItems(droppedItems); } ``` --- ## ⚙️ 配置文件 所有配置文件都有详细的中文注释，支持热重载。 **配置文件位置**: - 心境系统: `plugins/YouLongLibs/xinjing/config.yml` - 资质系统: `plugins/YouLongLibs/zizhi/config.yml` - 天谴系统: `plugins/YouLongLibs/tianqian/config.yml` **语言文件位置**: - 中文: `plugins/YouLongLibs/*/lang/zh_CN.yml` - 英文: `plugins/YouLongLibs/*/lang/en_US.yml` 所有玩家可见消息都可以自定义！修改后执行 `/reload` 命令即可生效。 ### 配置示例 #### 心境系统配置 ```yaml # plugins/YouLongLibs/xinjing/config.yml xinjing: enabled: true # 初始值和最大值 default-value: 100.0 max-value: 100.0 # 自然恢复配置 recovery: enabled: true rate: 0.5 # 每分钟恢复0.5点 interval-seconds: 60 # 60秒检查一次 # 死亡惩罚 death-penalty: 0.5 # 魔化配置 mohua: reset-value: 50.0 # 解除魔化后的初始心境值 actionbar-warning: true # 魔化时发送ActionBar警告 # 罪孽等级配置（业障系统）- 完全可配置 zuinie-levels: # 无垢生灵（业障极低，斩杀损心境甚重） - name: "无垢" min: 0 max: 10 deduction: 10.0 # 击杀扣除心境值 color: "&f" # 微垢生灵 - name: "微垢" min: 11 max: 30 deduction: 0.2 color: "&b" # 污秽生灵 - name: "污秽" min: 31 max: 60 deduction: 0.1 color: "&6" # 邪恶生灵（业障深重，斩杀损心境甚微） - name: "邪祟" min: 61 max: 100 deduction: 0.05 color: "&c" ``` **MythicMobs 怪物配置示例**: ```yaml # MythicMobs/Mobs/your_mob.yml YourMob: Display: '&c邪恶生灵' Health: 100 Damage: 10 Options: zuinie: 80 # 罪孽值（0-100） # 击杀此怪物时，根据罪孽值自动扣除心境 # zuinie: 80 → 邪祟等级 → 扣除 0.05 心境 ``` #### 资质系统配置 ```yaml # plugins/YouLongLibs/zizhi/config.yml zizhi: enabled: true # 首次进入随机范围 initial-range: min: 30.0 max: 70.0 # 10个品阶配置 levels: - name: "九品" min: 0 max: 9 speed-boost: 0.0 color: "&8" - name: "八品" min: 10 max: 19 speed-boost: 0.28 color: "&f" - name: "七品" min: 20 max: 29 speed-boost: 0.40 color: "&b" # ... 更多品阶 - name: "极品" min: 90 max: 100 speed-boost: 0.85 color: "&6" ``` #### 天谴系统配置 ```yaml # plugins/YouLongLibs/tianqian/config.yml tianqian: enabled: true # 击杀增加的天谴值 kill-increment: 2.0 # 被击杀者天谴值达到此值时，击杀者不增加 no-increase-threshold: 80.0 # 状态阈值 thresholds: yellow: 50.0 red: 80.0 thunder: 100.0 # 掉落配置 drop-settings: yellow: chance: 0.10 # 10%触发 item-count: 1 # 掉落1件 red: chance: 0.20 # 20%触发 item-count: 3 # 掉落3件 thunder: chance: 1.0 # 100%触发 item-count: 10 # 掉落10件 # 保护期配置（秒） protection-duration: yellow: 30 red: 60 thunder: 180 # 天雷配置 thunder: countdown: 60 # 60秒倒计时 damage: 1000.0 # 伤害值 clear-exp: true # 清除经验 clear-level: false # 是否清除等级 ``` --- ## 🏗️ 技术架构详解 ### 系统架构图 ``` ┌──────────────────────────────────────────────────────────────────┐ │ YouLongLibs 前置库 │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 心境系统 │ │ 资质系统 │ │ 天谴系统 │ │ │ │ (XinJing) │ │ (ZiZhi) │ │ (TianQian) │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ 罪孽值系统 (ZuiNie) │ │ │ │ │ │ ├─ MythicMobs 集成 │ │ │ │ │ │ ├─ 业障等级配置 │ │ │ │ │ │ └─ 心境扣除计算 │ │ │ │ │ └──────────────────────────────┘ │ │ │ │ │ │ │ │ └─────────────────┼─────────────────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ 事件系统 │ │ │ │ (Event Bus) │ │ │ └──────┬──────┘ │ │ │ │ │ ┌─────────────────┼─────────────────┐ │ │ │ │ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │ │ │ 业务层 │ │ 业务层 │ │ 业务层 │ │ │ │Manager │ │Manager │ │Manager │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ └─────────────────┼─────────────────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ 缓存层 │ │ │ │ (L1 Cache) │ │ │ └──────┬──────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ 存储层 │ │ │ │ (Database) │ │ │ │ SQLite/MySQL│ │ │ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 数据流向 ``` 玩家操作 │ ▼ ┌─────────────────────┐ │ 命令/事件处理 │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ 业务逻辑处理 │ │ (Manager) │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ 缓存更新 │ │ (L1 Cache) │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ 异步数据库写入 │ │ (Async Save) │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ 事件触发 │ │ (Event Dispatch) │ └─────────────────────┘ ``` ### 缓存策略 **三级缓存设计**: 1. **L1 缓存** - 内存缓存（ConcurrentHashMap） - 存储所有在线玩家数据 - 读取速度: < 0.01ms - 自动过期: 玩家离线时清除 2. **L2 缓存** - 定期刷新 - 间隔: 300秒 - 批量写入数据库 - 减少数据库压力 3. **L3 缓存** - 数据库持久化 - SQLite (本地) 或 MySQL (多服) - 异步写入，不卡服 - WAL模式提高并发性能 **缓存一致性保证**: ``` 内存缓存 ←→ 数据库 ↓ 异步同步（300秒） ↓ 玩家离线时强制同步 ``` ### 线程安全设计 **并发控制**: ```java // 1. ConcurrentHashMap 用于存储数据 private val dataCache = ConcurrentHashMap<UUID, PlayerData>() // 2. 读写锁保护关键操作 private val lock = ReentrantReadWriteLock() // 3. 原子操作保证数据一致性 private val counter = AtomicInteger(0) // 4. 异步执行器处理数据库操作 AsyncExecutor.run("task-name") { // 数据库操作在异步线程执行 databaseRepository.save(data) } ``` **线程安全保证**: - 所有公共API都是线程安全的 - 数据库操作异步执行，不阻塞主线程 - 缓存使用ConcurrentHashMap，支持并发读写 - 关键操作使用读写锁保护 ### 性能优化 **1. 异步数据库操作** ``` 主线程: 更新缓存 (< 1ms) 异步线程: 写入数据库 (< 50ms) 结果: 主线程不卡顿 ``` **2. 批量写入** ``` 单次写入: 1条数据 → 1次数据库操作 批量写入: 100条数据 → 1次数据库操作 性能提升: 100倍 ``` **3. 对象池技术** ``` StringBuilder池: 减少GC压力 Map池: 复用对象，减少内存分配 结果: GC暂停时间 < 10ms ``` **4. 索引优化** ```sql -- 数据库索引 CREATE INDEX idx_player_id ON player_data(player_id); CREATE INDEX idx_last_update ON player_data(last_update); ``` ### 可扩展性设计 **模块化架构**: ``` YouLongLibs ├── XinJing Module (可独立使用) ├── ZiZhi Module (可独立使用) ├── TianQian Module (可独立使用) └── Common (共享库) ``` **插件集成**: - PlaceholderAPI - 变量支持 - MythicMobs - 罪孽值系统 - 其他插件 - 通过API调用 --- ## 📊 性能基准测试 ### 测试环境 - **服务器**: Paper / Purpur / Leaf 1.21.8 - **Java**: Java 21 - **内存**: 4GB - **在线玩家**: 100人 - **数据库**: SQLite (WAL模式) ### 测试结果 | 操作 | 平均时间 | 最大时间 | TPS影响 | |-----|---------|---------|--------| | PlaceholderAPI查询 | 0.08ms | 0.15ms | < 0.01% | | 在线玩家数据读取 | 0.01ms | 0.02ms | < 0.01% | | 数据库查询 | 45ms | 80ms | 0% (异步) | | 配置热重载 | 85ms | 120ms | < 0.1% | | 事件触发 | 0.5ms | 1.2ms | < 0.01% | | 内存占用 | 5MB | - | 0.1% | ### 压力测试 **场景**: 1000个玩家同时在线 | 指标 | 结果 | |-----|------| | 内存占用 | ~50MB | | 数据库连接 | 5个 | | 缓存命中率 | 99.8% | | 平均响应时间 | < 1ms | | TPS影响 | < 0.5% | --- ## 🔍 调试工具 ### 调试命令 ``` # 心境系统调试 /xinjing debug info <玩家> - 显示详细信息 /xinjing debug cache <玩家> - 显示缓存状态 /xinjing debug recovery <玩家> - 显示恢复状态 # 资质系统调试 /zizhi debug info <玩家> - 显示详细信息 /zizhi debug cache <玩家> - 显示缓存状态 # 天谴系统调试 /tianqian debug info <玩家> - 显示详细信息 /tianqian debug cache <玩家> - 显示缓存状态 /tianqian debug thunder <玩家> - 显示天雷状态 ``` ### 日志输出 所有系统都支持详细的日志输出，可在配置文件中启用： ```yaml debug: enabled: true log-level: "INFO" # DEBUG, INFO, WARN, ERROR log-file: "plugins/YouLongLibs/debug.log" ``` ### 性能监控 ``` /youlonglibs status - 显示系统状态 /youlonglibs memory - 显示内存使用 /youlonglibs cache - 显示缓存统计 /youlonglibs database - 显示数据库连接 ``` --- ## 📦 安装说明 ### 环境要求 | 项目 | 要求 | 说明 | |------|------|------| | **服务端** | Paper / Purpur / Leaf 1.21.8+ | 推荐最新版本 | | **Java** | Java 21 | 必须 | | **TabooLib** | 6.2.3+ | 自动下载 | | **PlaceholderAPI** | 可选 | 用于变量支持 | | **MythicMobs** | 可选 | 用于心境系统罪孽值 | ### 安装步骤 1. 下载 `YouLongLibs-1.5.1.jar` 2. 将文件放入服务器的 `plugins` 目录 3. 重启服务器 4. 首次启动会自动生成配置文件 5. 根据需要修改配置文件 6. 使用 `/xinjing reload` 等命令重载配置 --- ## 📊 性能指标 ### 基准测试结果 | 操作 | 性能 | 说明 | |-----|------|------| | PlaceholderAPI查询 | < 0.1ms | 从内存缓存读取 | | 在线玩家数据读取 | < 0.01ms | 内存缓存命中 | | 数据库查询 | < 50ms | 异步执行，不卡服 | | 配置热重载 | < 100ms | 不影响在线玩家 | | 内存占用 | ~5MB/1000玩家 | 高效缓存策略 | ### 服务器要求 - **小型服务器**（<100人）：完全无压力 - **中型服务器**（100-500人）：优秀表现 - **大型服务器**（500+人）：建议使用MySQL --- ## 🎯 权限节点 ### 心境系统权限 | 权限节点 | 说明 | 默认值 | |---------|------|--------| | `youlonglibs.xinjing.use` | 使用基础命令 | 所有玩家 | | `youlonglibs.xinjing.admin` | 管理员权限 | OP | ### 资质系统权限 | 权限节点 | 说明 | 默认值 | |---------|------|--------| | `youlonglibs.zizhi.use` | 使用基础命令 | 所有玩家 | | `youlonglibs.zizhi.check` | 查看资质 | 所有玩家 | | `youlonglibs.zizhi.admin` | 管理员权限 | OP | ### 天谴系统权限 | 权限节点 | 说明 | 默认值 | |---------|------|--------| | `youlonglibs.tianqian.use` | 使用基础命令 | 所有玩家 | | `youlonglibs.tianqian.admin` | 管理员权限 | OP | --- ## 📝 常见问题 ### Q1: 如何切换到MySQL数据库？ 编辑配置文件 `config.yml`： ```yaml storage: database: type: "mysql" # 改为 mysql host: "localhost" port: 3306 database: "minecraft" username: "root" password: "your_password" ``` 然后重载配置：`/zizhi reload` ### Q2: PlaceholderAPI变量不显示？ 1. 确认安装了PlaceholderAPI插件 2. 检查控制台是否显示：`PlaceholderAPI 扩展已注册（统一管理）` 3. 使用 `/papi parse me %youlonglibs_zizhi%` 测试变量 ### Q3: 如何自定义资质等级？ 编辑 `zizhi/config.yml`，修改 `levels` 部分，保存后执行 `/zizhi reload` ### Q4: 天雷倒计时可以取消吗？ 可以！管理员使用 `/tianqian set <玩家> 99` 将天谴值降到100以下即可取消倒计时。 --- ## 📥 下载地址 | 项目 | 内容 | |------|------| | **最新版本** | v1.5.1 | | **下载链接** | 本帖下载 | | **文件大小** | 562.61 KB | | **MD5校验** | `02B2A72316E9717EFDC20C9F29EC21C4` | --- ## 🎨 配色方案 ### Minecraft 颜色代码参考 | 代码 | 颜色 | 用途 | |-----|------|------| | `§0` | 黑色 | 分隔线 | | `§1` | 深蓝 | 系统提示 | | `§2` | 深绿 | 成功提示 | | `§3` | 深青 | 信息提示 | | `§4` | 深红 | 警告/危险 | | `§5` | 紫色 | 资质系统 | | `§6` | 金色 | 标题/重要 | | `§7` | 浅灰 | 普通文本 | | `§8` | 深灰 | 次要文本 | | `§9` | 蓝色 | 链接/特殊 | | `§a` | 绿色 | 成功/正常 | | `§b` | 青色 | 信息/提示 | | `§c` | 红色 | 错误/天谴 | | `§d` | 粉色 | 特殊/心境 | | `§e` | 黄色 | 警告/黄名 | | `§f` | 白色 | 数值/强调 | ### 系统配色方案 **心境系统** ``` 正常状态: §a✓ 正常 (心境 > 70) 黄名状态: §e⚠ 黄名 (30 < 心境 ≤ 70) 红名状态: §c✗ 红名 (0 < 心境 ≤ 30) 魔化状态: §4✗ 魔化 (心境 = 0) ``` **资质系统** ``` 九品: §8◆ 九品 (0-9) 八品: §f◆ 八品 (10-19) 七品: §b◆ 七品 (20-29) 六品: §e◆ 六品 (30-39) 五品: §a◆ 五品 (40-49) 四品: §2◆ 四品 (50-59) 三品: §d◆ 三品 (60-69) 二品: §5◆ 二品 (70-79) 一品: §c◆ 一品 (80-89) 极品: §6◆ 极品 (90-100) ``` **天谴系统** ``` 正常: §a✓ 正常 (天谴 < 50) 黄名: §e⚠ 黄名 (50 ≤ 天谴 < 80) 红名: §c✗ 红名 (80 ≤ 天谴 < 100) 天雷: §4⚡ 天雷 (天谴 = 100) ``` --- ## 📸 效果展示 ### 启动界面 ``` [ATTACH type="full" size="560x300"]117542[/ATTACH] ``` ### 游戏内效果展示 #### 心境系统提示 **正常状态** ``` [ATTACH type="full" size="622x96"]117543[/ATTACH] ``` **黄名状态** ``` [ATTACH type="full" size="755x154"]117544[/ATTACH] ``` **红名状态** ``` [ATTACH type="full" size="957x226"]117545[/ATTACH] ``` #### 资质系统提示 **首次进入** ``` [ATTACH type="full" size="503x300"]117546[/ATTACH] ``` **资质突破** ``` [ATTACH type="full" size="920x150"]117547[/ATTACH] ``` **资质查询** ``` [ATTACH type="full" size="682x41"]117548[/ATTACH] ``` --- ## 🔄 更新日志 ### v1.5.1 (2025-10-31) **新增功能**: - ✨ 完整的三大系统实现（心境、资质、天谴） - 🔌 统一PlaceholderAPI扩展（20+变量） - 🌍 中英文双语支持 - ⚡ 高性能缓存系统 **技术特性**: - 🏗️ 分层架构设计 - 🔒 完整线程安全保证 - 📊 详细的调试工具 - 完整的错误处理 --- ## 💬 联系方式 | 项目 | 内容 | |------|------| | **作者** | Mlssya | | **版本** | 1.5.1 | | **更新日期** | 2025-10-31 | | **QQ群聊** | [点击加入【YouLong插件交流群】](https://qm.qq.com/q/TeXXqjesMM) | | **讨论交流** | [点击进入讨论](https://qm.qq.com/q/TeXXqjesMM) | | **问题反馈** | 欢迎在帖子下方留言或加入QQ群反馈 | --- ## 🙏 致谢 感谢以下开源项目的支持： | 项目 | 说明 | |------|------| | [Paper / Purpur / Leaf](https://www.minebbs.com/resources/leaf.9242/) | 高性能Minecraft服务端 | | [TabooLib](https://github.com/TabooLib/TabooLib) | 强大的插件开发框架 | | [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) | 变量占位符支持 | | [MythicMobs](https://www.mythicmobs.net/) | 自定义怪物系统 | --- [/MD]