NTM JSON Recipe Customization: File Paths and Formats

NTM exposes a powerful JSON-based recipe and configuration system that lets server operators and modpack authors override machine recipes, configure nuclear fallout block substitutions, and customise loot pools — all without writing a single line of Java or loading a coremod. The system is built on top of an abstract SerializableRecipe base class, so any machine that extends it can have its recipes loaded, replaced, or cleared entirely from a JSON file. The JSON recipe files live in the config/hbmRecipes/ subfolder of your Minecraft instance and are generated automatically on first launch as editable templates. Custom multiblock machine definitions use a separate file in config/hbmConfig/. Recipes can be reloaded at runtime using /ntmreload, making iteration fast and requiring no server restart for most changes.

If you are running a multiplayer server and want clients to see custom recipes in machine GUIs, enable 0.05_enableServerRecipeSync in HBM_NTM.cfg. See the General Config page for details.

File Locations

NTM uses two separate config directories for JSON data:

<instance>/
└── config/
    ├── hbmRecipes/                      ← Machine processing recipe overrides
    │   ├── hbmCustomMachines.json       ← Processing recipes for custom multiblock machines
    │   ├── hbmPress.json
    │   ├── hbmBlastFurnaceLegacy.json
    │   ├── hbmShredder.json
    │   ├── ... (one file per machine)
    │   └── _hbmPress.json               ← Auto-generated reference templates (do not edit)
    └── hbmConfig/                       ← Machine structure definitions and server runtime config
        ├── hbmCustomMachines.json       ← Custom multiblock machine layout & crafting recipe definitions
        └── hbmServer.json               ← Server runtime variables (edited via /ntmserver)

Files prefixed with _ inside hbmRecipes/ are reference templates written by the mod on first launch (when the non-prefixed file does not exist). They are never read at runtime — they exist solely so you can see the default values. To activate overrides, rename or copy the template, removing the _ prefix.

The hbmCustomMachines.json name is used in both directories for different purposes: config/hbmConfig/hbmCustomMachines.json defines the multiblock structure and crafting recipe for each custom machine, while config/hbmRecipes/hbmCustomMachines.json defines the processing recipes those machines run. Edit both files to fully configure a custom machine.

Machine Recipes — `SerializableRecipe` System

Machine recipe handling in NTM is centralised through SerializableRecipe, an abstract class that every recipe handler extends. On startup (and on /ntmreload), NTM registers and initialises all handlers in order:

PressRecipes, BlastFurnaceRecipes, ShredderRecipes, SolderingRecipes,
CombinationRecipes, CentrifugeRecipes, CrystallizerRecipes, RefineryRecipes,
VacuumRefineryRecipes, FractionRecipes, CrackingRecipes, ReformingRecipes,
HydrotreatingRecipes, LiquefactionRecipes, SolidificationRecipes,
CokerRecipes, PyroOvenRecipes, BreederRecipes, CyclotronRecipes,
FuelPoolRecipes, MixerRecipes, OutgasserRecipes, FluidBreederRecipes,
CompressorRecipes, ElectrolyserFluidRecipes, ElectrolyserMetalRecipes,
ArcWelderRecipes, RotaryFurnaceRecipes, ExposureChamberRecipes,
ParticleAcceleratorRecipes, AmmoPressRecipes, AnvilRecipes,
PedestalRecipes, AnnihilatorRecipes, CrucibleRecipes,
AssemblyMachineRecipes, ChemicalPlantRecipes, PUREXRecipes,
FusionRecipes, PrecAssRecipes, PlasmaForgeRecipes,
BlastFurnaceRecipesNT, MatDistribution, CustomMachineRecipes, ArcFurnaceRecipes

Each handler reads a dedicated JSON file from config/hbmRecipes/ (the file name is returned by the handler’s getFileName() method). If no override file exists the handler registers hardcoded defaults and writes a _-prefixed template file. The full handler-to-filename mapping is listed at the bottom of this page.

