Skip to main content

Machine

info

Machine is the main operational class used by UtilityCraft machines.

It extends BasicMachine and inherits all its base properties and methods, including:

  • entity access
  • block access
  • dimension access
  • inventory container access
  • progress tracking
  • energy integration
  • tick refresh validation
  • progress and energy UI rendering

The Machine class adds higher-level machine behavior such as:

  • machine settings access
  • upgrade handling
  • boost calculation
  • item transfer automation
  • item pulling from containers
  • machine placement and destruction logic
  • energy cost management
  • machine status and warning displays

Hierarchy:

BasicMachine
└─ Machine

All methods and properties from BasicMachine are available here.
This page documents the additional properties and methods introduced by Machine.

Index

Properties​

Psettings
Pupgrades
Pboosts

Static Methods​

MonDestroy
MspawnEntity

Methods​

MtransferItems
MpullItemsFromAbove
MdisplayProgress
MsetEnergyCost
MgetEnergyCost
MdisplayEnergy
MshowWarning
MshowStatus

Constructor

new Machine​

new Machine(block: Block, settings: MachineSettings)

Creates a new machine instance using the infrastructure provided by BasicMachine.

Parameters​

  • blockBlock

    Block representing the machine in the world.

  • settingsMachineSettings

    Machine configuration object that defines machine behavior such as:

    • base rate
    • energy capacity
    • fluid capacity
    • upgrades
    • rotation behavior

Behavior​

The constructor performs the following steps:

  1. Calls BasicMachine constructor using settings.machine.rate_speed_base.
  2. Validates that the machine entity exists and that the current tick is valid.
  3. Stores the provided machine settings.
  4. Reads upgrade levels from configured upgrade slots.
  5. Calculates machine boosts.
  6. Recalculates the effective machine rate.

Properties

settings​

Type: MachineSettings

Full machine configuration object passed into the constructor.

const settings = machine.settings

This property stores the machine definition used by the class, including values such as:

  • machine energy capacity
  • machine fluid capacity
  • base rate
  • upgrade slot definitions
  • rotation options

It is typically used by subclasses or machine implementations that need access to their full configuration.

upgrades​

Type: UpgradeLevels

Upgrade levels currently detected inside the machine upgrade slots.

const upgrades = machine.upgrades

Typical structure:

{
  energy: 0,
  range: 0,
  speed: 0,
  ultimate: 0
}

These values are calculated from the items currently placed in the configured upgrade slots.

boosts​

Type: { speed: number, consumption: number }

Calculated boost values derived from installed upgrades.

const boosts = machine.boosts

Structure:

{
  speed: 1,
  consumption: 1
}

Meaning​

  • speed increases the machine processing speed
  • consumption affects the effective energy cost multiplier

These values are used internally to adjust machine rate and operation cost.

Static Methods

onDestroy​

Machine.onDestroy(event): boolean

Handles the destruction of a machine block.

Behavior​

When a machine is broken:

  1. Retrieves the machine entity associated with the block.
  2. Reads stored energy and fluid data.
  3. Encodes that data into the dropped block item lore.
  4. Drops all items stored in the machine inventory.
  5. Removes the machine entity.
  6. Spawns the machine block item with stored information.

If the player is in Creative mode, the original block item drop is removed so the machine can be replaced by the custom preserved drop.

Parameters​

  • eventobject

    Block break event data containing block, broken permutation, player, and dimension.

Returns​

Type: boolean

Returns true if a machine entity was found and processed.
Returns false if no machine entity was associated with the block.

spawnEntity​

Machine.spawnEntity(event, config, callback?)

Spawns the machine entity when the block is placed.

Behavior​

  1. Reads the item held by the player.
  2. Extracts stored energy and fluid information from the placed item.
  3. Handles optional machine rotation before final placement.
  4. Spawns the machine entity.
  5. Initializes machine energy storage.
  6. Initializes fluid storage if the machine supports fluids.
  7. Executes an optional callback after initialization.
  8. Updates adjacent networks.

