> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/cn-er/pei-zhi/info-of-abilities/entity-state.md). # 实体状态能力 本页面会将每一种已注册能力作为完整条目进行说明。所有条目也支持[能力](/cn-er/pei-zhi/info-of-abilities.md)页面中介绍的通用能力字段。 ## 本页面的注册键 * `set_attribute` * `refresh_attribute` * `set_health` * `set_absorption` * `set_air` * `set_food` * `set_velocity` * `set_invulnerable` * `potion_effect` * `remove_potion_effect` * `extend_potion_effects` * `potion_cloud` * `freeze` * `fire` * `experience` *** ## `set_attribute` \*\*用途：\*\*设置某项 Bukkit 属性的基础值，或设置一项 EnchantmentReform 自定义属性值。 \*\*上下文：\*\*默认 `target` 为 `SOURCE`；选中的实体必须提供所请求的属性。 ### 字段 | 字段 | 默认值 | 说明 | | ----------- | ------------ | ----------------------------------------------- | | `attribute` | `max_health` | Bukkit 属性键（例如 `minecraft:max_health`）或自定义属性 ID。 | | `value` | `1` | 新值；支持使用 `{now}` 表示当前值，使用 `{max}` 表示其最大值。 | ### 示例 ```yaml type: set_attribute target: SOURCE attribute: minecraft:max_health value: '{max} * 1.25' ``` ### 行为与限制 * 修改最大生命值时，当前生命值会由平台实现进行调整或限制。 * 此能力修改的是基础值，而不是添加临时属性修改器。 * 自定义属性的目标必须是玩家。结果会取整、限制在配置范围内，并保存到玩家 PDC。 *** ## `refresh_attribute` \*\*用途：\*\*添加或刷新一个临时属性修改器，并防止重复叠加相同副本。 \*\*上下文：\*\*默认 `target` 为 `SOURCE`；目标必须是生物实体，并提供所请求的属性。 ### 字段 | 字段 | 默认值 | 说明 | | ----------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `attribute` | `minecraft:max_health` | Bukkit 属性的命名空间键或自定义属性 ID。 | | `operation` | `ADD_NUMBER` | 支持 `ADD_VALUE`、`ADD_MULTIPLIED_BASE`、`ADD_MULTIPLIED_TOTAL`，也兼容旧 Bukkit 名称 `ADD_NUMBER`、`ADD_SCALAR` 和 `MULTIPLY_SCALAR_1`。 | | `amount` | `0` | 修改器数值。 | | `duration` | 来源有效期 | 可选的存在时间，单位为 Tick，最小值限制为 2。附魔或自定义物品提前失效时也会立即移除修改器。 | ### 示例 ```yaml type: refresh_attribute target: SOURCE attribute: minecraft:movement_speed operation: ADD_NUMBER amount: 0.03 duration: 100 ``` ### 行为与限制 * 修改器身份由实体 UUID、能力 ID、Ability 配置路径、来源槽位和属性共同确定，因此同一来源再次执行会刷新其修改器，允许重复的不同来源则可独立叠加。 * 代次检查可以防止较早安排的移除任务删除已经被刷新的修改器。 * 无论是否配置 `duration`，附魔或自定义物品失效时都会立即移除修改器；未配置 `duration` 时，来源失效就是正常的生命周期终点。 * 实体卸载或插件卸载时也会移除修改器；最大生命值降低时，当前生命值会受到限制。 * 对于自定义属性，目标必须是玩家。Ability 会刷新一个仅存在于运行时的 modifier，并在到期或来源失效时移除，不会持久化到 PDC。 *** ## `set_health` \*\*用途：\*\*设置生物实体的当前生命值。 \*\*上下文：\*\*默认 `target` 为 `SOURCE`；目标必须是仍然存活的生物实体。 ### 字段 | 字段 | 默认值 | 说明 | | -------- | --- | ------------------------------------- | | `amount` | `1` | 新的生命值；支持当前生命值、最大生命值，以及实现中记录的触发器伤害占位符。 | ### 示例 ```yaml type: set_health target: SOURCE amount: 'min({max-health}, {health} + 6)' ``` ### 行为与限制 * 数值会限制在合法的生命值范围内，并受到实现中的硬性上限约束。 * 设置为零可能会杀死该实体。 *** ## `set_absorption` \*\*用途：\*\*设置可受伤害实体的伤害吸收量。 \*\*上下文：\*\*默认 `target` 为 `SOURCE`；目标必须是仍然存活的可受伤害实体。 ### 字段 | 字段 | 默认值 | 说明 | | -------- | ---- | ---------------------------------------------------------- | | `amount` | `10` | 新的伤害吸收值；支持使用 `{health}` 表示当前吸收量，使用 `{max-health}` 表示最大吸收量。 | ### 示例 ```yaml type: set_absorption target: SOURCE amount: 'min({max-health}, {health} + 4)' ``` ### 行为与限制 * 数值首先被硬性限制为不超过 2048，然后再受实体最大吸收量限制。 * 已死亡或生命值为零的实体会被跳过。 *** ## `set_air` \*\*用途：\*\*设置实体剩余的空气 Tick。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；选中的实体必须是生物实体。 ### 字段 | 字段 | 默认值 | 说明 | | -------- | ----- | --------------------------------- | | `amount` | 当前空气值 | 新的剩余空气值；支持 `{air}` 和 `{max-air}`。 | ### 示例 ```yaml type: set_air target: TARGET amount: 0 ``` ### 行为与限制 * 数值会限制在实现允许的下限和最大空气值之间。 * 平台支持时，负空气值可以立即继续溺水行为。 *** ## `set_food` \*\*用途：\*\*设置玩家的饥饿值和饱和度。 \*\*上下文：\*\*默认 `target` 为 `SOURCE`；选中的实体必须是玩家。 ### 字段 | 字段 | 默认值 | 说明 | | ------------ | --- | --------------------------------------- | | `food` | `1` | 新的饥饿值，限制在 `0..20`；`{original}` 表示当前饥饿值。 | | `saturation` | `0` | 新的饱和度，限制在 `0..20`；`{original}` 表示当前饱和度。 | ### 示例 ```yaml type: set_food target: SOURCE food: 20 saturation: 5 ``` ### 行为与限制 * 每次执行能力时，两个字段都会被应用。 *** ## `set_velocity` \*\*用途：\*\*设置或修改实体的速度。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；部分方向模式还需要 `SOURCE`。 ### 字段 | 字段 | 默认值 | 说明 | | ------------ | -------- | ----------------------------------------------------------------- | | `operation` | `SET` | 可填写 `SET`、`ADD`、`MULTIPLY` 或 `SCALE`。 | | `direction` | `VECTOR` | 可填写 `VECTOR`、`LOOK`、`SOURCE_TO_TARGET`、`TARGET_TO_SOURCE` 或 `UP`。 | | `x / y / z` | `0` | `VECTOR` 模式使用的配置向量。 | | `strength` | `1` | 方向模式使用的强度。 | | `vertical` | `0` | 添加到生成的 Y 轴速度上的数值。 | | `multiplier` | `1` | `SCALE` 操作使用的缩放倍率。 | ### 示例 ```yaml type: set_velocity target: TARGET operation: SET direction: SOURCE_TO_TARGET strength: 1.2 vertical: 0.35 ``` ### 行为与限制 * `SOURCE` 与 `TARGET` 不在同一世界时，基于两者计算的方向向量无法产生有效方向。 * `MULTIPLY` 会分别乘算向量的各个分量。 *** ## `set_invulnerable` \*\*用途：\*\*启用或禁用实体的无敌状态，并可选择临时生效。 \*\*上下文：\*\*默认 `target` 为 `SOURCE`；需要一个实体。 ### 字段 | 字段 | 默认值 | 说明 | | ---------- | ------ | ------------------------ | | `value` | `true` | 期望的无敌状态。 | | `duration` | `0` | 持续时间，单位为 Tick；非正数表示持续生效。 | ### 示例 ```yaml type: set_invulnerable target: SOURCE value: true duration: 60 ``` ### 行为与限制 * 临时状态的恢复由能力工具安排，并要求实体在恢复时仍然有效。 *** ## `potion_effect` \*\*用途：\*\*向生物实体施加一个药水效果。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；需要生物实体。 ### 字段 | 字段 | 默认值 | 说明 | | ----------------------------- | ---------- | ------------------------------- | | `potion` | `SLOWNESS` | 药水效果注册键。 | | `duration` | `100` | 持续时间，单位为 Tick。 | | `infinite-duration-threshold` | `999999` | 正数阈值；持续时间达到该值时转换为无限持续。填写零会禁用转换。 | | `amplifier` | `0` | 效果倍率，最小值为 0。 | | `ambient` | `false` | 是否为环境效果。 | | `particles` | `true` | 是否显示粒子。 | | `icon` | `true` | 是否显示 HUD 图标。 | | `accumulate` | `false` | 是否累加已有持续时间，并保留更高的效果倍率。 | ### 示例 ```yaml type: potion_effect target: TARGET potion: SLOWNESS duration: 120 amplifier: 1 accumulate: true ``` ### 行为与限制 * 有限持续时间最小限制为 1 Tick。 * 累加后的持续时间会在整数最大值处饱和。 *** ## `remove_potion_effect` \*\*用途：\*\*移除生物实体身上选中的活跃药水效果。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；需要生物实体。 ### 字段 | 字段 | 默认值 | 说明 | | ------------- | ---- | ---------------------------------------------------------------- | | `potion` | 未设置 | 单个精确效果或选择器。 | | `potions` | 空 | 按顺序检查的选择器；支持精确键，以及 `ALL`、`BENEFICIAL`、`HARMFUL` 和 `NEUTRAL` 等分类。 | | `max-effects` | `-1` | 最多移除的效果数量；负数表示无限制。 | ### 示例 ```yaml type: remove_potion_effect target: TARGET potions: - HARMFUL - minecraft:slowness max-effects: 2 ``` ### 行为与限制 * 在每个选择器规则中，效果会按照注册键以确定性顺序选取。 *** ## `extend_potion_effects` \*\*用途：\*\*延长选中活跃药水效果的剩余持续时间。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；需要生物实体。 ### 字段 | 字段 | 默认值 | 说明 | | ------------- | --------- | ----------------------------------------------------------- | | `potion` | `HARMFUL` | 单个精确效果或分类选择器。 | | `potions` | 空 | 按顺序检查的选择器；支持 `ALL`、`BENEFICIAL`、`HARMFUL`、`NEUTRAL` 和精确效果键。 | | `percentage` | `0` | 根据每个选中效果当前剩余时间增加的百分比。 | | `multiplier` | 未设置 | 直接使用的持续时间倍率；存在时会覆盖 `percentage`，且最小值限制为 `1`。 | | `max-effects` | `-1` | 最多延长的效果数量；负数表示无限制。 | ### 示例 ```yaml type: extend_potion_effects target: TARGET potions: - minecraft:poison - minecraft:slowness percentage: 20 ``` ### 行为与限制 * 每个效果的倍率、环境标记、粒子和图标设置都会保留。 * 无限持续效果不会发生变化。 * 有限持续时间会四舍五入到最接近的 Tick，并在整数最大值处饱和。 * 在每个选择器规则中，效果会按照注册键以确定性顺序选取。 *** ## `potion_cloud` \*\*用途：\*\*生成一个包含单个自定义药水效果的区域效果云。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；效果云位置使用解析出的触发位置。 ### 字段 | 字段 | 默认值 | 说明 | | ------------------ | -------- | -------------------------- | | `radius` | `3.0` | 效果云半径。 | | `duration` | `120` | 效果云存在时间，单位为 Tick。 | | `potion` | `POISON` | 药水效果键。 | | `potion-duration` | `100` | 药水效果持续时间。 | | `potion-amplifier` | `1` | 药水效果倍率。 | | `accumulate` | `false` | 是否累加采样到的已有持续时间，并保留更高的效果倍率。 | ### 示例 ```yaml type: potion_cloud potion: POISON radius: 4 duration: 160 potion-duration: 100 potion-amplifier: 0 ``` ### 行为与限制 * 启用累加时，只会在创建效果云时采样附近实体已有的效果状态；之后不会针对每个未来进入的实体独立重新计算。 *** ## `freeze` \*\*用途：\*\*修改生物实体的冰冻 Tick。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；需要生物实体。 ### 字段 | 字段 | 默认值 | 说明 | | -------------- | ------- | ------------------------------------------- | | `freeze-ticks` | `60` | 配置的冰冻 Tick，最小值限制为 0。 | | `accumulate` | `false` | 当前实现中：`false` 会加上已有 Tick，`true` 会替换已有 Tick。 | ### 示例 ```yaml type: freeze target: TARGET freeze-ticks: 80 accumulate: false ``` ### 行为与限制 * 历史配置项名称 `accumulate` 与当前实现的实际行为相反。 *** ## `fire` \*\*用途：\*\*修改生物实体的燃烧 Tick。 \*\*上下文：\*\*默认 `target` 为 `TARGET`；需要生物实体。 ### 字段 | 字段 | 默认值 | 说明 | | ------------ | ------- | ------------------------------------------- | | `fire-ticks` | `60` | 配置的燃烧 Tick，最小值限制为 0。 | | `accumulate` | `false` | 当前实现中：`false` 会加上已有 Tick，`true` 会替换已有 Tick。 | ### 示例 ```yaml type: fire target: TARGET fire-ticks: 100 accumulate: false ``` ### 行为与限制 * 历史配置项名称 `accumulate` 与当前实现的实际行为相反。 *** ## `experience` \*\*用途：\*\*给予玩家原始经验点数。 \*\*上下文：\*\*默认 `target` 为 `SOURCE`；选中的实体必须是玩家。 ### 字段 | 字段 | 默认值 | 说明 | | -------- | --- | ------------------------------------------- | | `amount` | `1` | 传递给 Bukkit `Player#giveExp` 的经验点数；负数遵循平台行为。 | ### 示例 ```yaml type: experience target: SOURCE amount: 5 ``` ### 行为与限制 * 此能力修改的是原始经验点数，而不是固定数量的经验等级。 ***