Machine Processing Recipe Structure

Each recipe file in config/hbmRecipes/ contains a top-level recipes array. Each element is a recipe object. Below is the structure used by CustomMachineRecipes (and similarly by all other machine handlers):

{
  "recipes": [
    {
      "recipeKey": "paperPress",
      "recipes": [
        {
          "inputFluids":  [ ["water", 250] ],
          "inputItems":   [ ["item", "hbm:item.powder_sawdust"] ],
          "outputFluids": [],
          "outputItems":  [ ["minecraft:paper", 3, 1.0] ],
          "duration": 60,
          "consumptionPerTick": 10,
          "pollutionType": "SOOT",
          "pollutionAmount": 0.03,
          "radiationAmount": 0,
          "flux": 0,
          "heat": 0
        }
      ]
    }
  ]
}

Recipe field reference

Field	Type	Description
`recipeKey`	String	Identifies which machine this recipe set belongs to. Must match the `recipeKey` declared in the machine’s definition in `hbmConfig/hbmCustomMachines.json`.
`inputFluids`	Array	List of fluid input stacks. Each entry is `[fluidName, amount_mB]` or `[fluidName, amount_mB, pressure]`.
`inputItems`	Array	List of item inputs in AStack format (see below).
`outputFluids`	Array	List of fluid outputs. Same format as `inputFluids`.
`outputItems`	Array	List of item outputs in ItemStack+chance format: `[registryName, (count), (meta), (nbtString), chance]`. `chance` is `1.0` for guaranteed output.
`duration`	Integer	Processing time in ticks.
`consumptionPerTick`	Integer	HE consumed per tick during processing.
`pollutionType`	String	Type of pollution produced (e.g. `"SOOT"`, `"GAS"`). Optional.
`pollutionAmount`	Float	Amount of pollution generated per process cycle. Optional.
`radiationAmount`	Float	Radiation generated per cycle (RADs). Optional.
`flux`	Integer	Flux value for flux-mode machines. Optional.
`heat`	Integer	Heat produced per cycle for heat-mechanic machines. Optional.

Item Stack Formats

NTM uses two different item stack formats in JSON recipes depending on context.

AStack Format (inputs)

Input items use the AStack format, which requires a type identifier as the first element:

Item stack
OreDict stack
NBT item

["item", "minecraft:iron_ingot"]

Quantity 1, metadata 0.

["item", "hbm:item.ingot_steel", 3, 0]

3× steel ingots, metadata 0. Size and meta are omitted when they are 1 and 0 respectively.

["dict", "ingotSteel"]

Accepts any item registered under the ingotSteel ore dictionary key. Quantity 1 by default.

["dict", "ingotSteel", 2]

2× of any ingotSteel ore dictionary match.

["nbt", "hbm:item.circuit", 1, 2, "{type:2}"]

1× circuit with metadata 2 and NBT {type:2}. NBT format matches the /give command syntax.

ItemStack+Chance Format (outputs)

Output items use a flat array format — no type identifier prefix:

["minecraft:paper", 3, 1.0]

3× paper with 100% drop chance.

["hbm:item.ingot_steel", 1, 0, 0.5]

1× steel ingot (meta 0) with 50% drop chance. The elements are: [registryName, (count), (meta), (nbtString), chance]. Trailing elements may be omitted when they are defaults (count=1, meta=0, no NBT). The chance value (0.0–1.0) is always the last element.

Custom Machine Definitions — `config/hbmConfig/hbmCustomMachines.json`

The hbmConfig/hbmCustomMachines.json file defines the physical structure, crafting recipe, and I/O parameters of custom multiblock machines. This is separate from the processing recipes (which go in hbmRecipes/hbmCustomMachines.json). The file is read by CustomMachineConfigJSON at startup and is not affected by /ntmreload — a full restart is required to pick up changes to machine definitions.

Machine Definition Structure

