界面自定义

菜单文件位于：

plugins/KaFurnace/ui/main.yml
plugins/KaFurnace/ui/furnace.yml
plugins/KaFurnace/ui/upgrade.yml

首次启动不会自动释放菜单。管理员执行 /kf ui zh_CN 或 /kf ui en_US 安装缺失模板；已有文件不会被覆盖。修改后执行 /kf reload，插件更新时只补齐缺失键。

Layout 规则#

每行必须正好 9 个字符，可配置 1 到 6 行。每个非空字符都必须有对应的 button.<字符> 定义。

熔炉菜单的 i、f、o 分别表示原料、燃料和产物，每类必须配置 1 到 6 个位置。按 Layout 从左到右、从上到下的顺序映射逻辑槽位，实际可用数量由对应槽位等级决定。

主菜单固定使用：

字符	用途
f	最多 10 个熔炉列表位置；左键打开，右键升级
b	购买下一座熔炉

升级菜单必须包含 n、b、s、r，分别表示普通熔炉、高炉、烟熏炉和返回。以下升级字符每种最多出现一次；自定义布局省略某个字符时，对应购买入口不会显示：

字符	功能键
i / f / o	input_slot / fuel_slot / output_slot
e / v	fuel_efficiency / smelting_speed
l / a / c	offline_smelting / auto_output_delivery / completion_notification

按钮格式#

button:
  "P":
    dynamic: cook
    display:
      material: CLOCK
      amount: 1
      name: "&b熔炼进度"
      lore:
        - "&7[{cook_progress_bar}&7] &f{cook_progress}% &7剩余 &f{cook_remaining_seconds} 秒"

界面文字直接写在 UI 文件中，不支持 lang: 引用。标题、名称和 Lore 支持 & 颜色代码；安装 PlaceholderAPI 后也支持任意 %变量%，详见 PlaceholderAPI。

普通按钮动作#

主菜单和升级菜单中的非保留自定义按钮，以及熔炉详情中没有设置 dynamic: 且不是 i、f、o 的普通按钮，可以配置左右键动作：

button:
  "T":
    display:
      material: MAP
      amount: 1
      name: "&e回到主菜单"
    actions:
      left-click:
        - "close"
        - "command: main"
      right-click:
        - "console: menu open main %player_name%"

支持的动作按列表顺序执行：

动作	用途
close	关闭当前库存界面
command: <指令>	由点击玩家执行指令，开头的 / 可省略
console: <指令>	由控制台执行指令；Folia 上会切换到全局调度器

动作文本支持当前菜单可用的 {内置变量} 和 PAPI %变量%。未知动作、空命令、未知点击类型或非字符串列表会使该菜单校验失败，并回退到同语言内置模板。

插件保留功能按钮不能附加 actions：主菜单的 f、b，升级菜单的类型/属性/能力/返回字符，以及熔炉详情的 i、f、o 和所有 dynamic: 按钮。主菜单熔炉图标固定为左键打开、右键升级；详情中的 dynamic: level 按钮固定打开当前熔炉升级菜单。

display.material 支持以下物品来源：

来源	完整格式	短格式
原版	CLOCK、minecraft:clock	-
空槽	AIR	-
ItemsAdder	itemsadder:命名空间:物品ID	ia:命名空间:物品ID
Oraxen	oraxen:物品ID	-
CraftEngine	craftengine:命名空间:物品ID	ce:命名空间:物品ID

AIR 不放置显示物，但 Layout 字符对应的点击、购买或返回功能仍然有效。外部插件未启用、物品 ID 不存在或 API 不兼容时，该槽保持为空并在控制台对该 ID 记录一次警告。普通原版按钮仍可被熔炉类型或运行状态的动态图标覆盖；显式配置的 AIR 和外部物品不会被动态材质覆盖。

state-materials.idle、running、paused_offline 和 blocked_output 使用相同的物品格式，也支持 AIR 及 ItemsAdder、Oraxen、CraftEngine 物品。要让 dynamic: state 应用这些状态图标，其按钮的基础 display.material 应使用可覆盖的原版材质。

标题、按钮名称和 Lore 还支持资源包插件的字符贴图：

插件	字形	偏移
ItemsAdder	:font_image:	:offset_-8:
Oraxen	<glyph:字形ID> / <g:字形ID>	<shift:-8>
CraftEngine	<image:命名空间:字形ID>	<shift:-8>

ItemsAdder 与 Oraxen 标签由 KaFurnace 通过软依赖 API 转换；CraftEngine 标签保留给其容器数据包拦截器，因此必须启用 network.intercept-packets.container: true。不要在同一段文本中混用 Oraxen 和 CraftEngine 标签，否则 <shift:...> 无法区分归属。直接写入资源包分配的 Unicode 字符不需要服务端转换。

进度材质列表#

dynamic: cook 和 dynamic: burn 的 material 可以从单个值改为任意长度的非空列表。插件按实际列表数量等分 0..100%，不要求固定为 10 项。列表中的每一项都支持原版材质、AIR、ItemsAdder、Oraxen 或 CraftEngine 物品格式。

