UI Customization

Menu files are stored at:

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

Menus are not extracted automatically on first startup. An administrator installs missing templates with /kf ui zh_CN or /kf ui en_US; existing files are not overwritten. Run /kf reload after editing. Updates only add missing keys.

Layout rules#

Every row must contain exactly 9 characters, with 1 to 6 rows total. Every non-space character needs a matching button.<character> definition.

The furnace menu uses i, f, and o for input, fuel, and output. Each category must have 1 to 6 positions. Positions map to logical slots from left to right and top to bottom; the corresponding slot level controls how many are active.

The main menu uses:

Character	Purpose
f	Up to 10 furnace-list positions; left-click opens and right-click upgrades
b	Purchase the next furnace

The upgrade menu must contain n, b, s, and r for furnace, blast furnace, smoker, and return. Each upgrade character below may appear at most once. Omitting one from a custom layout hides that purchase entry:

Character	Feature key
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 format#

button:
  "P":
    dynamic: cook
    display:
      material: CLOCK
      amount: 1
      name: "&bCooking Progress"
      lore:
        - "&7[{cook_progress_bar}&7] &f{cook_progress}% &7- &f{cook_remaining_seconds}s left"

UI text is written directly in menu files; lang: references are not supported. Titles, names, and lore support & color codes and arbitrary %placeholders% when PlaceholderAPI is installed. See PlaceholderAPI.

Ordinary button actions#

Custom non-reserved buttons in the main and upgrade menus, plus ordinary furnace-detail buttons without dynamic: that are not i, f, or o, may define left- and right-click actions:

button:
  "T":
    display:
      material: MAP
      amount: 1
      name: "&eBack to Main Menu"
    actions:
      left-click:
        - "close"
        - "command: main"
      right-click:
        - "console: menu open main %player_name%"

Supported actions run in list order:

Action	Purpose
close	Close the current inventory view
command: <command>	Run a command as the clicking player; a leading / is optional
console: <command>	Run a command as console; Folia schedules it on the global scheduler

Action text accepts the {built-in variables} available to that menu and PAPI %placeholders%. Unknown actions, empty commands, unknown click types, or non-string lists fail menu validation and cause fallback to the bundled template for that locale.

Reserved feature buttons cannot define actions: main-menu f and b; upgrade type, property, ability, and return characters; furnace-detail i, f, o, and every dynamic: button. Main-menu furnace icons always open on left-click and enter upgrades on right-click. The detail menu's dynamic: level button always opens upgrades for the current furnace.

display.material accepts these item sources:

Source	Full form	Alias
Vanilla	CLOCK, minecraft:clock	-
Empty slot	AIR	-
ItemsAdder	itemsadder:namespace:item_id	ia:namespace:item_id
Oraxen	oraxen:item_id	-
CraftEngine	craftengine:namespace:item_id	ce:namespace:item_id

AIR leaves the slot visually empty without disabling the click, purchase, or return action assigned to its Layout character. If an external plugin is disabled, the item ID does not exist, or its API is incompatible, the slot stays empty and the console reports that ID once. Dynamic furnace-type or state icons can still replace ordinary vanilla display materials; explicitly configured AIR and external items are not replaced.

state-materials.idle, running, paused_offline, and blocked_output use the same item syntax. They also accept AIR and ItemsAdder, Oraxen, or CraftEngine items. For dynamic: state to apply these state icons, keep the button's base display.material as an overridable vanilla material.

Titles, button names, and lore also accept resource-pack glyph syntax:

Plugin	Glyph	Offset
ItemsAdder	:font_image:	:offset_-8:
Oraxen	<glyph:glyph_id> / <g:glyph_id>	<shift:-8>
CraftEngine	<image:namespace:glyph_id>	<shift:-8>

KaFurnace resolves ItemsAdder and Oraxen tags through their optional APIs. CraftEngine tags are preserved for its container packet interceptor, so network.intercept-packets.container: true must be enabled. Do not mix Oraxen and CraftEngine tags in the same text because <shift:...> would be ambiguous. Fixed Unicode characters assigned by a resource pack need no server-side conversion.

Progress material lists#

For dynamic: cook and dynamic: burn, material may be changed from a single value to a non-empty list of any length. KaFurnace divides 0..100% by the actual number of entries; the list is not fixed to 10 items. Every entry accepts vanilla materials, AIR, ItemsAdder, Oraxen, or CraftEngine item syntax.

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: "&bCooking Progress"
      lore:
        - "&7Current: &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: "&cFuel Status"
      lore:
        - "&7Remaining: &f{burn_remaining_percent}%"