{
  "machines": [
    {
      "recipeKey": "paperPress",
      "unlocalizedName": "paperPress",
      "localizedName": "Paper Press",
      "localization": {
        "de_DE": "Papierpresse"
      },
      "fluidInCount": 1,
      "fluidInCap": 1000,
      "itemInCount": 1,
      "fluidOutCount": 0,
      "fluidOutCap": 0,
      "itemOutCount": 1,
      "generatorMode": false,
      "maxPollutionCap": 100,
      "fluxMode": false,
      "recipeSpeedMult": 1.0,
      "recipeConsumptionMult": 1.0,
      "maxPower": 10000,
      "maxHeat": 0,
      "recipeShape": ["IPI", "PCP", "IPI"],
      "recipeParts": [
        "I", ["dict", "ingotSteel"],
        "P", ["dict", "plateSteel"],
        "C", ["item", "hbm:item.circuit", 1, 0]
      ],
      "components": [
        { "block": "hbm:tile.cm_sheet", "x": -1, "y": 0, "z": 0, "metas": [0] },
        { "block": "hbm:tile.cm_port",  "x":  0, "y": -1, "z": 0, "metas": [0] }
      ]
    }
  ]
}

Machine definition field reference

Field	Type	Description
`recipeKey`	String	Identifies which recipe set this machine processes. Must match the key used in `config/hbmRecipes/hbmCustomMachines.json`.
`unlocalizedName`	String	Internal registry name for the machine. Used in NBT and machine lookup.
`localizedName`	String	Default display name shown in-game.
`localization`	Object	Optional locale overrides. Keys are locale codes (`en_US`, `de_DE`, etc.), values are translated names.
`fluidInCount`	Integer	Number of fluid input tanks.
`fluidInCap`	Integer	Capacity of each fluid input tank (mB).
`itemInCount`	Integer	Number of item input slots.
`fluidOutCount`	Integer	Number of fluid output tanks.
`fluidOutCap`	Integer	Capacity of each fluid output tank (mB).
`itemOutCount`	Integer	Number of item output slots.
`generatorMode`	Boolean	If `true`, input items are consumed when the process begins rather than when it completes.
`maxPollutionCap`	Integer	Maximum pollution this machine can accumulate before it stops processing. Optional; defaults to `0`.
`fluxMode`	Boolean	Enables flux-based energy consumption mode. Optional; defaults to `false`.
`recipeSpeedMult`	Double	Multiplier on recipe duration. `0.5` = twice as fast; `2.0` = twice as slow.
`recipeConsumptionMult`	Double	Multiplier on energy consumption per recipe.
`maxPower`	Long	Internal energy buffer size (HE).
`maxHeat`	Integer	Maximum heat buffer. Optional; defaults to `0` (no heat mechanic).
`recipeShape`	String array	Crafting grid rows for the controller block’s crafting recipe (standard Forge shaped recipe format). Optional.
`recipeParts`	Array	Alternating character key / AStack pairs mapping `recipeShape` letters to items. Optional.
`components`	Array	List of multiblock component block definitions (see below).

Component definition field reference

Each object in the components array describes one block in the multiblock structure:

Field	Type	Description
`block`	String	The fully-qualified block registry name (e.g. `hbm:tile.cm_sheet`).
`x`	Integer	X offset from the controller block.
`y`	Integer	Y offset from the controller block.
`z`	Integer	Z offset from the controller block.
`metas`	Integer array	List of accepted block metadata values. The multiblock is valid if the placed block has any of these metas.

Standard custom machine blocks provided by NTM for building multiblock structures:

Registry Name	Description
`hbm:tile.cm_block`	Solid structural block
`hbm:tile.cm_sheet`	Sheet/panel structural block
`hbm:tile.cm_port`	Item/fluid port block

Fallout Config — `hbmFallout.json`

The hbmFallout.json file in config/hbmRecipes/ controls how nuclear explosions transform blocks in the world. Each entry defines a matching rule and one or more replacement outcomes. The system supports matching by block identity, metadata, material type, opacity, and distance from the explosion centre.