Parameters​

  • eventobject

    Placement event data containing block, player, permutation to place, and optional cancel flag.

  • configMachineSettings

    Machine configuration describing entity type, capacities, and placement behavior.

  • callbackfunction

    Optional callback executed after the entity has been spawned and initialized.

Methods

transferItems​

transferItems(): boolean

Transfers items from the machine inventory into the container located behind the machine.

Behavior​

  1. Reads the machine facing direction using utilitycraft:axis.
  2. Resolves the opposite direction vector.
  3. Finds the adjacent block in that opposite direction.
  4. Gets the machine output slot range.
  5. Transfers items using DoriosAPI.containers.transferItemsAt().

Returns​

Type: boolean

Returns true if the transfer attempt was executed.
Returns false if the machine facing state was missing or invalid.

pullItemsFromAbove​

pullItemsFromAbove(targetSlot: number): boolean

Pulls items from the container directly above the machine into a specific internal slot.

Parameters​

  • targetSlotnumber

    Machine inventory slot where the item should be inserted.

Behavior​

  • Checks whether the block above is a supported vanilla container.
  • Reads the source container inventory.
  • If the target slot is empty, moves the first compatible stack.
  • If the target slot already contains the same item, merges stacks until full.

Returns​

Type: boolean

Returns true if an item transfer occurred.
Returns false if no compatible transfer was possible.

displayProgress​

displayProgress(options?: object): void

Displays the machine progress bar using the configured energy cost as the maximum progress value.

This method overrides the base progress display behavior from BasicMachine.

Parameters​

  • optionsobject

    Optional progress display configuration.

    Supported options:

    slot?: number
    type?: string
    index?: number
    scale?: number

Notes​

Internally this method calls the base displayProgress() implementation, but uses getEnergyCost() to determine the progress maximum.

setEnergyCost​

setEnergyCost(value: number, index?: number): void

Sets the energy cost required to complete one machine operation.

The value is stored as a dynamic property on the machine entity.

Parameters​

  • valuenumber

    Energy cost representing full progress.

  • indexnumber

    Optional cost index for machines that track multiple processes.

getEnergyCost​

getEnergyCost(index?: number): number

Returns the stored energy cost for the specified process index.

Parameters​

  • indexnumber

    Optional cost index.

Returns​

Type: number

If no value is stored, the default returned value is:

800

displayEnergy​

displayEnergy(slot?: number): void

Displays the machine energy bar in the inventory UI.

Parameters​

  • slotnumber

    Optional inventory slot used for the energy display.

Notes​

Internally delegates to this.energy.display(slot).

showWarning​

showWarning(message: string, options?: object): void

Displays a warning label in the machine interface.

Parameters​

  • messagestring

    Warning text shown to the player.

  • optionsobject

    Optional warning behavior settings.

    Supported options:

    resetProgress?: boolean
    displayProgress?: boolean
    slot?: number
    type?: string
    index?: number
    scale?: number

Behavior​

  • optionally resets progress
  • optionally redraws the progress bar
  • redraws the energy bar
  • turns the machine off
  • shows formatted machine statistics
  • displays the warning message

This method is commonly used for states such as:

  • missing input
  • blocked output
  • invalid recipe
  • missing conditions

showStatus​

showStatus(message: string): void

Displays a normal machine status label.

Parameters​

  • messagestring

    Status text shown to the player.

Behavior​

  • redraws the energy bar
  • displays current machine boost information
  • displays current operation cost
  • displays current machine rate

Unlike showWarning, this method does not reset progress.

Example

const machine = new Machine(block, settings)

if (!machine.valid) return

machine.displayEnergy()
machine.displayProgress()

machine.showStatus("Running")
machine.transferItems()

Notes

Machine is the primary implementation class used by most UtilityCraft machines.

Examples include:

  • Crusher
  • Incinerator
  • Electro Press
  • Block Breaker
  • Block Placer

These machines inherit all base infrastructure from BasicMachine and then use Machine for common machine behavior such as upgrades, UI, transfer logic, and preserved placement data.