PlaceholderAPI

When PlaceholderAPI is installed, KaFurnace automatically registers its internal %kafurnace_*% expansion. No separate eCloud download is required. PlaceholderAPI is a soft dependency; furnaces, databases, and built-in UI variables continue to work without it.

Placeholder format#

KaFurnace placeholders use this format:

%kafurnace_<furnace number>_<field>%

The furnace number is 1..10 and matches the stable number shown in the player's main menu. For example, %kafurnace_1_input_amount% is the input amount in furnace 1.

Identity, state, and levels#

Field	Example	Description
furnace_index	%kafurnace_1_furnace_index%	Stable furnace number for the owner
furnace_type	%kafurnace_1_furnace_type%	FURNACE, BLAST_FURNACE, or SMOKER
state / state_id	%kafurnace_1_state%	Raw state enum name
completed	%kafurnace_1_completed%	Completed cooking cycles
fuel_efficiency_level	%kafurnace_1_fuel_efficiency_level%	Fuel-efficiency level
smelting_speed_level	%kafurnace_1_smelting_speed_level%	Smelting-speed level
input_slot_level	%kafurnace_1_input_slot_level%	Input-slot level and unlocked count
fuel_slot_level	%kafurnace_1_fuel_slot_level%	Fuel-slot level and unlocked count
output_slot_level	%kafurnace_1_output_slot_level%	Output-slot level and unlocked count
offline_smelting / offline_smelting_enabled	%kafurnace_1_offline_smelting_enabled%	Whether offline cooking is enabled, localized
auto_output_delivery / auto_output_delivery_enabled	%kafurnace_1_auto_output_delivery_enabled%	Whether online output delivery is enabled, localized
completion_notification / completion_notification_enabled	%kafurnace_1_completion_notification_enabled%	Whether one-time completion notification is enabled, localized

PAPI state is not localized. Like state_id, it returns IDLE, RUNNING, PAUSED_OFFLINE, or BLOCKED_OUTPUT.

Boolean fields return localized 是/否 or Yes/No. Append _raw to any boolean field for stable true/false, such as %kafurnace_1_offline_smelting_enabled_raw%, when writing conditions or scripts.

Item slots#

Field	Example	Description
input_amount	%kafurnace_1_input_amount%	Total amount across all unlocked input slots
input_type	%kafurnace_1_input_type%	Material enum in the first non-empty unlocked input slot
fuel_amount	%kafurnace_1_fuel_amount%	Total unignited amount across all unlocked fuel slots
fuel_type	%kafurnace_1_fuel_type%	Material enum in the first non-empty unlocked fuel slot
output_amount	%kafurnace_1_output_amount%	Total amount across all unlocked output slots
output_type	%kafurnace_1_output_type%	Material enum in the first non-empty unlocked output slot

Ignited fuel has already been removed from the fuel slot. Use the fuel-time placeholders for its remaining duration instead of fuel_amount.

Cooking progress and time#

