PlaceholderAPI
安装 PlaceholderAPI 后，KaFurnace 会自动注册 %kafurnace_*% 内部扩展，无需从 eCloud 另外下载。PlaceholderAPI 是软依赖；未安装时不会影响熔炉、数据库或内置 UI 变量。
变量格式#
KaFurnace 变量使用以下格式：
%kafurnace_<熔炉序号>_<字段>%
熔炉序号为 1..10，对应玩家主菜单中的稳定序号。例如 %kafurnace_1_input_amount% 表示一号炉原料数量。
标识、状态与等级#
| 字段 | 示例 | 说明 |
|---|---|---|
furnace_index |
%kafurnace_1_furnace_index% |
玩家内熔炉序号 |
furnace_type |
%kafurnace_1_furnace_type% |
FURNACE、BLAST_FURNACE 或 SMOKER |
state / state_id |
%kafurnace_1_state% |
原始状态枚举名 |
completed |
%kafurnace_1_completed% |
已完成熔炼轮数 |
fuel_efficiency_level |
%kafurnace_1_fuel_efficiency_level% |
燃料效率等级 |
smelting_speed_level |
%kafurnace_1_smelting_speed_level% |
熔炼速度等级 |
input_slot_level |
%kafurnace_1_input_slot_level% |
原料槽等级和已解锁数量 |
fuel_slot_level |
%kafurnace_1_fuel_slot_level% |
燃料槽等级和已解锁数量 |
output_slot_level |
%kafurnace_1_output_slot_level% |
产物槽等级和已解锁数量 |
offline_smelting / offline_smelting_enabled |
%kafurnace_1_offline_smelting_enabled% |
是否允许离线熔炼，按当前语言显示 |
auto_output_delivery / auto_output_delivery_enabled |
%kafurnace_1_auto_output_delivery_enabled% |
是否启用在线产物配送，按当前语言显示 |
completion_notification / completion_notification_enabled |
%kafurnace_1_completion_notification_enabled% |
是否启用一次性完成通知，按当前语言显示 |
PAPI 中的 state 不使用语言文件，和 state_id 一样返回 IDLE、RUNNING、PAUSED_OFFLINE 或 BLOCKED_OUTPUT。
布尔字段默认返回语言文件中的 是/否 或 Yes/No。在任一布尔字段末尾添加 _raw 可获得固定的 true/false，例如 %kafurnace_1_offline_smelting_enabled_raw%，适合条件和脚本判断。
物品槽#
| 字段 | 示例 | 说明 |
|---|---|---|
input_amount |
%kafurnace_1_input_amount% |
全部已解锁原料槽的数量合计 |
input_type |
%kafurnace_1_input_type% |
第一个非空已解锁原料槽的材质枚举名 |
fuel_amount |
%kafurnace_1_fuel_amount% |
全部已解锁燃料槽中尚未点燃的数量合计 |
fuel_type |
%kafurnace_1_fuel_type% |
第一个非空已解锁燃料槽的材质枚举名 |
output_amount |
%kafurnace_1_output_amount% |
全部已解锁产物槽的数量合计 |
output_type |
%kafurnace_1_output_type% |
第一个非空已解锁产物槽的材质枚举名 |
已点燃燃料已经从燃料槽扣除，其剩余时间应读取燃料时间变量，而不是 fuel_amount。
熔炼进度与时间#
| 字段 | 说明 |
|---|---|
cook_progress / cook_percent |
当前轮熔炼百分比，范围 0..100 |
cook_progress_bar |
固定 20 个 ` |
cook_elapsed_ms / cook_elapsed_seconds |
当前轮已熔炼时间 |
cook_progress_seconds / smelt_progress_seconds |
当前轮已熔炼秒数别名 |
cook_elapsed_time / cook_progress_time / smelt_progress_time |
按 countdown_format 格式化的当前轮已用时间 |
cook_total_ms / cook_total_seconds |
当前轮配方总时间 |
smelt_total_seconds |
当前轮总秒数别名 |
cook_total_time / smelt_total_time |
按 countdown_format 格式化的当前轮总时间 |
cook_remaining_ms / cook_remaining_seconds |
当前轮剩余时间 |
smelt_remaining_seconds |
当前轮剩余秒数别名 |
cook_remaining_time / smelt_remaining_time |
按 countdown_format 格式化的当前轮剩余时间 |
cook_all_total_ms / cook_all_total_seconds |
当前全部原料理论总时间 |
cook_all_total_time |
按 countdown_format 格式化的全部理论总时间 |
cook_all_remaining_ms / cook_all_remaining_seconds |
当前全部原料理论剩余时间 |
estimated_all_seconds / estimated_remaining_seconds |
全部原料理论剩余秒数别名 |
cook_all_remaining_time / estimated_all_time / estimated_remaining_time |
按 countdown_format 格式化的全部剩余时间 |
cook_all_finish_epoch_ms |
理论完成时刻的 Unix 毫秒时间戳 |
cook_all_finish_time |
按 time_format 格式化的服务器时区理论完成时间 |
例如：
进度: %kafurnace_1_cook_progress_bar% %kafurnace_1_cook_progress%%
本轮剩余: %kafurnace_1_cook_remaining_time%
全部剩余: %kafurnace_1_estimated_remaining_time%
全部原料估算假定当前配方不变、燃料持续充足且输出不会阻塞，只适合展示，不能用于扣费、发奖或任务截止时间。
燃料进度与时间#
| 字段 | 说明 |
|---|---|
burn_progress |
当前燃料已燃烧百分比，范围 0..100 |
burn_remaining_percent / burn_percent |
当前燃料剩余百分比 |
burn_progress_bar |
固定 20 个 ` |
burn_elapsed_ms / burn_elapsed_seconds |
当前燃料已燃烧时间 |
burn_progress_seconds / fuel_elapsed_seconds |
当前燃料已燃烧秒数别名 |
burn_elapsed_time / burn_progress_time / fuel_elapsed_time |
按 countdown_format 格式化的已燃烧时间 |
burn_total_ms / burn_total_seconds |
当前燃料总燃烧时间 |
fuel_total_seconds / fuel_time_seconds |
当前燃料总秒数别名 |
burn_total_time / fuel_total_time / fuel_time |
按 countdown_format 格式化的当前燃料总时间 |
burn_remaining_ms / burn_remaining_seconds |
当前燃料剩余时间 |
fuel_remaining_seconds |
当前燃料剩余秒数别名 |
burn_remaining_time / fuel_remaining_time |
按 countdown_format 格式化的当前燃料剩余时间 |
fuel_all_remaining_ms / fuel_all_remaining_seconds |
当前燃烧余量与燃料槽库存合计可燃烧时间 |
fuel_all_remaining_time |
按 countdown_format 格式化的全部燃料时间 |
fuel_sufficient_for_all_input |
全部燃料是否充足，按当前语言显示；追加 _raw 返回 true/false |
两个进度条字段返回可直接显示的 Minecraft 颜色控制码。所有剩余秒字段向上取整为整数；毫秒字段以及已燃烧、总时长秒字段仍保留精度。全部 *_time 变量只拼接 countdown_format 中数值非零的区间，整数不补前导零，零时长使用秒单位显示。
全部燃料时间使用所有已解锁燃料槽中每件燃料的实际时长和当前燃料效率倍率计算，并加上当前已点燃燃料的剩余时间。没有原料或当前配方无法估算时，fuel_sufficient_for_all_input 返回当前语言中的“否”，对应 _raw 字段返回 false。
在 UI 中使用其他 PAPI 变量#
ui/main.yml、ui/furnace.yml 和 ui/upgrade.yml 的标题、按钮名称与 Lore 可使用其他扩展提供的 PAPI 变量：
name: "&e%player_name% 的一号炉"
lore:
- "&7在线时间: &f%statistic_time_played%"
解析顺序固定为：KaFurnace 内置 {变量}、PAPI %变量%、最后转换 & 颜色代码。因此 PAPI 返回文本中的 &a 等颜色代码同样生效。未安装 PlaceholderAPI 时，UI 中的 %变量% 保持原样。
空值与刷新规则#
- 尚未购买的有效熔炉序号对数字数量和时间返回
0，可读*_time返回零时长格式，fuel_sufficient_for_all_input返回本地化的否，进度条返回 20 段深灰色空条，物品类型返回AIR，state返回IDLE，理论完成时间返回-； - 无效序号、未知字段或没有玩家上下文时返回空字符串；
- 本地化
{furnace_type_name}和按钮动态上下文{percent}不作为 PAPI 字段公开； - 变量读取线程安全的不可变快照，不主动推进熔炉，默认最多落后一个 5 Tick 引擎刷新周期；
- KaFurnace 自身变量可被异步读取，但 UI 中使用的其他第三方扩展仍需由对应扩展保证 Folia 线程兼容。
这些变量可用于计分板、聊天格式、Tab 列表、菜单插件和其他支持 PlaceholderAPI 的插件。