CoreLib 动作

EmakiAttribute 注册的 CoreLib 动作段如下: 段 ID, 参数, 适用场景与用法示例. 使用方式: 按下表选段, 照示例写入配置, 再用各段的成功输出验证结果

前置条件: EmakiAttribute 处于启用状态. 其启动流程会向 CoreLib 动作注册表追加属性, 资源, 标签和同步相关的段, 这些段可以写在支持 CoreLib 管道的配置节点里, 例如 Forge/Strengthen/Cooking/Skills/Item 的动作列表, CoreLib 管道模板, 或由其他插件通过 CoreLib 管道引擎触发

NOTE

这里只记录 EmakiAttribute 注册的段; CoreLib 自带的消息, 命令, 经济, 物品等通用段见 CoreLib 动作系统. 当前段 ID 只使用下表中的规范名, 不再提供历史别名入口. 旧的 attributedamage 现在写作 attribute_damage; 其余段的 id 没有变

目标由 source 决定: 作用于执行者自己写 self, 指定玩家用 player_by_name

段 ID 速查

段 ID	用途	目标要求
attribute_damage	对目标造成一次 Attribute 自定义伤害	REQUIRED_ENTITY
attribute_add	给目标添加限时属性修饰	REQUIRED_ENTITY
attribute_set	设置目标的限时属性修饰	REQUIRED_ENTITY
attribute_remove	清理目标指定 effect_id 效果组内的全部限时属性	REQUIRED_ENTITY
attribute_resource_add	增加目标指定资源的当前值	REQUIRED_ENTITY
attribute_resource_set	设置目标指定资源的当前值	REQUIRED_ENTITY
attribute_resource_remove	扣除目标指定资源的当前值	REQUIRED_ENTITY
attribute_resource_consume	消耗目标指定资源	REQUIRED_ENTITY
attribute_tag_add	按属性标签批量添加限时属性	REQUIRED_ENTITY
attribute_tag_remove	按属性标签移除限时属性	REQUIRED_ENTITY
attribute_tag_clear	按属性标签清理限时属性	REQUIRED_ENTITY
attribute_sync	同步目标或全部在线玩家的属性与资源状态	OPTIONAL
attribute_refresh	刷新 Attribute 缓存, 并同步目标或全部在线玩家	OPTIONAL

除两个同步段外, attribute_damage 与资源段只接受玩家目标; 限时属性与标签段接受任意生物实体 (含非玩家生物), 非生物目标会跳过. attribute_damage 的目标要求虽然声明为 REQUIRED_ENTITY, 但实现只处理 Player, 指向非玩家生物时以 not_player 跳过, 不造成伤害

升级须知: 限时属性行为变化

两条对既有配置可见的变化:

1. 标签入口的复合效果 ID 已消失. attribute_tag_add effect_prefix=poison 过去会写出 poison:physical_attack, poison:movement_speed 等一条条互不相干的顶层记录, 现在改为全部归入 poison 一个效果组. 所以按 poison:physical_attack 这类复合 ID 精确删除的旧配置会失效, 要改成 attribute_remove effect_id=poison; 反过来, 过去删不掉任何东西的 attribute_remove effect_id=poison 现在才真正生效
2. 多个效果组对同一属性 SET 时的胜者已确定. 过去由内部哈希表迭代顺序决定, 同样的配置可能得到不同结果, 也可能随扩容变化; 现在固定为最后写入的那一条生效 (按内部单调序号取最大者), 重复运行结果一样. /ea trace 会把被覆盖的那条显示为"被更高 revision 覆盖"

单属性配置不受影响, 行为逐字不变

attribute_damage

对目标造成一次 Attribute 伤害. 与 CoreLib 内置 damage 的区别: 本段走 EmakiAttribute, 模块的伤害类型, 抗性与战斗快照全部生效

参数	类型	必填	默认值	说明
amount	DOUBLE	是	—	基础伤害值
type	STRING	否	""	伤害类型 ID; 留空使用 EmakiAttribute 的默认伤害类型
cause	STRING	否	CUSTOM	Bukkit EntityDamageEvent.DamageCause, 如 CUSTOM, MAGIC, ENTITY_ATTACK

