更新日志

当前版本线

• EmakiCoreLib: 3.4.0
• EmakiAttribute: 3.3.0
• EmakiForge: 3.3.0
• EmakiStrengthen: 3.4.0
• EmakiCooking: 2.2.0
• EmakiGem: 1.2.0
• EmakiSkills: 1.1.0

运行环境基线: Java 25 (GraalVM) · Spigot API 1.21.11-R0.1-SNAPSHOT

---

3.4.0 / 2.2.0 — 自定义方块集成与 PDC 属性 API 重构

EmakiCoreLib — 自定义方块桥接体系 (CustomBlockBridge)

新增 CustomBlockBridge 接口，让三种自定义方块插件共用同一套方块识别 API：

桥接实现	对接插件
CraftEngineBlockBridge	CraftEngine
ItemsAdderBlockBridgeProvider	ItemsAdder
NexoBlockBridgeProvider	Nexo

接口方法：available()、isCustomBlock(Block)、identifyBlock(Block)、matches(Block, String)。三个实现都是软依赖——对应插件没装时 available() 返回 false，不会报错。

EmakiCoreLib — PDC 属性 API 重构

ReflectivePdcAttributeGateway 重构为 PdcAttributeGateway，不再使用反射，改为通过 Bukkit ServicesManager 发现 PdcAttributeApi 服务实例。API 方法不变：write、clear、readAll、copyPayloads、registerSource、unregisterSource。

EmakiCoreLib — 物品源解析器重构

物品源解析器从反射式实现（Reflective*）改为直接调用各插件 API。CraftEngine 解析器额外监听 CraftEngineReloadEvent，在重载后自动刷新物品表。

EmakiCooking — 新增 ItemsAdder 和 Nexo 自定义方块工位支持

CookingBlockMatcher 现在支持四种方块来源类型：

来源类型	匹配方式
VANILLA	比较 Material
CRAFTENGINE	委托 CraftEngineBlockBridge
ITEMSADDER	委托 ItemsAdderBlockBridge
NEXO	委托 NexoBlockBridge

新增 CraftEngineCookingStationListener，监听 CraftEngine 的 CustomBlockInteractEvent 和 CustomBlockBreakEvent。EmakiCooking 的软依赖新增 ItemsAdder 和 Nexo。

EmakiAttribute — weight → score 术语重命名

AttributeBalanceRegistry 内部字段从 weights 重命名为 scores，对应方法 weightOf → scoreOf、weights → scores。

版本号变更

模块	旧版本	新版本
EmakiCoreLib	3.3.0	3.4.0
EmakiCooking	2.1.0	2.2.0
EmakiStrengthen	3.3.0	3.4.0
EmakiSkills	1.0.0	1.1.0

---

EmakiCoreLib / EmakiSkills — 随机文本配置与物品渲染增强

EmakiCoreLib — 表达式引擎新增随机文本配置

表达式引擎新增 random_text 字符串配置类型，支持从候选行列表中随机抽取指定数量的文本行。适用于随机词条、随机描述等场景。

random_bonus_lines:
  type: "random_text"
  rolls: 2
  allow_duplicates: false
  lines:
    - "物理攻击: +{物理攻击}"
    - "物理防御: +{物理防御}"
  variables:
    物理攻击:
      type: "range"
      min: 2
      max: 6

• rolls 支持数值配置类型（常量、range、expression 等），可以让抽取次数随等级变化
• variables 支持局部变量定义，每个变量支持完整的数值配置类型
• 候选行列表字段支持 lines、values、options、texts 四种别名

同时新增字符串配置求值 API：evaluateStringConfig 和 evaluateStringLinesConfig，用于对复杂文本配置对象进行求值。

EmakiCoreLib — 装配系统 Lore 渲染增强

结构化展示模板解析器（StructuredPresentationTemplateResolver）现在对 Lore 行使用表达式引擎的字符串配置求值，这意味着 lore_sections 的 lines 字段现在支持 random_text 等复杂文本配置类型，不再局限于简单的字符串模板替换。

EmakiCoreLib — 物品组件名称写入

新增 SpigotItemComponentNameWriter，通过 minecraft:custom_name 组件写入物品名称，支持物品翻译键和人性化名称生成。这是内部实现优化，不影响配置 API。

