API Fuels

Fuels

Lua API / Fuels

Fuel declarations assign fixed burn durations to items. They can extend vanilla furnaces or form named policies for BetaMoon machines. Durations use game ticks; Minecraft normally runs 20 ticks per second.

On this page

• Built-in furnace set
• betamoon.fuels:add(definition)
  • Fuel registration fields
• Registration references
  • registration:override(definition)
  • registration:remove()
• betamoon.fuels.sets:add(definition)
  • Fuel-set field definitions
• Fuel-set lookup
  • betamoon.fuels.sets:get(key)
  • betamoon.fuels.sets:getRequired(key)
  • betamoon.fuels.sets:list()
• Fuel-set references
  • set:getBurnTime(stack)
  • set:contains(stack)
  • set:remove()
• Fuel queries
• Matching order
• Using sets in machines
• Reload and compatibility

Built-in furnace set

betamoon.mc.fuels.furnace is the key "minecraft:fuel/furnace". It represents the effective furnace policy: BetaMoon registrations, Minecraft's native fuels and compatible ModLoader fuels.

Native Beta 1.7.3 durations are:

Fuel	Ticks
Wood-material block	300
Stick	100
Coal or charcoal	1,600
Lava bucket	20,000
Sapling	100

betamoon.fuels:add(definition)

Registers a fixed item/damage rule and returns a registration reference. Omitting set targets the built-in furnace set, which makes the item usable in vanilla furnaces and BetaMoon machines using that set.

local peat = betamoon.items:getRequired("mymod:item/peat")

local registration = betamoon.fuels:add {
    item = peat,
    burnTime = 800
}

Fuel registration fields

Field	Type	Requirement / default
item	item reference, canonical key, numeric ID or stack descriptor	Required registered item. A plain reference/key/ID matches every damage value.
burnTime	integer	Required, 1 through 1,073,741,823 ticks.
damage	integer	Optional exact damage value.
set	fuel-set reference or key	Defaults to betamoon.mc.fuels.furnace.

A stack descriptor can supply the exact damage value when damage is omitted:

betamoon.fuels:add {
    item = { id = 5000, damage = 2, count = 1 },
    burnTime = 2400
}

damage selects an item subtype; it does not describe durability consumed while burning. Fuel registration consumes one whole item when a machine acquires it.

Registration references

The returned reference exposes item, damage, burnTime, enabled, set, owner and exists.

registration:override(definition)

Overrides burnTime and/or enabled and returns a removable handle. Disabling a rule keeps its stable reference but removes it from effective matching until the layer is removed.

registration:remove()

Removes this exact registration and returns true. A second removal returns false. Removing a rule does not alter fuel already consumed by a burning machine.

local removed = registration:remove()

betamoon.fuels.sets:add(definition)

Creates a named fuel policy. A key must use namespace:fuel/name. include composes other sets in declaration order; it keeps a live relationship rather than copying their current entries.

local boilerFuels = betamoon.fuels.sets:add {
    key = "mymod:fuel/boiler",
    include = {
        betamoon.mc.fuels.furnace
    }
}

betamoon.fuels:add {
    set = boilerFuels,
    item = "mymod:item/coke",
    burnTime = 3200
}

Fuel-set field definitions

A set without include accepts only its own registrations:

local arcaneFuels = betamoon.fuels.sets:add {
    key = "mymod:fuel/arcane"
}

Unknown includes, repeated includes, duplicate keys, self-inclusion and inclusion cycles are errors.

Fuel-set lookup

betamoon.fuels.sets:get(key)

Returns a fuel-set reference or nil.

betamoon.fuels.sets:getRequired(key)

Returns a fuel-set reference or raises an error when absent.

betamoon.fuels.sets:list()

Returns all current set references in stable registration order, including the built-in furnace set.

Fuel-set references

A set reference exposes key, owner, exists, and its live include list. set:override { include = {...} } replaces the complete include list after validating missing sets, duplicates, and cycles.

set:getBurnTime(stack)

Returns the matching duration or 0.

set:contains(stack)

Returns whether the set accepts the stack.

set:remove()

Removes a custom set and its direct registrations, returning true. The built-in furnace set cannot be removed, so its method returns false.

Fuel queries

The root methods default to the furnace set:

local furnaceTicks = betamoon.fuels:getBurnTime(stack)
local acceptedByFurnace = betamoon.fuels:isFuel(stack)

local boilerTicks = betamoon.fuels:getBurnTime(stack, boilerFuels)
local acceptedByBoiler = betamoon.fuels:isFuel(stack, boilerFuels)

getBurnTime returns 0 for an unaccepted stack. Queries do not consume or alter the supplied stack.

betamoon.fuels:find(query), first(query), and one(query) find registration references by owner, set, item, damage, and enabled. The find result supports overrideAll.

Matching order

Resolution is deterministic within each set:

1. a direct exact-damage registration;
2. a direct any-damage registration;
3. included sets in declaration order;
4. for the built-in furnace set, Minecraft and ModLoader fuel behavior.

This lets a machine-specific direct rule override an included furnace duration. An explicit BetaMoon registration in the furnace set similarly overrides the native duration for that item. Native fuels remain enabled.

Using sets in machines

Passing a set to consumeFuel validates and consumes exactly one item, leaves a native container item such as an empty bucket, and returns the duration. It changes nothing and returns 0 when the item is not accepted.

local burnTime = ctx.entity.inventory:consumeFuel("fuel", boilerFuels)

Use the same set on a container slot to reject invalid manual placement and shift-click insertion:

slots = {
    { slot = "fuel", x = 56, y = 53, acceptsFuel = boilerFuels }
}

Machine logic must still call consumeFuel or query the set. Container filters are interaction assistance; save data, scripts and other mods can change inventories without passing through a GUI slot.

See Tile entities and Containers.

Reload and compatibility

Fuel sets and registrations are owned by the declaring script and removed when that reloadable script unloads. A machine keeps the remaining ticks from fuel it already acquired; its next acquisition uses the current rules.

Vanilla furnaces and BetaMoon machines support both exact-damage and any-damage fuel rules. Other mods' machines use BetaMoon fuel registrations only when they use Minecraft or ModLoader furnace fuel behavior; machines with separate fuel rules are unaffected.

Examples: custom furnace fuel, machine-specific composed set.