条件与 Lore 格式

条件系统

条件文件放在 conditions/ 目录下，用来控制"物品上的属性什么时候生效"。比如你可以设置一把武器只有绑定的玩家才能获得属性加成，或者要求玩家达到一定等级才能使用某件装备。

当物品不满足条件时，它的属性不会被计入玩家的属性快照——相当于这件装备"没有属性"。

条件文件格式

enabled: true
source_id: "forge"
condition_type: pdc_meta
invalid_as_failure: true
conditions:
  - key: "emaki:bind_player"
    operator: "=="
    value: "%player_name%"

字段说明

字段	类型	必填	默认值	说明
enabled	boolean	否	true	是否启用此条件。设为 false 可以临时禁用而不用删文件
source_id	String	是	—	关联的 PDC 属性源 ID。条件只对这个源写入的属性生效
condition_type	String	是	—	条件类型：pdc_meta 或 lore_regex
invalid_as_failure	boolean	否	true	当条件数据不存在时是否视为失败。比如物品上没有 emaki:bind_player 这个 PDC 键，是直接判定失败还是跳过
conditions	List	是	—	条件列表，所有条件都满足时才算通过

pdc_meta 类型

从物品的 PDC（PersistentDataContainer）元数据中读取值，和预期值做比较。

condition_type: pdc_meta
conditions:
  - key: "emaki:bind_player"
    operator: "=="
    value: "%player_name%"
  - key: "emaki:required_level"
    operator: "<="
    value: "%player_level%"

支持的运算符：==、!=、>、>=、<、<=

这是最常用的条件类型。PDC 数据是存在物品 NBT 里的，不会显示在 Lore 中，适合做后端校验。

lore_regex 类型

用正则表达式匹配物品 Lore 行，从中提取值进行比较。适合那些把条件信息写在 Lore 里的物品。

condition_type: lore_regex
conditions:
  - pattern: "绑定玩家: (.+)"
    group: 1
    operator: "=="
    value: "%player_name%"
  - pattern: "需要等级: (\\d+)"
    group: 1
    operator: "<="
    value: "%player_level%"

lore_regex 捕获组

group 指定正则表达式的捕获组编号。group: 0 是整个匹配结果，group: 1 是第一个括号里捕获的内容。上面的例子中，"绑定玩家: (.+)" 匹配到 "绑定玩家: Steve" 时，group: 1 就是 "Steve"。

内置条件文件

插件默认带了几个条件文件，覆盖常见的使用场景：

文件名	source_id	条件类型	用途
default_bind.yml	—	pdc_meta	绑定玩家检查——验证物品是否绑定到当前玩家
default_equipment_level.yml	—	pdc_meta	装备等级检查——验证玩家等级是否满足装备要求
forge.yml	forge	pdc_meta	锻造源条件，检查锻造相关的 PDC 元数据
strengthen.yml	strengthen	pdc_meta	强化源条件，检查强化相关的 PDC 元数据

表达式占位符

条件的 value 字段支持以下占位符，会在运行时替换为实际值：

占位符	说明
%value%	从物品中读取到的实际值
%player_level%	玩家等级
%player_name%	玩家名称
$1、$2、...	正则表达式捕获组（仅 lore_regex 类型可用）

条件执行顺序

条件按文件加载顺序执行。需要注意的是，当 invalid_as_failure: true 时，如果物品上根本没有对应 source_id 的 PDC 数据，条件会直接判定为失败——物品的属性不会被计入快照。所以如果你的条件只针对特定来源的物品，确保 source_id 设置正确，避免误伤其他来源的物品。

Lore 格式系统

Lore 格式文件放在 lore_formats/ 目录下，做两件事：

1. 控制属性值在物品 Lore 中怎么显示（比如 +100 物理攻击 还是 +15% 物理伤害加成）
2. 定义解析规则，让系统能从 Lore 文本中反向提取出属性值

Lore 格式文件格式

id: default_flat
format: "{sign}{value} {name}"
precision: 2
read_priority: 50
read_patterns:
  - "([+-]?\\d+\\.?\\d*) (.+)"

字段说明

字段	类型	必填	默认值	说明
id	String	是	—	格式唯一标识
format	String	否	"{sign}{value} {name}"	显示格式模板。{sign} 是正负号，{value} 是数值，{name} 是属性名
precision	int	否	2	数值精度（小数位数）
read_priority	int	否	按 ID 自动分配	解析优先级，数值越大越先尝试匹配
read_patterns	List	否	[]	解析用的正则表达式列表

read_patterns 别名

read_patterns 字段也可以写成 read_pattern、lore_patterns 或 lore_pattern，效果一样，都会被合并处理。

内置 Lore 格式

ID	格式	read_priority	示例
default_flat	{sign}{value} {name}	50	+100 物理攻击
default_percent	{sign}{value}% {name}	100	+15% 物理伤害加成
default_regen	{sign}{value}/s {name}	80	+5/s 生命回复
default_resource	{sign}{value} {name}	60	+200 生命值

为什么 default_percent 优先级最高

read_priority 决定解析时的尝试顺序。default_percent（100）最先匹配，是因为百分比格式（带 %）比固定值格式更具体。如果让固定值格式先匹配，+15% 物理伤害加成 可能会被错误地解析为固定值 15，丢掉百分比语义。

Lore 解析流程

当系统需要从物品 Lore 中读取属性时，解析流程如下：

物品 Lore 行
    ▼
按 read_priority 降序遍历所有 Lore 格式
    ▼
对每个格式，尝试用 read_patterns 匹配 Lore 行
    ▼
匹配成功 → 提取属性名称和数值
    ▼
通过属性定义的 lore_patterns 反向验证属性 ID
    ▼
写入属性快照

完整解析示例

假设物品 Lore 包含一行：+150 物理攻击

1. default_percent（priority=100）尝试匹配 → 不含 %，匹配失败
2. default_regen（priority=80）尝试匹配 → 不含 /s，匹配失败
3. default_resource（priority=60）尝试匹配 → 匹配成功，提取值 150，名称 物理攻击
4. 遍历属性定义，找到 physical_attack 的 lore_patterns 包含 物理攻击
5. 将 physical_attack = 150 写入物品属性快照

注意第 4 步的反向验证：即使正则匹配成功了，还要确认提取出的名称确实对应某个已定义的属性。这样可以避免 Lore 中的非属性文本被误解析。