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。

物品槽#

字段	示例	说明
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_total_ms / cook_total_seconds	当前轮配方总时间
smelt_total_seconds	当前轮总秒数别名
cook_remaining_ms / cook_remaining_seconds	当前轮剩余时间
smelt_remaining_seconds	当前轮剩余秒数别名
cook_all_total_ms / cook_all_total_seconds	当前全部原料理论总时间
cook_all_remaining_ms / cook_all_remaining_seconds	当前全部原料理论剩余时间
estimated_all_seconds / estimated_remaining_seconds	全部原料理论剩余秒数别名
cook_all_finish_epoch_ms	理论完成时刻的 Unix 毫秒时间戳
cook_all_finish_time	服务器时区中的理论完成时间

例如：

进度: %kafurnace_1_cook_progress_bar% %kafurnace_1_cook_progress%%
本轮剩余: %kafurnace_1_cook_remaining_seconds% 秒
全部剩余: %kafurnace_1_estimated_remaining_seconds% 秒

全部原料估算假定当前配方不变、燃料持续充足且输出不会阻塞，只适合展示，不能用于扣费、发奖或任务截止时间。

燃料进度与时间#

字段	说明
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_total_ms / burn_total_seconds	当前燃料总燃烧时间
fuel_total_seconds / fuel_time_seconds	当前燃料总秒数别名
burn_remaining_ms / burn_remaining_seconds	当前燃料剩余时间
fuel_remaining_seconds	当前燃料剩余秒数别名
fuel_all_remaining_ms / fuel_all_remaining_seconds	当前燃烧余量与燃料槽库存合计可燃烧时间
fuel_sufficient_for_all_input	全部可用燃料是否足以熔完当前全部有效原料，返回 true 或 false

两个进度条字段返回可直接显示的 Minecraft 颜色控制码。所有剩余秒字段向上取整为整数；毫秒字段以及已燃烧、总时长秒字段仍保留精度。

全部燃料时间使用所有已解锁燃料槽中每件燃料的实际时长和当前燃料效率倍率计算，并加上当前已点燃燃料的剩余时间。没有原料或当前配方无法估算时，fuel_sufficient_for_all_input 返回 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，fuel_sufficient_for_all_input 返回 false，进度条返回 20 段深灰色空条，物品类型返回 AIR，state 返回 IDLE，理论完成时间返回 -；
• 无效序号、未知字段或没有玩家上下文时返回空字符串；
• 本地化 {furnace_type_name} 和按钮动态上下文 {percent} 不作为 PAPI 字段公开；
• 变量读取线程安全的不可变快照，不主动推进熔炉，默认最多落后一个 5 Tick 引擎刷新周期；
• KaFurnace 自身变量可被异步读取，但 UI 中使用的其他第三方扩展仍需由对应扩展保证 Folia 线程兼容。

这些变量可用于计分板、聊天格式、Tab 列表、菜单插件和其他支持 PlaceholderAPI 的插件。