⚠️ Beta 声明（请先读这一段）本数据包目前处于中期制作的 Beta 阶段：功能与格式都可能继续变动， 文档内容仅供参考，不保证稳定、不保证向后兼容。 安装或升级前请备份你的存档。如果它弄坏了什么，Beta 阶段我们不作承诺。
欢迎试用与反馈，但请把它当「正在做的东西」，而不是「已经定稿的产品」。
一句话：给它一件物品，它帮你管住这件物品「被右键使用」的全过程。
你平时玩的 Minecraft 里，一件物品右键下去无非就是吃掉、放下去、或者射出去。 这些东西要在数据包里自己做，得写一大堆检测逻辑，还很容易漏掉边角情况。
这个包把这件事做成了一套现成的框架。你不需要改这个包的代码，
只要在自己的物品上写一小段声明（一段叫 dc 的标记），
就自动获得「用了几次、什么时候用完、用完变什么」这一整套行为。
它管的是这些动作：
吃掉 / 喝掉 · 放下方块 · 丢出去 · 用一次掉一格耐久并随时间自己修回来 · 鱼竿右键 · 弓弩三叉戟射击 · 雪球鸡蛋末影珍珠经验瓶投掷
下面用普通玩家的说法说一遍，不涉及任何技术名词。示例物品都能在
data/doom.consumable/loot_table/items/ 里找到。
| 你想做的事 | 实际效果 | 示例物品文件 |
|---|---|---|
| 限量使用的消耗品 | 比如一个苹果能吃 5 次，吃完变成金苹果。物品栏里会显示一条耐久条代表还剩几次 | limited_apple.json |
| 无限使用的消耗品 | 随便吃，永远用不完。可以设定「每次使用给自己一点伤害」之类的代价 | infinite_apple.json |
| 用完就消失 / 用完就坏掉 | 用光之后有三种收场：直接消失、留在手里但锁死不能再碰、或者干脆变回一件普通物品 | vanish_apple.json · disable_apple.json · normal_bow.json |
| 用完返还一个东西 | 用尽之后手上换成另一件物品（比如苹果吃完剩个核） | remainder_apple.json |
| 限量放置的方块 | 像放方块一样放 5 次，放完变回一撮粉末。按住右键连放也不会漏数 | limited_glowstone.json |
| 能丢的东西 | 把物品丢出去会有响应，并带一个丢弃冷却（默认 60 刻） | discard_glowstone.json |
| 会自己修回来的耐久条 | 用一次掉一格，停下来不动时会一格一格自己回满。像呼吸一样 | recover_heart.json |
| 鱼竿右键接口 | 给鱼竿接上抛竿 / 收杆 / 钓到东西的事件，能按玩家状态禁用，也能做成「按一下立刻收回」的按钮型物品 | test_rod.json |
| 射击扣次 | 弓 / 弩 / 三叉戟真的射出才扣一次。可以顺带补回箭（相当于无限箭），也可以做三种耗尽结局 | limited_bow.json · infinite_bow.json |
| 弩 · 连发弹匣 | 给弩加一个标记，射完自动重新上膛，配合补箭就是半自动无限连发 | repeating_crossbow.json |
| 投掷扣次 | 雪球 / 鸡蛋 / 末影珍珠 / 经验瓶，扔一个扣一次 | limited_snowball.json · limited_ender_pearl.json |
| 方块使用冷却 | 给一个方块加冷却：冷却没好时右键会被拦下，还能让方块在「就绪 / 冷却」两种外观之间自动切换（用拉杆、铜灯这类原生方块当载体） | api/block_cd_demo 一条命令就能搭起来 |
有些物品天生就是「用一次少一点」的消耗品，有些是「永远用不完」的钥匙。 这两类是这个框架里最基础的分支，几乎所有示例都是在它们上面加减改出来的。
- 地图作者：给自定义物品加上「吃几次 / 放几次 / 射几次」的规则，不用重写检测逻辑。
- 其它数据包作者：把本包当库来调用，只需要在自己物品上写声明。
- 直接玩的玩家：也可以直接把它当玩法包装进存档，用示例物品体验。
-
准备两个包。本包依赖
doom.library（必需），它是提供数据读写的公共基础库， 没有它本包跑不起来：doom.consumable（本包）doom.library（https://github.com/Doom-Flare/doom.library）- 可选：
doom.log。装上它，框架的并发自检哨兵在发现问题时会向上报一条E201； 不装也能正常玩，只是这类提醒无处可去。
-
放进存档的
datapacks目录。两个（或三个）包都要放在同一个目录下：<你的存档>/datapacks/doom.consumable/ <你的存档>/datapacks/doom.library/也就是每个包目录里应该直接看到
pack.mcmeta和data/。 -
在游戏里加载。进入世界后执行
/reload。用/datapack list应该能看到这两个包是启用的。 -
版本要求。以本包
pack.mcmeta的声明为准，当前是：pack_format= 81supported_formats= 48 ~ 82（含两端）- 另有
min_format=[48, 0]、max_format=[82, 0]
本包已在 Minecraft 1.21.11 上跑通完整回归套件（见下一节）。 装到别的版本前，请先核对你的游戏版本落在上面的区间内。
本包自带一套自动化回归。装好 doom.test 后，在游戏里执行：
/function doom.test:consumable
它会逐个套件上报结果。当前是 9 个套件 / 175 条断言，
判定结果请用 RCON 直读计分板 #pass / #fail / #calls dt.test——
套件用 tellraw 上报，不会写进服务端日志，光看日志会以为什么都没发生。
现状：2026-10-12 起 175/175 全绿（1.21.11 实测）。 此前长期挂着的那 1 条失败是测试夹具自身的缺陷（它试图用命令直接生成鱼漂， 而鱼漂在当前版本是禁止
summon的实体），不是产品问题，夹具已改。
真正的技术细节不在这个 README 里，已经整份下沉到
docs/技术手册-物品契约与实现.md。
那份手册里写着：完整的 dc 字段契约表、鱼竿接口的四条 API 与四个回调标签、
方块冷却设备的字段与钩子、射击链／投掷链的记分板、以及逐条标了出处的引擎事实与踩坑记录。
要动手改行为，请以那份为准。
这里只留最常用的几条，让你先跑起来：
- 声明写在哪：物品组件的
minecraft:custom_data.dc里。 - 两个必填字段：
detect（走哪条检测链："consume"吃 /"place"放 /"shot"射 /"throw"投） 和type（"limited"有限次 /"infinite"无限）。 - 次数：
max_uses与current_uses，配合max_damage就能显示成一条耐久条。 - 耗尽处置：
depleted取"disable"（锁死）/"vanish"（消失）/"normal"（变普通物品），缺省是disable。 - 伪耐久回复：
recover: 1b打开，recover_ticks控制每格回复需要多少刻（默认 10）。 - 可丢弃：
discardable: 1b，冷却用discard_cooldown（默认 60）。
最快的学习路径是照抄示例：打开 data/doom.consumable/loot_table/items/ 下任意一个
limited_* / infinite_* 文件，改改里面的 id 和数字，就是一件你自己的物品了。
另外两个现成的工具：
/function doom.consumable:test/give_rod—— 拿一把测试鱼竿；/function doom.consumable:test/probe_rod—— 打印鱼竿相关的计分板与鱼漂状态，现场核对用。
pack.mcmeta 版本声明（版本支持以它为准）
README.md 你正在看的这份（面向新手）
CHANGELOG.md 变更日志 —— 功能与版本的权威来源
docs/
技术手册-物品契约与实现.md 完整技术手册（dc 契约 / API / 引擎事实）
技术档案-方块冷却闸门-20261001.md
实现链路-RecoveryHeart-20260928.md
data/doom.consumable/
advancement/ 进度触发器（各条检测链的入口）
function/ 框架本体
api/ 对外 API：鱼竿、方块冷却、丢包回调…
block/ 方块冷却设备
core/ 快照与派发主干
recover/ 伪耐久条回复
restore/ 恢复落点守卫
rod/ 鱼竿接口
schedule/ 限次与日程
shot/ 射击链（弓 / 弩 / 三叉戟）
throw/ 投掷链（雪球 / 鸡蛋 / 末影珍珠 / 经验瓶）
test/ 调试与发放测试物品的函数
item_modifier/ 物品改写（连发弹匣等）
loot_table/items/ 全部示例物品定义
tags/ 回调标签（第三方挂载点）与物品/方块标签
- Beta 阶段，格式会变。上面那张
dc字段表随时可能调整，请以docs/技术手册-物品契约与实现.md为准。 - 方块交互没有「使用前」钩子。方块冷却闸门只能做「冷却判定 + 回调」， 方块本身的行为（箱子开了、按钮按了）已经发生。要「根本按不动」，数据包层面做不到。
- 补箭在背包满时会静默失败，不会报错。
- 鱼竿有一条边界：把鱼漂抛进未加载的区块时，归属标记会打空， 可能出现一次「抛竿后立刻收杆」的幻影（真人正常视距下不会遇到）。
见仓库根目录的 LICENSE。