actions:
  - 'self | attribute_damage amount=25 type=physical cause=CUSTOM'
  - 'looking_at range=15 | attribute_damage amount=40 type=spell cause=MAGIC'

cause 写成无法识别的值时以 INVALID_CONFIG 失败, 不会退回一个错误的 cause 继续打伤害; 空值等同 CUSTOM. 伤害被模块规则拒绝时以 REJECTED 失败. 成功时输出 damage_type

限时属性

effect_id 是效果组 ID, 不是单条效果的 ID. 同一个 effect_id 下可以放多个属性, 它们互不覆盖, 一起到期, 也能被 attribute_remove 一次整组清掉. attribute_add 与 attribute_set 决定组内该属性这一条是加算还是覆盖, 这也是两者分成独立段而不是共用一个 mode 参数的原因

actions:
  - 'self | attribute_add effect_id=buff_strength attribute=physical_attack value=10 duration_ticks=200t'
  - 'self | attribute_add effect_id=buff_strength attribute=physical_crit_rate value=5 duration_ticks=200t'
  - 'self | attribute_remove effect_id=buff_strength'

上例的两条 attribute_add 进同一组, attribute_remove 一次清掉两个属性

attribute_add / attribute_set

两个段的参数相同

参数	类型	必填	默认值	说明
effect_id	STRING	是	—	效果组 ID; 重复使用同一个 ID 会把多个属性归入同一组
attribute	STRING	是	—	属性 ID; 未注册时以 INVALID_CONFIG 失败
value	DOUBLE	是	—	修饰值; NaN 与 ±Inf 以 INVALID_CONFIG 失败
duration_ticks	DURATION	是	—	持续时间; 支持 20t, 1s, 1000ms, 纯数字按 tick 处理
stack_mode	STRING	否	属性定义的 temporary_stack_mode	与组内同属性已有效果的合并方式: REPLACE 覆盖, STACK 数值与剩余时间相加. 写入没声明的值以 INVALID_CONFIG 失败

actions:
  - 'self | attribute_add effect_id=forge_bonus attribute=physical_attack value=12 duration_ticks=10s'
  - 'self | attribute_set effect_id=arena_buff attribute=physical_attack value=30 duration_ticks=200t'
  - 'self | attribute_add effect_id=forge_bonus attribute=physical_attack value=3 duration_ticks=10s stack_mode=STACK'

attribute_remove

参数	类型	必填	默认值	说明
effect_id	STRING	是	—	要清理的效果组 ID; 该组内全部属性一起移除

actions:
  - 'self | attribute_remove effect_id=arena_buff'

三个段的 effect_id 与 attribute 都会做 id 归一化. effect_id 为空时以 INVALID_CONFIG 失败; 目标不是生物实体时以 not_living_entity 跳过 (非玩家生物同样可用). 目标身上没有该组时以 skipped 而不是成功返回. 成功时输出 effect_id, attribute, value, duration_ticks, status, affected_count, existed, remaining_ticks, 其中 status 取 APPLIED / REPLACED / STACKED / REMOVED

资源

四个资源段会通过 EmakiAttribute 的资源同步边界修改玩家资源的当前值. 它们共用同一组参数

参数	类型	必填	默认值	说明
resource	STRING	是	—	资源 ID, 如 health, mana
amount	DOUBLE	是	—	操作数量

段 ID	计算方式
attribute_resource_add	当前值 + amount
attribute_resource_set	直接设为 amount
attribute_resource_remove	当前值 - amount, 最低为 0
attribute_resource_consume	与 attribute_resource_remove 完全相同

attribute_resource_consume 与 attribute_resource_remove 的算式一致, 保留两个 id 是因为已有配置按名字引用它们; 两者共用同一份实现

最终值仍会按资源定义的同步规则截断, 所以 add 不会超过上限