Field	Description
cook_progress / cook_percent	Current cooking percentage from 0..100
cook_progress_bar	Colored cooking bar made from exactly 20 `
cook_elapsed_ms / cook_elapsed_seconds	Elapsed time in the current cycle
cook_progress_seconds / smelt_progress_seconds	Aliases for elapsed seconds
cook_elapsed_time / cook_progress_time / smelt_progress_time	Elapsed cycle time formatted by countdown_format
cook_total_ms / cook_total_seconds	Total recipe time for the current cycle
smelt_total_seconds	Alias for total cycle seconds
cook_total_time / smelt_total_time	Total cycle time formatted by countdown_format
cook_remaining_ms / cook_remaining_seconds	Remaining time in the current cycle
smelt_remaining_seconds	Alias for remaining cycle seconds
cook_remaining_time / smelt_remaining_time	Remaining cycle time formatted by countdown_format
cook_all_total_ms / cook_all_total_seconds	Estimated total time for all current input
cook_all_total_time	Estimated all-input total formatted by countdown_format
cook_all_remaining_ms / cook_all_remaining_seconds	Estimated remaining time for all current input
estimated_all_seconds / estimated_remaining_seconds	Aliases for all-input remaining seconds
cook_all_remaining_time / estimated_all_time / estimated_remaining_time	All-input remaining time formatted by countdown_format
cook_all_finish_epoch_ms	Estimated Unix completion timestamp in milliseconds
cook_all_finish_time	Estimated server-time-zone completion formatted by time_format

Example:

Progress: %kafurnace_1_cook_progress_bar% %kafurnace_1_cook_progress%%
Current cycle: %kafurnace_1_cook_remaining_time% left
All input: %kafurnace_1_estimated_remaining_time% left

The all-input estimate assumes an unchanged recipe, enough fuel, and unblocked output. It is display-only and must not control payments, rewards, or deadlines.

Fuel progress and time#

Field	Description
burn_progress	Percentage of the current fuel already burned, from 0..100
burn_remaining_percent / burn_percent	Percentage of the current fuel remaining
burn_progress_bar	Colored fuel bar made from exactly 20 `
burn_elapsed_ms / burn_elapsed_seconds	Elapsed burn time
burn_progress_seconds / fuel_elapsed_seconds	Aliases for elapsed burn seconds
burn_elapsed_time / burn_progress_time / fuel_elapsed_time	Elapsed burn time formatted by countdown_format
burn_total_ms / burn_total_seconds	Total duration of the current fuel
fuel_total_seconds / fuel_time_seconds	Aliases for total fuel seconds
burn_total_time / fuel_total_time / fuel_time	Current fuel total formatted by countdown_format
burn_remaining_ms / burn_remaining_seconds	Remaining burn time
fuel_remaining_seconds	Alias for remaining fuel seconds
burn_remaining_time / fuel_remaining_time	Remaining burn time formatted by countdown_format
fuel_all_remaining_ms / fuel_all_remaining_seconds	Combined burn time from the active remainder and every stored fuel item
fuel_all_remaining_time	Combined fuel time formatted by countdown_format
fuel_sufficient_for_all_input	Whether all fuel is sufficient, localized; append _raw for true/false

Both progress-bar fields return Minecraft color control codes ready for display. All remaining-second fields round up to whole seconds; millisecond fields and elapsed/total second fields retain their 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-fuel estimate applies the current fuel-efficiency multiplier to every item in all unlocked fuel slots and adds the remaining duration of the ignited fuel. fuel_sufficient_for_all_input returns localized no when there is no input or the current recipe cannot be estimated, while its _raw field returns false.

Using other PAPI placeholders in the UI#

Titles, button names, and lore in ui/main.yml, ui/furnace.yml, and ui/upgrade.yml can use placeholders from other expansions:

name: "&e%player_name%'s Furnace 1"
lore:
  - "&7Play time: &f%statistic_time_played%"

Text is resolved in this order: KaFurnace built-in {variables}, PAPI %placeholders%, then & colors. Colors such as &a returned by a PAPI expansion therefore also work. Without PlaceholderAPI, %placeholders% remain unchanged in UI text.

Empty values and refresh behavior#

• A valid but unpurchased furnace number returns 0 for numeric amounts and times, a zero duration for readable *_time, localized no for fuel_sufficient_for_all_input, a 20-segment dark-gray empty progress bar, AIR for material types, IDLE for state, and - for the estimated finish time.
• Invalid numbers, unknown fields, and requests without player context return an empty string.
• Localized {furnace_type_name} and the button-specific {percent} context are not exposed as PAPI fields.
• Reads use thread-safe immutable snapshots and do not advance a furnace, so values may trail by up to one default 5-tick engine interval.
• KaFurnace placeholders are safe for asynchronous reads. Other third-party expansions used in UI text remain responsible for their own Folia thread compatibility.

These placeholders can be used in scoreboards, chat formats, Tab lists, menu plugins, and other plugins that support PlaceholderAPI.