BasicMachine class

Namespace: DoriosCore · Package: DoriosCore/index.js

BasicMachine is the base runtime wrapper shared by machines and generators. It resolves the block's helper entity, applies scheduler rules, exposes its inventory and energy storage, prepares item/liquid/gas IO documents, and provides common UI and progress helpers.

import { BasicMachine } from "DoriosCore/index.js";

Definition

class BasicMachine

Inheritance:

BasicMachine
├─ Machine
│  └─ MultiblockMachine
└─ Generator
   └─ MultiblockGenerator

Most addons instantiate Machine or Generator. Extend BasicMachine directly only when the runtime is neither a processing machine nor an energy generator.

Constructor

new BasicMachine(block, options)

new BasicMachine(block: Block, options: BasicMachineOptions)

Creates a runtime wrapper for the helper entity associated with block.

Parameters

Name	Type	Required	Description
block	Block	Yes	Machine block in the world.
options	BasicMachineOptions	Yes	Runtime rate and scheduler behavior.
options.rate	number	Yes	Base rate designed for ordinary 20 TPS logic. DoriosCore does not provide a fallback at this level.
options.ignoreTick	boolean	No	When true, bypasses scheduler throttling for this instance. Defaults to false.

The constructor sets valid to false before resolving runtime state. It becomes true only after the helper entity, scheduler check, inventory, energy manager, effective rate, and IO documents have been prepared.

const runtime = new BasicMachine(block, { rate: 20 });
if (!runtime.valid) return;

warning

Always guard valid. An invalid wrapper usually means the scheduler did not select this machine on the current tick; it is not necessarily an error.

Properties

Property	Type	Description
valid	boolean	Whether the runtime is ready for this processing tick.
entity	Entity	Helper entity paired with the block. Use only after the validity guard.
block	Block	Block represented by this runtime.
dimension	Dimension	Dimension containing the block.
container	Container	Inventory container exposed by the helper entity.
energy	EnergyStorage	Energy manager bound to the helper entity.
shouldUpdateUI	boolean	Whether a player currently has this container UI open.
baseRate	number	Rate before scheduler-interval scaling.
processingInterval	number	Effective interval returned by TickScheduler.
rate	number	baseRate × processingInterval. Use this for work done on valid ticks.
itemIOReady	boolean	Whether the persisted complex item IO document is ready locally.
fluidIOReady	boolean	Whether the indexed-liquid IO document is ready locally.
gasIOReady	boolean	Whether the indexed-gas IO document is ready locally.

Methods

setRate(baseRate)

setRate(baseRate: number): void

Updates baseRate and recalculates rate with the current processingInterval.

Parameter	Type	Description
baseRate	number	New unscaled processing or generation rate.

setLabel(text, slot)

setLabel(text: string | string[], slot?: number): void

Writes the machine label item while shouldUpdateUI is true.

Parameter	Type	Default	Description
text	string | string[]	—	A string becomes the item name. In an array, the first entry is the name and remaining entries become lore.
slot	number	1	Inventory slot used by the label. Existing items in the slot are reused.

machine.setLabel([
  "§r§aCrusher Running",
  "§r§7Input: §fCobblestone",
  "§r§7Output: §fGravel",
]);

on()

on(): void

Sets the block state utilitycraft:on to true. The block definition and resource pack can use this state for its active texture.

off()

off(): void

Sets the block state utilitycraft:on to false.

addProgress(amount, index)

addProgress(amount: number, index?: number): void

Adds amount to one dynamic progress channel.

Parameter	Type	Default	Description
amount	number	—	Value added to the current progress. May be negative.
index	number	0	Progress channel stored as dorios:progress_{index}.

getProgress(index)

getProgress(index?: number): number

Returns the current value of a progress channel, or 0 when it has not been set.

Parameter	Type	Default	Description
index	number	0	Progress channel to read.

setProgress(value, maxValue, options)

setProgress(value: number, maxValue?: number, options?: ProgressOptions): void

Stores a nonnegative progress value and optionally redraws its bar.

Parameter	Type	Default	Description
value	number	—	New progress value. Values below zero are stored as zero.
maxValue	number	800	Value represented by a full bar.
options.slot	number	2	Inventory slot containing the progress item.
options.type	string	progress_right_big_bar	Item-ID suffix for modern progress frames.
options.display	boolean	true	Whether to call displayProgress() after storing.
options.index	number	0	Progress channel.
options.scale	number	16 when passed through this method	Maximum visual frame forwarded to the renderer.
options.legacy	boolean	false	Uses non-padded legacy frame IDs when true.

displayProgress(maxValue, options)

displayProgress(maxValue?: number, options?: ProgressOptions): void

Draws the selected progress channel as an item frame while the UI is open. It returns without changing the container when maxValue is zero or negative.

Parameter	Type	Default	Description
maxValue	number	800	Value represented by a full bar.
options.slot	number	2	Destination inventory slot.
options.type	string	progress_right_big_bar	Modern frame prefix; legacy mode defaults to arrow_right.
options.index	number	0	Progress channel to render.
options.scale	number	22 modern, 16 legacy	Highest visual frame number.
options.legacy	boolean	false	Chooses legacy non-padded IDs.

Modern IDs are padded, for example utilitycraft:progress_right_big_bar_00. Legacy IDs use names such as utilitycraft:arrow_right_0.

displayEnergy(slot)

displayEnergy(slot?: number): void

Calls energy.display(slot) only while the UI is open.

Parameter	Type	Default	Description
slot	number	0	Inventory slot for the energy bar.

processIO(limits)

processIO(limits?: ProcessIOLimits): ProcessIOSummary

Processes enabled item, liquid, and gas faces using the registered IO documents. Resource indices are independent from inventory slots.

Parameter	Type	Default	Description
limits.maxInputSlotsScannedPerTick	number	9	External inventory slots examined per enabled input face.
limits.maxOutputSlotsMovedPerTick	number	9	Machine output slots attempted per enabled output face.
limits.maxFluidMovedPerTick	number	2500	Total liquid amount moved during the call.
limits.maxGasMovedPerTick	number	2500	Total gas amount moved during the call.

Returns:

interface ProcessIOSummary {
  itemsMoved: number;
  inputSlotsScanned: number;
  fluidMoved: number;
  gasMoved: number;
}

Invalid runtimes return a summary containing four zeros. Item input scanning maintains a rotating cursor so large neighboring inventories are scanned fairly across ticks.

See Process machine IO for processing order, face resolution, fallbacks, fairness, and adapter selection.

const moved = machine.processIO({
  maxFluidMovedPerTick: 1000,
  maxGasMovedPerTick: 500,
});

blockSlots(slots)

blockSlots(slots: number[]): void

Fills each empty slot with the standard blocker item. Existing items are not replaced.

Parameter	Type	Description
slots	number[]	Inventory slot indices to reserve.

unblockSlots(slots)

unblockSlots(slots: number[]): void

Clears only slots containing the standard blocker item; ordinary items are preserved.

Example

import { BasicMachine } from "DoriosCore/index.js";

const machine = new BasicMachine(block, { rate: 20 });
if (!machine.valid) return;

machine.processIO();
machine.addProgress(machine.rate);
machine.displayEnergy();
machine.displayProgress(800);

if (machine.getProgress() >= 800) {
  machine.setProgress(0, 800);
}

Remarks

• Construct a new runtime only in the machine's tick path; do not retain it between ticks.
• UI methods are intentionally skipped while the container is closed.
• Networks remain owned by UtilityCore. processIO() operates through compatible container and neighbor abstractions exposed to DoriosCore.