actions:
  - 'self | attribute_resource_add resource=mana amount=10'
  - 'self | attribute_resource_set resource=health amount=20'
  - 'self | attribute_resource_remove resource=health amount=5'
  - 'self | attribute_resource_consume resource=mana amount=20'

resource 会做 id 归一化; 指向没加载的资源时以 INVALID_CONFIG 失败. 成功时输出 resource, operation, amount, old_value, new_value, current_max

标签限时属性

tag 指向一组配置在一起的属性, 一次调用即可施加整套增益, 无需逐项列出

attribute_tag_add

参数	类型	必填	默认值	说明
tag	STRING	是	—	属性标签, 不区分大小写
value	DOUBLE	是	—	对每个命中属性施加的修饰值
duration_ticks	DURATION	是	—	持续时间
effect_prefix	STRING	否	tag:<tag>	整套命中属性归入的效果组 ID; 为空时用 tag:<标签>
stack_mode	STRING	否	""	叠加模式: REPLACE 或 STACK. 为空时各属性用自身的 temporary_stack_mode; 写了无法识别的值以 INVALID_CONFIG 失败

actions:
  - 'self | attribute_tag_add tag=DEBUFF value=-5 duration_ticks=5s effect_prefix=poison stack_mode=REPLACE'

上例命中的全部属性都进 poison 这一个组, 所以可以直接用 attribute_remove effect_id=poison 整组清掉

attribute_tag_remove / attribute_tag_clear

参数	类型	必填	默认值	说明
tag	STRING	是	—	要移除限时属性的属性标签

actions:
  - 'self | attribute_tag_remove tag=DEBUFF'
  - 'self | attribute_tag_clear tag=BUFF'

这两个段行为完全一致, 都按标签移除. 这个重复是从旧实现保留下来的: 猜测 clear 原本想做什么 (大概是清掉全部标签) 并据此改动, 会改变现有配置依赖的行为, 所以没有动它

tag 为空时以 INVALID_CONFIG 失败; 没有任何属性带该标签, 或目标身上没有对应效果时以 skipped 返回, 而不是报成功. 三个段成功时都输出 tag, effect_id, status 与 count (命中并处理的属性条数)

同步

两个段都只有一个参数, 区别在默认值与是否清缓存

段 ID	参数	类型	默认值	说明
attribute_sync	all	BOOLEAN	false	重算属性值, 不清缓存. 默认只处理目标
attribute_refresh	all	BOOLEAN	true	先清掉模块缓存再重算, 是改完属性配置后该跑的段. 默认处理全部在线玩家

actions:
  # 只同步自己
  - 'self | attribute_sync'
  # 同步全部在线玩家, 不需要目标, 可省略 source
  - 'attribute_sync all=true'
  # 配置改完后清缓存并全服重算
  - 'attribute_refresh'
  # 只对自己清缓存重算
  - 'self | attribute_refresh all=false'

这两个段的目标要求是 OPTIONAL 而不是 REQUIRED_ENTITY, 因为 all=true 根本不需要目标; all=false 的路径自己检查玩家, 拿不到玩家时跳过

它们也是本模块唯一线程域随参数变化的段: all=true 要遍历在线玩家列表, 跑在服务端全局域上; all=false 只碰单个实体. all 的值写成占位符时无法在规划期读出来, 这时按该段自己的默认值判定域, 所以 attribute_refresh 会按全局域规划

成功时输出 all, all=false 时还会带上 player

使用提示

• 除 attribute_sync all=true 与 attribute_refresh all=true 外, 这些段都需要玩家目标
• 如果需要让 MythicMobs 技能直接给目标生物添加或清除限时属性, 请使用 MythicMobs 集成 中的 emaki_attribute_add, emaki_attribute_remove, emaki_attribute_add_tag, emaki_attribute_clear_tag. 那些是 MythicMobs 机制, 不是 CoreLib 段
• duration_ticks 使用 CoreLib DURATION 解析, 20t, 1s, 1000ms 都可用; 纯数字按 tick 处理
• 相关服务还没就绪时, 段以 MISSING_CONTEXT 失败, 而不是不报错地跳过