Doom Virtual Health v3.0.0 — Minecraft 1.21.7 / 1.21.8

快速开始

方式一：auto_init（推荐）

/summon minecraft:zombie ~ ~ ~ {
  data:{dvh:{max_health:40d, health:40d, on_death:"say died"}},
  NoAI:1b
}

第一 tick 自动初始化，无需任何命令调用。

方式二：api/create

/execute as @n run \
  function doom.virtual.health:api/create {with:{max_health:21.5, health:20}}

绑定 Bossbar（可选）

/execute as @e[tag=virtual_health_entity] run \
  function doom.bossbar:api/create {with:{name:'"Boss"',color:red,style:progress,visible:"true",targets:"@a"}}

扣血 / 加血 / 无敌

# 扣 500 mHP（= 0.5 HP）
/execute as @e[tag=virtual_health_entity] run \
  function doom.virtual.health:api/add_health {points:-500}

# 无敌
/execute as @e[tag=virtual_health_entity] run \
  function doom.virtual.health:api/set_invulnerable {state:1b}

伤害与治疗机制

精度：0.001 HP（mHP）。余数补偿保证长期累计不丢失。

伤害倍率 dvh.damage_mult（默认 1000 = 100%）

API 参考

doom.virtual.health

所有 API 以 @s 为 VH 实体执行，非 VH 实体 return fail。单位：points/health/max_health 均为 HP（内部 ×1000 转 mHP，支持小数如 points:-0.5）。

doom.bossbar

api/create 参数（bossbar）

predicate 判定

# 血量低于 30% 时触发
scoreboard players set @e[tag=virtual_health_entity] dvh.pp 30
execute as @e[tag=virtual_health_entity] if function \
  doom.virtual.health:api/predicate/below_percentage run say low HP!

死亡回调 on_death

触发时机：dvh.health 降至 0（trigger_death）时执行。

用法：on_death 是任意命令字符串，以 VH 实体位置执行：

/execute as @e[tag=virtual_health_entity] run \
  function doom.virtual.health:api/create {with:{max_health:100, health:100, on_death:"say I died"}}

或 auto_init 时：

/summon minecraft:zombie ~ ~ ~ {
  data:{dvh:{max_health:100d, health:100d, on_death:"function mypack:boss_death"}},
  NoAI:1b
}

执行语义

• 等价于 execute at @s run <on_death 命令>，@s 是 VH 实体
• 不要写 @s[tag=virtual_health_entity]（选择器在回调时已失效），直接用 @s
• 回调执行后实体被 out_of_world 伤害杀死
• on_death 为空字符串视为无回调，直接进入死亡流程
• 指定 on_death 时跳过 UUID 归属追踪；未指定则追踪 last_hurt_by_mob 生成击杀 credit

常见写法

# 广播死亡消息
on_death: "say A VH entity has died"

# 调用自定义处理函数
on_death: "function mypack:boss_killed"

# 播放音效（以实体位置）
on_death: "playsound minecraft:entity.wither.death master @a ~ ~ ~ 1 1"

# 生成掉落物
on_death: "summon minecraft:item ~ ~ ~ {Item:{id:\"minecraft:diamond\",Count:1b}}"

auto_init 自动初始化

/summon 时实体携带 data:{dvh:{...}}，第一 tick 自动完成 create + apply_trigger：

/summon minecraft:zombie ~ ~ ~ {
  data:{dvh:{max_health:"2000", health:"2000"}},
  NoAI:1b
}

• 支持字段：max_health / health / on_death
• 值可为数字（double）或字符串（如 "2000"，mcdoc 补全用）
• 自动补全：Spyglass + mcdoc 插件在 data:{dvh:{ 处提示
• auto_init 后自动执行 apply_trigger（分配 vitality 触发器）

vitality 附魔触发器

vitality 附魔挂在实体装备上，由附魔 tick 驱动装备加成同步，替代纯命令轮询。

• 附魔文件：enchantment/vitality.json（槽位：saddle、mainhand）
• Riding 实体（猪/马/驴/骡/骷髅马/僵尸马/骆驼/炽足兽）→ 主手槽
• 非 Riding 实体 → 鞍槽
• api/apply_trigger 自动分配，也可手动调用
• tick effect 驱动 api/sync/equipment_bonus：扫描 8 槽 attribute_modifiers 同步到 dvh.max_health

注意：修改 enchantment JSON 需要重启服务器（/reload 无效）。

读取血量

# 读取 HP（÷1000）
execute store result score #hp obj run function api/get_health
# #hp = 2000

# 读取 mHP（原始精度）
execute store result score #hp_mhp obj run function api/get_health_mhp
# #hp_mhp = 2000000

# 读取百分比 [0,100]
execute store result score #pct obj run function api/get_percentage
# #pct = 63

# 统计（写两个计分板并 scale）
execute as @e[tag=virtual_health_entity] run \
  function doom.virtual.health:api/get_stats {damage_out:"#dmg", healing_out:"#heal", scale:1000}

计分板

标签

安装

1. 在 Releases 下载数据包 zip
2. 放入存档的 datapacks/ 文件夹
3. 执行 /reload 加载数据包
4. 看到 [DVH] Virtual Health System Loaded. 即成功

已知 Edge Cases（边界情况）

亟待更多玩家测试：以下为代码审查中识别出的边界情况，部分已在设计中规避，部分受原版机制限制。

数值精度类

机制限制类（原版限制）

使用注意类

注意事项

• kill 参数默认 {kill:1b}，移除时会杀死实体；不想杀用 {kill:0b}
• on_death 回调不要写 @s[tag=virtual_health_entity]（选择器已失效），直接用 @s
• add_health {points:负数} 对无敌实体无效；set_health 不受无敌影响
• Bossbar api/create 重复调用 return fail
• scale:1 = mHP，scale:1000 = HP
• 修改 enchantment JSON（vitality.json）需要重启服务器
• 伤害倍率范围 [1, 100000]（×1000 标度）