Entry Structure

{
  "entries": [
    {
      "matchesBlock": "minecraft:log",
      "primarySubstitution": [
        ["hbm:waste_log", 0, 1]
      ],
      "maximumDistancePercent": 65.0
    },
    {
      "matchesMaterial": "sand",
      "primarySubstitution": [
        ["hbm:waste_trinitite", 0, 1]
      ],
      "chance": 0.05
    }
  ]
}

FalloutEntry field reference

Field	Type	Description
`matchesBlock`	String	Registry name of the block to match (e.g. `minecraft:log`). Optional.
`matchesMeta`	Integer	Exact metadata value the block must have to match. `-1` or absent = any meta.
`mustBeOpaque`	Boolean	If `true`, only opaque blocks are matched.
`matchesMaterial`	String	Material name to match instead of a specific block. Supported values: `grass`, `ground`, `wood`, `rock`, `iron`, `anvil`, `water`, `lava`, `leaves`, `plants`, `vine`, `sponge`, `cloth`, `fire`, `sand`, `circuits`, `carpet`, `redstoneLight`, `tnt`, `coral`, `ice`, `packedIce`, `snow`, `craftedSnow`, `cactus`, `clay`, `gourd`, `dragonEgg`, `portal`, `cake`, `web`.
`restrictDepth`	Boolean	If `true`, the depth counter is decremented when this block is converted (affects layered blast behaviour).
`primarySubstitution`	Array	List of `[blockName, meta, weight]` triplets. One is chosen randomly by weight.
`secondarySubstitutions`	Array	Same format as `primarySubstitution`. Used when the random roll fails the `chance` check.
`chance`	Double	Probability (0.0–1.0) that the primary substitution is used. If the roll fails, secondary substitutions are used instead. Default `1.0`.
`minimumDistancePercent`	Double	Minimum distance from explosion centre (as % of max radius) for this rule to apply. Default `0.0`.
`maximumDistancePercent`	Double	Maximum distance from explosion centre (as % of max radius) for this rule to apply. Default `100.0`.
`falloffStartFactor`	Double	Fraction of `maximumDistancePercent` at which random falloff begins. Default `0.9`.

Item Pool Config — `hbmItemPools.json`

NTM uses named item pools to populate dungeon loot chests and structure containers. The hbmItemPools.json file in config/hbmRecipes/ lets you override any pool to change what items appear and how likely they are.

File Format

{
  "description": "Format: [[itemStack], min, max, weight], ...",
  "pools": {
    "poolName": [
      [ ["item", "hbm:item.ingot_steel"], 1, 5, 10 ],
      [ ["item", "minecraft:gold_ingot"], 1, 3,  5 ],
      [ ["item", "hbm:item.circuit", 1, 2], 1, 1, 2 ]
    ]
  }
}

Each entry in a pool array is:

[ [itemStack], minCount, maxCount, weight ]

Item pool entry fields

Position	Type	Description
`[0]`	Array	Item stack in AStack format (see above). The stack’s own count is ignored — use `minCount`/`maxCount` instead.
`[1]`	Integer	Minimum number of items to place.
`[2]`	Integer	Maximum number of items to place.
`[3]`	Integer	Relative weight. An item with weight `10` is 10× as likely to be chosen as an item with weight `1`.

If hbmItemPools.json exists, it completely replaces all pools defined within it. Pools not present in the file remain unchanged (default values apply). This allows surgical overrides of individual pools without needing to copy the entire default pool list.

Reloading Recipes In-Game

Run /ntmreload as a server operator to reload all JSON recipe files, fluid definitions, item pools, damage resistance tables, and logic block scripts without restarting the server:

/ntmreload

This command re-runs the full SerializableRecipe.initialize() pipeline, which clears all recipe maps, reads every JSON file from config/hbmRecipes/, re-registers defaults for any file that doesn’t exist, and writes fresh template files.

