Skip to main content

BasicMachine

info

BasicMachine is the base runtime wrapper for a machine block and its helper entity.

It resolves the machine entity, checks the scheduler, exposes the entity inventory, creates an EnergyStorage instance, and provides common UI/progress helpers. Most addons use Machine or Generator, but both are built on this class.

Hierarchy:

BasicMachine
|- Machine
|- Generator
`- MultiblockMachine

Index

Properties​

Pvalid
Pentity
Pblock
Pdimension
Pcontainer
Penergy
PshouldUpdateUI
PbaseRate
PprocessingInterval
Prate

Methods​

MsetRate
MsetLabel
Mon
Moff
MaddProgress
MgetProgress
MsetProgress
MdisplayProgress
MdisplayEnergy
MblockSlots
MunblockSlots

Constructor

new BasicMachine​

new BasicMachine(block: Block, options: { rate?: number, ignoreTick?: boolean })

Creates a runtime wrapper for the machine at block.

Parameters​

  • blockBlock

    The machine block in the world.

  • options.ratenumber

    Base rate designed around 20 TPS logic. Machine reads this from settings.machine.rate_speed_base; Generator reads it from settings.generator.rate_speed_base.

  • options.ignoreTickboolean

    When true, bypasses TickScheduler.shouldProcessMachine() for this wrapper instance.

Behavior​

  1. Sets valid to false.
  2. Resolves the helper entity from the block.
  3. Checks whether the UI is open with Utils.hasOpenUI(entity).
  4. Skips the tick unless ignoreTick is true or the scheduler allows processing.
  5. Creates EnergyStorage.
  6. Reads the entity inventory container.
  7. Calculates processingInterval and effective rate.
  8. Sets valid to true.

Typical usage:

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

Properties

valid​

Type: boolean

Whether this runtime wrapper is ready to run logic on the current tick.

valid is false if the helper entity is missing, the scheduler skipped this tick, or the entity inventory cannot be read.

entity​

Type: Entity

The helper entity associated with the machine block. It stores inventory, dynamic properties, tags, energy data, fluid data, and tick group state.

block​

Type: Block

The machine block represented by this runtime.

dimension​

Type: Dimension

The block's dimension.

container​

Type: Container

The inventory container from the helper entity.

energy​

Type: EnergyStorage

Energy manager attached to the helper entity.

shouldUpdateUI​

Type: boolean

true when at least one player has the machine UI open. UI-rendering helpers return early when this is false.

baseRate​

Type: number

The unscaled machine rate supplied through options.rate.

processingInterval​

Type: number

The tick interval returned by TickScheduler.getProcessingInterval(entity). Open UIs currently use a short interval; closed machines use the active scheduler profile interval.

rate​

Type: number

Effective per-run rate:

rate = baseRate * processingInterval;

Use this value for work performed only when valid is true.

Methods

setRate​

setRate(baseRate: number): void

Updates baseRate and recalculates rate using the current processingInterval.

setLabel​

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

Writes a label item into the machine inventory. The default slot is 1.

If text is a string, it becomes the item nameTag. If text is an array, the first item becomes nameTag and the remaining items become lore lines.

This method only updates while shouldUpdateUI is true.

on​

on(): void

Sets the block state utilitycraft:on to true.

off​

off(): void

Sets the block state utilitycraft:on to false.

addProgress​

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

Adds to the dynamic property dorios:progress_{index}. The default index is 0.

getProgress​

getProgress(index?: number): number

Reads dorios:progress_{index}. Returns 0 when unset.

setProgress​

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

Stores progress and optionally redraws the progress item.

type ProgressDisplayOptions = {
  slot?: number;      // default 2
  type?: string;      // default "progress_right_big_bar"
  display?: boolean;  // default true
  index?: number;     // default 0
  scale?: number;     // default 22 modern, 16 legacy
  legacy?: boolean;   // default false
};

value is clamped to at least 0.

displayProgress​

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

Displays the progress bar in the entity inventory.

Modern progress uses padded frame ids like:

utilitycraft:progress_right_big_bar_00
utilitycraft:progress_right_big_bar_22

When legacy: true, it uses the older non-padded frame naming:

utilitycraft:arrow_right_0
utilitycraft:arrow_right_16

displayEnergy​

displayEnergy(slot?: number): void

Delegates to this.energy.display(slot). The default slot is 0. This method only updates while shouldUpdateUI is true.

blockSlots​

blockSlots(slots: number[]): void

Fills empty inventory slots with the blocker item utilitycraft:arrow_right_0.

unblockSlots​

unblockSlots(slots: number[]): void

Clears blocker items from the given slots.

Example

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

machine.displayEnergy();
machine.addProgress(machine.rate);

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