button:
  "P":
    dynamic: cook
    display:
      material:
        - itemsadder:my_pack:cook_1
        - itemsadder:my_pack:cook_2
        - itemsadder:my_pack:cook_3
        - itemsadder:my_pack:cook_4
      amount: 1
      name: "&b熔炼进度"
      lore:
        - "&7当前: &f{cook_progress}%"
  "B":
    dynamic: burn
    display:
      material:
        - oraxen:fuel_1
        - oraxen:fuel_2
        - oraxen:fuel_3
        - oraxen:fuel_4
        - oraxen:fuel_5
      amount: 1
      name: "&c燃料状态"
      lore:
        - "&7剩余: &f{burn_remaining_percent}%"

上述 4 项 cook 列表按 0-24%、25-49%、50-74%、75-100% 从第 1 项递增到第 4 项。burn 使用燃料“剩余比例”选择，因此新燃料接近 100% 时显示列表末项，燃烧过程中依次向前切换，接近耗尽或没有活动燃料时显示第 1 项。名称、Lore、数量和 custom-model-data 由整个按钮共用。

材质列表只能用于 dynamic: cook 或 dynamic: burn。其他动态类型和普通按钮使用列表会导致该 UI 文件校验失败并回退到内置模板。

熔炉状态变量#

变量	说明
{furnace_index} / {furnace_type} / {furnace_type_name}	熔炉序号、类型枚举和本地化类型名
{state} / {state_id}	状态文本和状态枚举名
{input_amount} / {fuel_amount} / {output_amount}	全部已解锁对应槽位的数量合计
{input_type} / {fuel_type} / {output_type}	第一个非空已解锁槽位的材质名
{completed}	已完成轮次数
{fuel_efficiency_level} / {smelting_speed_level}	燃料效率和熔炼速度等级
{input_slot_level} / {fuel_slot_level} / {output_slot_level}	三类槽位等级和已解锁数量
{offline_smelting_enabled}	是否允许该炉离线熔炼，按当前语言显示
{auto_output_delivery_enabled}	是否启用在线产物配送，按当前语言显示
{completion_notification_enabled}	是否启用完成通知，按当前语言显示

进度与时间变量#

变量	说明
{cook_progress} / {cook_progress_bar}	本轮百分比和递增的 20 段彩色进度条
{cook_elapsed_seconds} / {cook_total_seconds} / {cook_remaining_seconds}	本轮已用、总计和剩余秒数
{cook_elapsed_time} / {cook_total_time} / {cook_remaining_time}	按 countdown_format 格式化的本轮时长
{cook_all_remaining_seconds} / {estimated_remaining_seconds}	当前全部有效原料理论剩余秒数
{cook_all_remaining_time} / {estimated_remaining_time}	按 countdown_format 格式化的全部剩余时长
{cook_all_finish_time}	按 time_format 格式化的理论全部完成时间
{burn_progress} / {burn_remaining_percent}	已燃烧和剩余百分比
{burn_progress_bar}	按剩余量递减的 20 段彩色燃料条
{burn_elapsed_seconds} / {burn_total_seconds} / {burn_remaining_seconds}	当前已点燃燃料的时间
{burn_elapsed_time} / {burn_total_time} / {burn_remaining_time}	按 countdown_format 格式化的当前燃料时长
{fuel_all_remaining_ms} / {fuel_all_remaining_seconds}	当前余量加全部已解锁燃料槽库存的预计时间
{fuel_all_remaining_time}	按 countdown_format 格式化的全部燃料预计时长
{fuel_sufficient_for_all_input}	当前全部燃料是否足以熔完全部有效原料

两个进度条变量自带颜色代码。所有“剩余秒”向上取整为整数；毫秒和已用/总时长秒变量保留实际精度。全部 *_time 只拼接 countdown_format 中数值非零的区间，整数不补前导零，零时长使用秒单位显示。全部完成估算假定当前配方不变、燃料充足且输出不阻塞，只适合显示。

布尔变量显示 lang/zh_CN.yml 或 lang/en_US.yml 中的本地化文本，经济提供者显示本地化的 金币/点券 或 Money/Points。需要用于条件、脚本或配置判断时，在变量名末尾添加 _raw，例如 {offline_smelting_enabled_raw}、{fuel_sufficient_for_all_input_raw} 和 {input_slot_provider_raw}，原始值固定为小写的 true、false、vault 或 playerpoints。

价格与升级菜单变量#

主菜单提供 {owned}、{max}、{remaining_slots}、{next_furnace_index}，以及：

{furnace_purchase_price}
{furnace_purchase_provider}
{furnace_purchase_provider_available}

五类等级键均提供 {<键>_level}、{<键>_next_level}、{<键>_maxed}、{<键>_price}、{<键>_provider}、{<键>_provider_available}。三类永久解锁提供 {<键>_enabled} 及同样的价格、提供者、可用状态变量。类型切换价格前缀为 type_furnace、type_blast_furnace、type_smoker。

权限相关变量包括 {furnace_purchase_allowed}、五类 {<键>_permission_max_level} 与 {<键>_allowed}、三类永久能力 {<键>_allowed}，以及 {type_furnace_allowed}、{type_blast_furnace_allowed}、{type_smoker_allowed}。布尔显示值已本地化，菜单条件应使用对应的 _raw 值。