EmakiSkills — 技能参数新增 random_text 类型

技能参数系统新增 random_text 参数类型（别名：random_text_lines、random_lines、random_line、text_lines），支持在技能定义中配置随机文本参数，抽取结果作为字符串注入 MythicMobs。

EmakiSkills — expression 参数类型支持嵌套变量

expression 类型参数现在支持通过 variables 字段定义嵌套变量，每个嵌套变量本身也是一个数值配置对象。这让复杂的公式可以拆分成更易读的部分：

damage:
  type: "expression"
  expression: "{base_damage} + {level_bonus}"
  variables:
    base_damage:
      type: "constant"
      value: 18
    level_bonus:
      type: "expression"
      expression: "({level} - 1) * 4"

---

EmakiSkills — 技能等级与参数系统

新增技能等级和参数系统，技能可以升级，参数随等级自动变化。

技能参数

• 技能定义新增 skill_parameters 节点，支持 number、string、boolean 三种参数类型
• 数值参数支持公式计算（如 18 + ({level} - 1) * 4），随等级自动变化
• 参数在释放技能时自动注入 MythicMobs，通过 <skill.var.参数名> 引用
• 自动注入 5 个内置变量：emaki_skill_id、emaki_skill_level、emaki_trigger_id、emaki_is_passive、emaki_has_target

技能升级

• 技能定义新增 upgrade 节点，配置最大等级、经济费用、成功率和材料需求
• 支持按等级配置不同的费用、材料、成功率和参数覆盖
• 升级失败可配置惩罚（none 或 downgrade）
• 扣费失败时自动退还已扣除的金币和材料

新增命令

• /eskills upgrade <技能ID> — 玩家自助升级技能
• /eskills level get/set/add <玩家> <技能> [值] — 管理员等级管理

---

EmakiSkills — 被动技能系统

新增被动技能支持。被动技能由游戏事件自动触发，不需要施法模式和槽位绑定。

新增内容

• trigger_type 字段：技能定义新增 trigger_type: "passive" 标记被动技能
• passive_triggers 字段：声明被动技能响应的事件列表
• 22 种被动触发器：攻击、受伤、死亡、击杀、射箭、三叉戟、方块交互、物品丢弃、潜行、传送、定时等
• passive_trigger_settings.timer_interval_ticks：定时触发器的检查间隔配置
• 被动技能触发时自动传递事件目标给 MythicMobs（如被攻击的实体作为 @target）

被动技能示例

id: attack_passive
trigger_type: "passive"
passive_triggers:
  - "attack"
mythic_skill: "ExampleAttackPassive"
cooldown_ticks: 40

主动 vs 被动

维度	主动技能	被动技能
触发方式	施法模式 + 按键	游戏事件自动触发
槽位绑定	需要	不需要
GUI 展示	可装备到槽位	不出现在技能池
冷却/资源	✅	✅

---

3.3.0 性能优化与依赖升级

运行环境升级

Java 编译目标从 21 升级到 25，推荐使用 GraalVM 25 运行。

EmakiCoreLib — Caffeine 缓存替换

通用缓存 CacheManager 从手写的 LinkedHashMap + ReentrantReadWriteLock 替换为 Caffeine。原实现的 get() 持有 writeLock 导致所有读操作串行化，Caffeine 使用分段锁实现真正的高并发读取。

EmakiCoreLib — 经济桥接迁移至 ExcellentEconomy

CoinsEngine 已更名为 ExcellentEconomy，经济提供者 ID 从 coinsengine 改为 excellenteconomy。API 获取方式改为通过 Bukkit ServicesManager 查找，不再依赖具体插件主类。

迁移注意

配置中的 provider: coinsengine 需要改为 provider: excellenteconomy，动作中的 provider=coinsengine 同理。

EmakiCoreLib — 表达式引擎双层缓存

表达式预编译缓存从单层 ThreadLocal 升级为 L1（ThreadLocal，256 条/30 分钟 TTL）+ L2（全局 ConcurrentHashMap，1024 条）双层架构，跨线程共享编译结果。

EmakiCoreLib — 虚拟线程支持

AsyncTaskScheduler 新增 forPluginVirtual 工厂方法，支持通过 Java 虚拟线程执行异步任务。虚拟线程仅用于无 Bukkit API 访问的纯计算任务，所有世界/实体操作仍通过 BukkitScheduler 同步。