/ntmreload clears and rebuilds all recipe maps. Any players currently using a machine GUI will have their pending recipes invalidated. Advise players to step away from machines before reloading on a live server.

Changes to machine definitions (config/hbmConfig/hbmCustomMachines.json) are not picked up by /ntmreload. A full server restart is required to apply changes to multiblock layouts, I/O counts, or the machine crafting recipe.

Server-Side Recipe Sync

When 0.05_enableServerRecipeSync = true in HBM_NTM.cfg, the server serialises all modified SerializableRecipe handlers into byte streams and sends them to clients as they connect. This ensures clients display the server’s custom recipes in machine GUIs rather than the defaults baked into their local JAR. Recipe sync is disabled by default because it adds connection overhead and is unnecessary in single-player or on servers where all players have identical modpacks.

Handler-to-File Mapping

All SerializableRecipe handlers and the filenames they read from config/hbmRecipes/:

Handler Class	File in `config/hbmRecipes/`
`CustomMachineRecipes`	`hbmCustomMachines.json`
`PressRecipes`	(see template for filename)
`BlastFurnaceRecipes`	`hbmBlastFurnaceLegacy.json`
`ShredderRecipes`	(see template)
`CentrifugeRecipes`	(see template)
`CrystallizerRecipes`	(see template)
`RefineryRecipes`	(see template)
`MixerRecipes`	(see template)
`CompressorRecipes`	(see template)
`ArcWelderRecipes`	(see template)
`AssemblyMachineRecipes`	`hbmAssemblyMachine.json`
`ChemicalPlantRecipes`	`hbmChemicalPlant.json`
`FusionRecipes`	`hbmFusion.json`
`PUREXRecipes`	`hbmPUREX.json`
`FluidBreederRecipes`	`hbmIrradiationFluids.json`
`AnnihilatorRecipes`	`hbmAnnihilator.json`
(all others)	See `SerializableRecipe.registerAllHandlers()` and the `_`-prefixed templates generated on first launch.

Each file follows the same { "recipes": [ ... ] } wrapper structure; the contents of each recipe object differ per machine type. Refer to the _-prefixed template files for the exact field names used by each handler.

Introduction

Core Concepts

Configuration

NTM JSON Recipe Customization: File Paths and Formats

File Locations

Machine Recipes — `SerializableRecipe` System

Machine Processing Recipe Structure

Item Stack Formats

AStack Format (inputs)

ItemStack+Chance Format (outputs)

Custom Machine Definitions — `config/hbmConfig/hbmCustomMachines.json`

Machine Definition Structure

Fallout Config — `hbmFallout.json`

Entry Structure

Item Pool Config — `hbmItemPools.json`

File Format

Reloading Recipes In-Game

Server-Side Recipe Sync

Handler-to-File Mapping

Build docs developers (and LLMs) love

Introduction

Core Concepts

Configuration

Documentation Index

​File Locations

​Machine Recipes — SerializableRecipe System

​Machine Processing Recipe Structure

​Item Stack Formats

​AStack Format (inputs)

​ItemStack+Chance Format (outputs)

​Custom Machine Definitions — config/hbmConfig/hbmCustomMachines.json

​Machine Definition Structure

​Fallout Config — hbmFallout.json

​Entry Structure

​Item Pool Config — hbmItemPools.json

​File Format

​Reloading Recipes In-Game

​Server-Side Recipe Sync

​Handler-to-File Mapping

Build docs developers (and LLMs) love

File Locations

Machine Recipes — `SerializableRecipe` System

Machine Processing Recipe Structure

Item Stack Formats

AStack Format (inputs)

ItemStack+Chance Format (outputs)

Custom Machine Definitions — `config/hbmConfig/hbmCustomMachines.json`

Machine Definition Structure

Fallout Config — `hbmFallout.json`

Entry Structure

Item Pool Config — `hbmItemPools.json`

File Format

Reloading Recipes In-Game

Server-Side Recipe Sync

Handler-to-File Mapping