Machine Definition
The machine_definition entry describes a machine type entirely from the panel. Placing its spawnItem creates a live instance that ticks autonomously, renders its hologram, persists across restarts and opens its menu on right-click.
Core
| Field | Default | Description |
|---|---|---|
processingType | SMELTING | The machine's behavior. See processing types. |
behaviors | [] | Explicit behavior set; leave empty to auto-derive from processingType. |
criteria / modifiers / triggers | [] | Standard triggerable fields, checked/fired when the definition is used. |
Slots
| Field | Default | Description |
|---|---|---|
inputSlots | 1 | Input slots for items to process. |
outputSlots | 1 | Output slots for results. |
hasFuelSlot | true | Whether the machine has a dedicated fuel slot. |
upgradeSlots | 0 | Upgrade module slots (0 = upgrades disabled). |
shearsSlots | 0 | Shear storage slots (SHEARING machines). |
filterSlots | 0 | Filter slots (SORTING machines). |
maxPerSlot | 64 | Max items per inventory slot. |
liquidTankCapacity | 0 | Liquid tank capacity in millibuckets (0 = no tank). |
Recipes & Fuel
Recipes and fuels use material name strings (e.g. IRON_INGOT), resolved at runtime.
recipes — list of MachineRecipeSpec:
| Field | Default | Description |
|---|---|---|
inputMaterial / outputMaterial | "" | Input and output materials. |
outputAmount | 1 | Output count. |
cookTime | 200 | Processing duration in ticks. |
fuelCost | 0 | Fuel units per operation. |
energyCost | 0 | Energy units per operation. |
liquidInputName / liquidInputAmount | "" / 0 | Liquid consumed (millibuckets). |
liquidOutputName / liquidOutputAmount | "" / 0 | Liquid produced (millibuckets). |
fuelTypes — list of MachineFuelSpec: material, burnTime (ticks), fuelValue (units).
Energy
| Field | Default | Description |
|---|---|---|
energyCapacity | 0 | Storage capacity (0 = no energy system). Used by ENERGY_CELL. |
energyGenerationPerTick | 0 | Output of ENERGY_GENERATOR machines. |
energyConsumptionPerTick | 0 | Draw of consumer machines. |
Consumers must be linked to the grid before they draw. The pool is shared per world in the public build; energy physically lives in the ENERGY_CELL machines.
Tiers & Upgrades
allowedUpgrades — which MachineUpgradeTypes this machine accepts (SPEED, YIELD, ENERGY_EFFICIENCY, FORTUNE, RANGE, FILTER). Empty = refuses upgrades.
upgradeSpecs — list of MachineUpgradeSpec: material, type, magnitude (SPEED/YIELD multiply; FORTUNE is a 0–1 chance; RANGE adds blocks; FILTER adds slots).
tiers — list of MachineTierSpec, ascending; the highest unlocked wins and stacks multiplicatively with modules:
| Field | Default | Description |
|---|---|---|
name | "" | Display name (e.g. T2). |
researchNode | "" | Research gate. Public build: blank = unlocked; non-blank = locked. |
speedMultiplier / yieldMultiplier / energyMultiplier | 1.0 | Operation modifiers. |
fortuneChance | 0.0 | Chance (0–1) to double an operation's output. |
Archetype-specific
| Field | Default | Used by |
|---|---|---|
chargeables / chargeRatePerSecond | [] / 0 | CHARGING — items fillable with energy (charge rides in the item's persistent data). |
assemblerMode | SPAWN | ASSEMBLER — SPAWN (ingredients + energy → entity) or COLLECT (harvest nearby produce). |
assemblerEntityType / assemblerIngredients | "" / [] | ASSEMBLER — target entity and per-operation ingredients. |
assemblerEnergyCost / assemblerInterval / assemblerRange | 0 / 100 / 5.0 | ASSEMBLER — cost, cadence (ticks), COLLECT radius. |
vacuumRange | 0.0 | VACUUM — collection radius in blocks. |
shearRange / shearInterval | 5.0 / 100 | SHEARING — radius and cadence. |
CONVEYOR, GENERATOR and VOID reuse existing fields rather than adding their own:
| Archetype | Configured with |
|---|---|
CONVEYOR | The single output slot is the belt buffer (outputSlots ≥ 1 + guiStorageRef). Direction is the placement yaw. Throughput scales with hopperTransferAmount and the SPEED modifier. |
GENERATOR | Each recipe with a blank inputMaterial is produced into the outputs on the first recipe's cookTime. Optional energyCost powers it. Products only spawn when they all fit. |
VOID | Items in the input slots are deleted. With filterSlots set, only items matching a filter are destroyed; with none, everything fed in is voided. |
Automation & Redstone
Every placed machine ticks autonomously on its owning region, so hoppers, redstone and processing all run without a viewer and are safe under Folia. Pure transforms (recipes, generators) also catch up the work missed while their chunk was unloaded, capped at 30 minutes and bounded by available inputs, fuel and energy.
| Field | Default | Description |
|---|---|---|
hopperInterval / hopperTransferAmount | 100 / 1 | Data-driven hopper automation (0 interval = disabled). Pulls from a container above into the inputs; pushes finished products into adjacent containers. |
redstoneMode | IGNORE | IGNORE, DISABLE_WHEN_POWERED (a signal pauses it) or REQUIRE_POWER (only runs while powered). A paused machine advances no progress and pays nothing. |
ejectWhenPowered | false | When powered, ejects finished products into adjacent containers even without a hopper. |
redstoneComparatorOutput | NONE | What a neighbouring comparator reads: PROGRESS, INPUT_FILL, OUTPUT_FILL or ENERGY_FILL (0–15). Requires BTC-CORE. |
redstonePulseOnComplete | false | Emit a short redstone pulse each time an operation completes. Requires BTC-CORE. |
redstonePulseTicks | 4 | Duration of the completion pulse in ticks. |
Comparator output and completion pulses need a block to emit redstone, which no plain Bukkit block can do. They are driven through the BTC-CORE server hook (BTCCoreAPI.setEmittedRedstonePower); on a server without it these fields are simply inert. Redstone inputs (redstoneMode, ejectWhenPowered) work everywhere.
Visuals & Hologram
| Field | Default | Description |
|---|---|---|
spawnItem | empty | Item that places the machine and is returned on pickup. |
visualType | NONE | NONE, FURNITURE or CUSTOM_BLOCK (CraftEngine ids below). |
furnitureId / customBlockId | "" | CraftEngine model ids. |
alignWithPlayerYaw | true | Align placed furniture with the player's yaw. |
hologramEnabled | true | Toggle the status hologram. |
hologramOffsetHeight | 1.2 | Height above the machine block. |
hologramProgressBarFormat | — | Supports %bar%, %percent%, %time_left%. |
hologramIdleMessage / hologramActiveMessage / hologramLowEnergyMessage / hologramFullMessage | — | MiniMessage status lines. |
Limits & Persistence
| Field | Default | Description |
|---|---|---|
machineLimit | 0 | Max instances per player (0 = unlimited). Bypass: machine.protection.bypass. |
perIslandLimit / islandLimitUpgradeKey | 0 / "" | Island-scoped limits — inert in the public build (no island system). |
storageRef | empty | Required — machine_data_artifact persisting instances. |
guiStorageRef | empty | STORAGE machines — OmniGUI storage entry backing the stored items (one group per instance). |