EmakiAttribute — PDC 热路径内存化

攻击冷却、合成伤害标记、伤害类型覆盖三个高频状态从 PDC 读写迁移到 ConcurrentHashMap 内存缓存，消除了每次伤害事件的 NBT 序列化开销。

EmakiAttribute — 伤害计算缓存优化

DamageCalculationCache 的内部 BoundedCache 替换为 Caffeine，缓存 Key 中的 double 字段改为 long（doubleToRawLongBits），签名字符串改为 long hash，大幅降低缓存查询开销。

EmakiCooking — 配方查找缓存

CookingRecipeService 新增 parsedSourceCache，缓存已解析的 ItemSource 对象，避免每次 findByInput 重复解析配方输入源。

EmakiSkills — 触发器索引

PlayerSkillProfile 新增 bindingByTrigger 索引，触发器查找从 O(n) 线性扫描降为 O(1) 哈希查找。

DamageResult — 紧凑构造器增强

DamageResult record 的紧凑构造器增加了 damageTypeId 的 null 检查和 finalDamage 的非负约束。

---

3.3.0 / 1.2.0 更新

EmakiAttribute — 临时属性

新增 TemporaryAttributeService，可以给玩家附加带过期时间的临时属性。两种模式：

• ADD — 在现有属性值上叠加，同一个 effectId 重复调用会累加数值并刷新过期时间
• SET — 直接覆盖属性值，后写入的覆盖先写入的

临时属性过期后自动移除，属性快照会立即刷新。过期检查间隔为 250ms，由独立的守护线程处理。

配套新增了 temporary_attribute 动作，可以在动作系统中直接使用：

actions:
  - "temporary_attribute mode=add effect_id=buff_atk attribute=physical_attack value=50 duration=200"
  - "temporary_attribute mode=set effect_id=override_def attribute=physical_defense value=100 duration=100"
  - "temporary_attribute mode=remove effect_id=buff_atk"

插件关闭时会自动清理所有临时属性数据。

EmakiAttribute — MMOItems 桥接改进

MMOItems 桥接从反射调用改为直接 API 调用，不再依赖 MMOItems 的内部实现细节。这意味着 MMOItems 版本更新时桥接不容易失效了。

EmakiSkills — 施法模式改为 F 键

施法模式的入口键固定为 F 键（PlayerSwapHandItemsEvent）。之前的 auto 和 g 选项已移除。

原因：G 键是客户端本地按键，Spigot 服务端无法监听到，ProtocolLib 和 PacketEvents 也拿不到这个事件。F 键（交换主副手）是服务端能可靠捕获的按键，所以改为固定使用 F 键。

cast_mode:
  # F 键用于进入/退出施法模式
  entry_key: "f"
  restore_last_state_on_join: true

注意

如果你之前配置了 entry_key: "auto" 或 entry_key: "g"，升级后会自动变为 "f"。F 键原本的交换主副手功能会被施法模式拦截（事件被取消）。

EmakiSkills — 触发器有效性验证

同步技能池时，系统现在会额外检查绑定的触发器是否仍然有效（triggerRegistry.isEnabled()）。如果某个触发器在配置中被禁用了，对应的槽位绑定会被自动清除，避免出现"绑了技能但按键没反应"的情况。

锻造 / 强化 / 宝石 — 技能 ID 写入

三个装备成长模块都新增了 skill 效果类型。配方中的材料、强化的星级阶段、宝石定义都可以声明技能 ID，锻造/强化/镶嵌完成后会自动把技能 ID 写入产物的 PDC（通过 ReflectiveSkillPdcGateway）。

这样一来，装备的技能不再需要手动通过命令写入 PDC，配方本身就能定义"这把武器带什么技能"。

锻造材料示例：

effects:
  - type: skill
    skills:
      - "fireball"
      - "ice_bolt"

强化星级阶段示例：

stars:
  5:
    effects:
      - type: skill
        skills:
          - "flame_burst"

宝石定义示例：

effects:
  - type: skill
    skill: "mana_shield"

EmakiCoreLib — 技能 PDC 网关

新增 ReflectiveSkillPdcGateway，负责在物品的 PDC 中读写技能 ID 列表。键为 emaki_skills:item.skills.ids，值为分号分隔的技能 ID 字符串。

