The Upgrades API lets you create upgrade items that modify machine behavior and attach compatible upgrade lists to specific block entities.
UpgradeBase
UpgradeBase is the base class for all upgrade items. It extends BaseItem.
public class UpgradeBase extends BaseItem
Constructor
public UpgradeBase(Item.Properties properties, String description)
Standard NeoForge item properties.
English description shown in the item tooltip when the player holds Shift.
Methods
// Attempt to apply this upgrade to a block; throws if the block is not Upgradeable
void functionalUpgrade(BaseEntityBlock<?> block, BlockState state)
// Mark the upgrade as applied or unapplied
boolean setApplied(boolean hasBeenApplied)
// Check whether this upgrade instance has been applied
boolean hasBeenApplied()
// Return the English description string
String getEnglishDescription()
gui.gm.press_shift localization key.
Upgradeable interface
Upgradeable marks a block entity as capable of holding upgrades.
public interface Upgradeable {
ItemStackHandler getUpgradeInventory();
}
ItemStackHandler that represents the upgrade slots of your machine. The handler’s slot count determines how many upgrades can be installed simultaneously.
UpgradeMap
UpgradeMap is a record that associates a block entity type with an ordered list of compatible upgrade/max-stack pairs.
public record UpgradeMap<T extends BlockEntity>(
DeferredBlockEntityType<T> entity,
ImmutableList<Pair<ItemDefinition<UpgradeBase>, Integer>> upgrades
)
entity
DeferredBlockEntityType<T>
The block entity type this upgrade map belongs to.
upgrades
ImmutableList<Pair<ItemDefinition<UpgradeBase>, Integer>>
Ordered list of (upgrade definition, max slots) pairs that the block entity accepts.
DeferredUpgradeMap
DeferredUpgradeMap is a record that wraps an UpgradeMap inside a DeferredHolder for registration.
public record DeferredUpgradeMap<T extends BasePoweredBlockEntity>(
Class<? extends BasePoweredBlockEntity> entity,
DeferredHolder<UpgradeMap<?>, UpgradeMap<T>> holder
) implements Supplier<UpgradeMap<T>>
get() to resolve the held UpgradeMap<T> after registration has completed.
CoreUpgrades
CoreUpgrades registers all built-in upgrade items and provides access to upgrade functions.
Built-in upgrades
| Constant | Description |
|---|
EMPTY | Placeholder base upgrade |
SPEED | Increases machine operation speed |
CAPACITY | Expands operational size |
EFFICIENCY | Reduces power consumption per operation |
OVERCLOCK | Greatly increases speed at efficiency cost |
THERMAL_BUFFER | Allows operation under extreme conditions |
AUTO_EJECTOR | Pushes output to connected inventories |
INPUT_EXPANDER | Accepts input from multiple sides |
MULTI_PROCESSOR_UNIT | Enables multiple simultaneous operations |
SILENCING_COIL | Suppresses machine sounds |
NANITE_INJECTOR | Increases byproduct and rare drop yield |
PRECISION_GEARBOX | Improves accuracy for chance-based outputs |
REDSTONE_INTERFACE | Adds advanced redstone control |
ECO_DRIVE | Near-zero idle power draw |
VOID_MOD | Destroys overflow items |
REPLICATION_NODE | Duplicates output at high power cost |
create() methods
// Register an upgrade with a BiFunction factory (receives Properties and description String)
public static <T extends UpgradeBase, I> ItemDefinition<T> create(
String id,
String desc,
BiFunction<Item.Properties, String, T> factory,
@Nullable UpgradeFunctionBuilder<T, I> caller
)
// Register an upgrade with a standard Function factory
public static <T extends UpgradeBase, I> ItemDefinition<T> create(
String id,
String desc,
Function<Item.Properties, T> factory,
@Nullable UpgradeFunctionBuilder<T, I> caller
)
// Explicit ResourceLocation variant (BiFunction)
public static <T extends UpgradeBase, I> ItemDefinition<T> create(
String name,
String desc,
ResourceLocation id,
BiFunction<Item.Properties, String, T> factory,
@Nullable UpgradeFunctionBuilder<T, I> caller
)
Human-readable upgrade name; used to derive the registry path.
English description passed to the upgrade’s tooltip.
factory
BiFunction or Function
required
Creates the UpgradeBase (or subclass) item instance.
Optional builder that produces an UpgradeFunction. Pass null to register a passive upgrade with no active logic.
getCompatibleUpgrades()
public static ImmutableList<Pair<ItemDefinition<UpgradeBase>, Integer>>
getCompatibleUpgrades(Block block)
UpgradeMap registered for the given block’s entity type and returns its upgrade list. Returns an empty list if no map is registered.
The block associated with the target block entity.
UpgradeFunctionBuilder and UpgradeFunction
@FunctionalInterface
public interface UpgradeFunctionBuilder<T extends UpgradeBase, I> {
UpgradeFunction<T, I> build();
}
public interface UpgradeFunction<T extends UpgradeBase, I> {
// Called once when the upgrade is installed
void create(T base, I valueType);
// Called each time the upgraded behavior executes
void work(I attribute);
}
Code example: implementing Upgradeable in a block entity
import general.mechanics.api.upgrade.Upgradeable;
import net.minecraft.core.BlockPos;
import net.minecraft.world.level.block.entity.BlockEntity;
import net.minecraft.world.level.block.entity.BlockEntityType;
import net.minecraft.world.level.block.state.BlockState;
import net.neoforged.neoforge.items.ItemStackHandler;
public class MyMachineBlockEntity extends BlockEntity implements Upgradeable {
// Two upgrade slots
private final ItemStackHandler upgradeInventory = new ItemStackHandler(2);
public MyMachineBlockEntity(BlockEntityType<?> type, BlockPos pos, BlockState state) {
super(type, pos, state);
}
@Override
public ItemStackHandler getUpgradeInventory() {
return upgradeInventory;
}
public void tick() {
// Check whether a speed upgrade is installed
var compatibleUpgrades = CoreUpgrades.getCompatibleUpgrades(
getBlockState().getBlock()
);
// Apply upgrade logic as needed ...
}
}