The four-entry cook list above advances from entry 1 to entry 4 across 0-24%, 25-49%, 50-74%, and 75-100%. Burn selection uses the fuel remaining ratio: a fresh fuel near 100% displays the last entry, then moves toward the first entry while burning. The first entry is shown near empty or when no fuel is active. Name, lore, amount, and custom-model-data are shared by the whole button.

Material lists are valid only for dynamic: cook and dynamic: burn. A list on any other dynamic type or ordinary button fails UI validation and causes that menu file to fall back to the bundled template.

Furnace-state variables#

Variable	Description
{furnace_index} / {furnace_type} / {furnace_type_name}	Furnace number, type enum, and localized type name
{state} / {state_id}	Localized state and raw state enum
{input_amount} / {fuel_amount} / {output_amount}	Total amount across all unlocked slots in that category
{input_type} / {fuel_type} / {output_type}	Material in the first non-empty unlocked slot
{completed}	Completed cooking cycles
{fuel_efficiency_level} / {smelting_speed_level}	Fuel-efficiency and smelting-speed levels
{input_slot_level} / {fuel_slot_level} / {output_slot_level}	Slot levels and unlocked counts
{offline_smelting_enabled}	Whether this furnace can process offline, localized
{auto_output_delivery_enabled}	Whether online output delivery is active, localized
{completion_notification_enabled}	Whether completion notification is active, localized

Progress and time variables#

Variable	Description
{cook_progress} / {cook_progress_bar}	Current percentage and a filling 20-segment colored bar
{cook_elapsed_seconds} / {cook_total_seconds} / {cook_remaining_seconds}	Current-cycle elapsed, total, and remaining time
{cook_elapsed_time} / {cook_total_time} / {cook_remaining_time}	Current-cycle durations formatted by countdown_format
{cook_all_remaining_seconds} / {estimated_remaining_seconds}	Estimated remaining seconds for all valid input
{cook_all_remaining_time} / {estimated_remaining_time}	All-input remaining duration formatted by countdown_format
{cook_all_finish_time}	Estimated completion timestamp formatted by time_format
{burn_progress} / {burn_remaining_percent}	Burned and remaining percentages
{burn_progress_bar}	A draining 20-segment colored fuel bar
{burn_elapsed_seconds} / {burn_total_seconds} / {burn_remaining_seconds}	Time for the currently ignited fuel
{burn_elapsed_time} / {burn_total_time} / {burn_remaining_time}	Current-fuel durations formatted by countdown_format
{fuel_all_remaining_ms} / {fuel_all_remaining_seconds}	Active remainder plus all fuel stored in unlocked slots
{fuel_all_remaining_time}	All-fuel duration formatted by countdown_format
{fuel_sufficient_for_all_input}	Whether all available fuel can finish all current valid input

Both bar variables include their own colors. Remaining-second values round up to whole seconds; millisecond and elapsed/total second values keep their actual precision. Every *_time value joins only non-zero units from countdown_format; integers are not zero-padded, and a zero duration uses the second unit. The all-input estimate assumes an unchanged recipe, enough fuel, and unblocked output and is display-only.

Boolean variables use the localized text in lang/zh_CN.yml or lang/en_US.yml. Economy providers display localized 金币/点券 or Money/Points. Append _raw when a condition, script, or configuration needs a stable value, for example {offline_smelting_enabled_raw}, {fuel_sufficient_for_all_input_raw}, or {input_slot_provider_raw}. Raw values remain lowercase true, false, vault, or playerpoints.

Price and upgrade-menu variables#

The main menu provides {owned}, {max}, {remaining_slots}, {next_furnace_index}, and:

{furnace_purchase_price}
{furnace_purchase_provider}
{furnace_purchase_provider_available}

Each of the five level keys provides {<key>_level}, {<key>_next_level}, {<key>_maxed}, {<key>_price}, {<key>_provider}, and {<key>_provider_available}. Each permanent unlock provides {<key>_enabled} plus the same price, provider, and availability variables. Type-switch price prefixes are type_furnace, type_blast_furnace, and type_smoker.

Permission variables include {furnace_purchase_allowed}, {<key>_permission_max_level} and {<key>_allowed} for all five level properties, {<key>_allowed} for each permanent unlock, and {type_furnace_allowed}, {type_blast_furnace_allowed}, and {type_smoker_allowed}. Boolean display values are localized; menu conditions should use the matching _raw value.