鹤造工坊

Appearance

读取组件脚本编写 ​

什么是读取组件？ ​

读取组件是插件解析物品 Lore/NBT 的核心模块。当插件检测一件装备时，会调用所有注册的读取组件去解析其中的每一行文本，提取出属性值和条件。

三大读取组件：

组件类型作用问题
数值读取 (ValueReader)从文本中提取属性值「这一行是什么属性？值是多少？」
条件读取 (ConditionReader)判断条件是否满足「这一行的条件是否满足？」
映射读取 (MappingReader)将文本映射为属性列表「这行文本对应哪些属性？」

工作原理 ​

以一件装备为例，假设它的 Lore 如下：

§7物理攻击 +100
§7等级需求: 50
§7生命值 +500

插件的解析流程：

  1. 逐行遍历 Lore 的每一行
  2. 对每一行，按优先级依次调用所有读取组件
  3. 某个读取组件返回「我认识这一行」→ 提取属性值/条件，停止继续检查
  4. 某个读取组件返回 null/false → 「我不认识」，交给下一个组件

例如：

  • §7物理攻击 +100 → NumberValueReader 识别到「物理攻击 +100」，提取属性值
  • §7等级需求: 50 → LevelConditionReader 识别到「等级需求」，判断玩家等级是否≥50
  • §7生命值 +500 → NumberValueReader 再次识别

为什么要自定义读取组件？ ​

系统自带的读取组件覆盖了常见格式。但如果你有特殊需求，比如：

  • 需要读取自定义格式的属性值：攻击力: 100-200.火焰
  • 需要自定义条件：公会等级需求: 5
  • 需要根据物品材质决定属性

那就需要自己编写读取组件脚本。

放置位置 ​

自定义读取组件脚本放在 scripts/reads/ 目录下。插件启动或重载时自动扫描加载。

教程列表 ​

按推荐学习顺序：

  1. 自定义条件读取组件 — 最简单，容易理解
  2. 自定义数值读取组件 — 更灵活
  3. 自定义映射读取组件 — 批量映射

前置知识 ​

编写读取组件前，你需要了解：

关键概念 ​

ReadableLine ​

ReadableLine 是读取组件的核心对象，代表 Lore 或 NBT 中的一行文本。它包含：

  • 原始行文本
  • 去除颜色代码后的纯文本（getClearLine()）
  • 去除过滤符处理后的文本

CacheManager ​

CacheManager 是缓存管理器。因为同一行可能被多个读取组件检查，使用缓存可以避免重复的正则解析。推荐始终通过 CacheManager.getStringList() 来获取解析结果。

优先级（priority） ​

当多个同类型的读取组件都能匹配同一行时，优先级决定了谁先处理。数值越小越优先。读取组件一旦返回了有效结果，就不会再调用优先级更低的组件。