这个网关被 Forge、Strengthen、Gem 三个模块共同使用，确保技能 ID 的写入格式一致。

版本号变更

模块	旧版本	新版本
EmakiCoreLib	3.2.0	3.3.0
EmakiAttribute	3.2.0	3.3.0
EmakiForge	3.2.0	3.3.0
EmakiStrengthen	3.2.0	3.3.0
EmakiGem	1.1.0	1.2.0

---

3.2.0 更新

这轮发布的主线是把 Emaki 全系列收口到结构化展示、纯 Spigot 运行口径和更清晰的配置边界上。最大的变化在于物品重建的思路——以前是"反向修改最终文本"，现在改成了"修改对应 namespace 的 layer state，再由 CoreLib 重新渲染整件物品"。这意味着各模块不再直接操作物品的 name/lore 文本，而是各自维护自己那一层的数据，最终展示由 CoreLib 统一合成。

重点改动

EmakiCoreLib

• 结构化展示（Structured Presentation）成为唯一的运行主链。旧的展示编译器、Lore 搜索插入链和 edititem 动作已从当前运行路径移除——如果你之前用了这些，需要迁移
• 原版物品/方块来源只接受 minecraft-、mc-、v- 或裸 ID 四种写法，minecraft:xxx 不再被识别
• 新增 CraftEngine 方块桥接，原版材质解析也统一了口径
• Adventure、exp4j、BoostedYaml 改为通过 plugin.yml libraries 声明加载，不再打包进 jar

EmakiAttribute

• 伤害热路径做了职责拆分：结算、回复、消息、synthetic 反馈各自独立成模块，方便排查问题和后续扩展
• preview 命令会保留原版物品的本地化名称，不再显示内部 ID
• PDC 条件文件的写法统一改为 conditions（旧的 checks 仍可读取，但建议迁移）

EmakiForge

• 配方 DSL 统一为根级 forge_capacity + result.output_item 结构，旧的 target_item 输出结构不再支持
• 资源编辑器的文本输入改为命令式：/emakiforge input <内容|cancel>，不再依赖聊天监听
• condition_type 如果填了非法值，加载阶段就会直接拒绝并报错，不会静默忽略

EmakiStrengthen

• 默认配方和展示完全迁移到顶层 structured_presentation
• 强化材料消耗改为 GUI-only 规则——所有参与判定的材料必须先放进 GUI，不再从背包自动补材
• 新增 /emakistrengthen clearstate 命令，以及可配置的本地/全服广播阈值

EmakiGem

• GUI 入口统一为 /emakigem gui [inlay|extract|open|upgrade]
• 默认宝石和开孔器改为 item_source 驱动，不再硬编码物品定义
• give 子命令已移除（用 CoreLib 的物品源 give 代替）
• 修复了失败动作不触发和升级关闭时返还异常的问题

升级建议

注意

升级前务必备份自定义配置、语言文件和默认资源副本，尤其是 Strengthen / Forge / Gem 的展示和 GUI 相关 YAML。这个版本的配置结构变动较大，没有备份的话回退会很麻烦。

具体迁移清单：

• 原版物品/方块来源：全部改为 minecraft-xxx、mc-xxx、v-xxx 或裸 ID 写法
• 自定义展示：迁移到 structured_presentation；旧的 presentation、name_operations、lore_operations、edititem 等已不再是受支持的主路径
• Forge 配方：改用根级 forge_capacity + result.output_item
• Strengthen 材料：确认所有材料都通过 GUI 放入，旧的背包自动补材行为已移除
• Attribute 条件配置：新配置统一用 conditions，checks 只保留兼容读取
• CoreLib 运行库：首次部署 3.2.0 时确认服务端允许通过 plugin.yml libraries 下载依赖

兼容性说明

• 当前发布基于 Java 21 + Spigot API 1.21.11-R0.1-SNAPSHOT
• CoreLib 只保留结构化展示主路径；原版物品/方块来源只接受四种规则（minecraft-、mc-、v-、无前缀）
• Forge 的旧 target_item 输出结构和 Strengthen 的旧 presentation schema 不再被识别
• EmakiGem 为闭源模块，1.1.0 的变更基于 .codex/change-reports 汇总