> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borntocraftstudio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Machine Definition

> The single entry that defines a machine type — slots, recipes, energy, visuals, tiers and upgrades.

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](../../Home.mdx#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 `MachineUpgradeType`s 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.                                                             |
| `hopperInterval` / `hopperTransferAmount`                      | `100` / `1`         | Hopper automation (`0` interval = disabled).                                               |

## 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). |