---
description: Interact directly with the machine in JS scripts
---

# Machine

Machine is one of the object provided in the [function requirement context](context).

It contains various methods for interacting with the machine.

### Methods

<details>

<summary>Of</summary>

Create a Machine object from a BlockEntity or [BlockContainer](https://kubejs.com/wiki/kubejs/BlockContainerJS/) objects.

```javascript
var machine = CustomMachine.of(blockEntity);
var machine = CustomMachine.of(blockContainer);
```

</details>

<details>

<summary>Data</summary>

Add a way to store custom data in the machine.

The stored data will be stored in the machine as NBT and saved when the machine is unloaded, preventing loosing the data, for example, when the game is quitted.

KubeJS will treat the data as a Map.

<pre class="language-java"><code class="lang-java"><strong>//Get the data :
</strong><strong>var data = ctx.machine.data;
</strong>
//Put a number in the data :
data.power = 2;

//Increment that number : 
data.power++
</code></pre>

</details>

<details>

<summary>Energy</summary>

```javascript
var machine = ctx.machine;

//Return the energy stored in the machine internal buffer.
var energy = machine.energyStored;

//Return the maximum capacity of the machine energy storage.
var energyCapacity = machine.energyCapacity;

//Set the current energy of the machine, this override the previous energy stored.
//newEnergyAmount must be a positive integer value.
//Max value : 9,223,372,036,854,775,807
machine.setEnergyStored(newEnergyAmount);

//Return the amount of energy that was successfully added to the machine (or amountToAdd if all the energy was inserted).
//If simulate is `false` the energy will really be inserted, otherwise it wont.
//amountToAdd MUST be a positive integer value.
var addedEnergy = machine.addEnergy(amountToAdd, simulate);

//Return the amount of energy that was successfully removed from the machine (or amountToRemove if all the energy was extracted).
//If simulate is `false` the energy will really be extracted, otherwise it wont.
//amountToRemove MUST be a positive integer value.
var removedEnergy = machine.removeEnergy(amountToRemove, simulate);
```

</details>

<details>

<summary>Fluids</summary>

```javascript
var machine = ctx.machine;

//Return the fluid stored in the specified tank.
//The returned fluid is a KubeJS FluidStackJS, see code: https://github.com/KubeJS-Mods/KubeJS/blob/1.16/main/common/src/main/java/dev/latvian/kubejs/fluid/FluidStackJS.java
var fluid = machine.getFluidStored("tankID");

//Return the capacity of the specified tank.
var capacity = machine.getFluidCapacity("tankID");

//Put the specified fluid in the specified tank, this will override the previous stored fluid.
//The passed fluid must be a KubeJS FluidStackJS, create one with Fluid.of("namespace:fluidID", amount)
machine.setFluidStored("tankID", fluid);

//Add the specified fluid to the first available tank.
//Return the amount of fluid that couldn't be added.
//The passed fluid must be a KubeJS FluidStackJS, create one with Fluid.of("namespace:fluidID", amount)
//If simulate is `false` the fluid will really be inserted, otherwise it wont.
var remaining = machine.addFluid(fluid, simulate);

//Add the specified fluid to the specified tank.
//Return the amount of fluid that couldn't be added.
//The passed fluid must be a KubeJS FluidStackJS, create one with Fluid.of("namespace:fluidID", amount)
//If simulate is `false` the fluid will really be inserted, otherwise it wont.
var remaining = machine.addFluidToTank("tankID", fluid, simulate);

//Remove the specified fluid from the first available tank.
//Return the fluid that was successfully removed.
//Both passed and returned fluids must be a KubeJS FluidStackJS, see code: https://github.com/KubeJS-Mods/KubeJS/blob/1.16/main/common/src/main/java/dev/latvian/kubejs/fluid/FluidStackJS.java
//If simulate is `false` the fluid will really be removed, otherwise it wont.
var removedFluid = machine.removeFluid(fluid, simulate);

//Remove the specified amount of fluid from the specified tank.
//Return the fluid that was successfully removed.
//The returned fluid is a KubeJS FluidStackJS, see code: https://github.com/KubeJS-Mods/KubeJS/blob/1.16/main/common/src/main/java/dev/latvian/kubejs/fluid/FluidStackJS.java
//The specified amount MUST be a positive integer value.
//If simulate is `false` the fluid will really be removed, otherwise it wont.
var remaining = machine.removeFluidFromTank("tankID", amount, simulate);
```

</details>

<details>

<summary>Items</summary>

```javascript
Machine machine = ctx.machine;

//Return the item stored in the specified slot.
//The returned item is a KubeJS ItemStackJS, see docs : https://kubejs.com/wiki/kubejs/ItemStackJS/
var item = machine.getItemStored("slotID");

//Return the capacity of the specified slot.
var capacity = machine.getItemCapacity("slotID");

//Set the specified item in the specified slot.
//The passed item must be a KubeJS ItemStackJS, create one using Item.of("namespace:itemID", amount)
machine.setItemStored("slotID", item);

//Add the specified item to the specified slot.
//Return the item that couldn't be added, or an empty ItemStack if all items were successfully added.
//The passed item must be a KubeJS ItemStackJS, create one using Item.of("namespace:itemID", amount)
//If simulate is `false` the item will really be inserted, otherwise it wont.
var remaining = machine.addItemToSlot("slotID", itemToAdd, simulate);

//Remove the specified amount of item from the specified slot.
//Return the item that were successfully removed, or an empty ItemStack if the slot was empty.
//The returned item is a KubeJS ItemStackJS, see docs : https://kubejs.com/wiki/kubejs/ItemStackJS/
//The specified amount MUST be a positive integer value.
//If simulate is `false` the item will really be extracted, otherwise it wont.
var extracted = machine.removeItemFromSlot("slotID", amountToRemove, simulate);
```

</details>

<details>

<summary>Id</summary>

Get the id of the machine, the id is a String of the format : `namespace:path`.

```javascript
var machine = ctx.getMachine();

var id = machine.id;
```

#### Reminder : A machine stored in `data/namespace/machines/machine.json` will have the id : `namespace:machine`

</details>
