🧬实体状态能力

本页面会将每一种已注册能力作为完整条目进行说明。所有条目也支持能力页面中介绍的通用能力字段。

本页面的注册键

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} 表示其最大值。

示例

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。附魔或自定义物品提前失效时也会立即移除修改器。

示例

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

新的生命值；支持当前生命值、最大生命值，以及实现中记录的触发器伤害占位符。

示例

type: set_health
target: SOURCE
amount: 'min({max-health}, {health} + 6)'

行为与限制

数值会限制在合法的生命值范围内，并受到实现中的硬性上限约束。
设置为零可能会杀死该实体。

`set_absorption`

**用途：**设置可受伤害实体的伤害吸收量。

**上下文：**默认 target 为 SOURCE；目标必须是仍然存活的可受伤害实体。

字段

默认值

说明

amount

10

新的伤害吸收值；支持使用 {health} 表示当前吸收量，使用 {max-health} 表示最大吸收量。

示例

type: set_absorption
target: SOURCE
amount: 'min({max-health}, {health} + 4)'

行为与限制

数值首先被硬性限制为不超过 2048，然后再受实体最大吸收量限制。
已死亡或生命值为零的实体会被跳过。

`set_air`

**用途：**设置实体剩余的空气 Tick。

**上下文：**默认 target 为 TARGET；选中的实体必须是生物实体。

字段

默认值

说明

amount

当前空气值

新的剩余空气值；支持 {air} 和 {max-air}。

示例

type: set_air
target: TARGET
amount: 0

行为与限制

数值会限制在实现允许的下限和最大空气值之间。
平台支持时，负空气值可以立即继续溺水行为。

`set_food`

**用途：**设置玩家的饥饿值和饱和度。

**上下文：**默认 target 为 SOURCE；选中的实体必须是玩家。

字段

默认值

说明

food

1

新的饥饿值，限制在 0..20；{original} 表示当前饥饿值。

saturation

0

新的饱和度，限制在 0..20；{original} 表示当前饱和度。

示例

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 操作使用的缩放倍率。

示例

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；非正数表示持续生效。

示例

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

是否累加已有持续时间，并保留更高的效果倍率。

示例

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

最多移除的效果数量；负数表示无限制。

示例

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

最多延长的效果数量；负数表示无限制。

示例

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

是否累加采样到的已有持续时间，并保留更高的效果倍率。

示例

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。

示例

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。

示例

type: fire
target: TARGET
fire-ticks: 100
accumulate: false

行为与限制

历史配置项名称 accumulate 与当前实现的实际行为相反。

`experience`

**用途：**给予玩家原始经验点数。

**上下文：**默认 target 为 SOURCE；选中的实体必须是玩家。

字段

默认值

说明

amount

1

传递给 Bukkit Player#giveExp 的经验点数；负数遵循平台行为。

示例

type: experience
target: SOURCE
amount: 5

行为与限制

此能力修改的是原始经验点数，而不是固定数量的经验等级。

最后更新于 6天前