This howto will describe how to use the BuildCraft API to create a mod using BuildCraft engine and power pipes as a power source. This explanations are valid starting BuildCraft 2.2.2 (not yet released at the time this article is written).

Let’s concentrate on a block that needs to be powered by BuildCraft machines. First, you need to implement the interface “IPowerReceptor”. In addition to that, you need to maintain a reference of an instance of “PowerProvider” in your tile entity.

“PowerProvider” will contain all information regarding the current power that you’re using. Because of flexibility issues, the actual PowerProvider may vary depending on the power framework that you’re using. BuildCraft offers two power frameworks, the simple redstone framework and the pneumatic framework (engines). Other mods may offer alternate frameworks. Let’s call this reference “powerProvider”.

This reference has to be instantiated in two cases: at construction time, and when loaded from NBTData. To create the powerProvide at construction time, you need to call an instance from the current framework:

if (PowerFramework.currentFramework) != null) {
powerProvider = PowerFramework.currentFramework.createPowerProvider();
}

Loading and saving the power provider on the disk is not mandatory, except if you want to keep track of remaining energy that can be stored in the provider. In this case, you need to use the loadPowerProvider and savePowerProvider function of the currentFramework variable:

PowerFramework.currentFramework.loadPowerProvider(this, nbttagcompound);
PowerFramework.currentFramework.savePowerProvider(this, nbttagcompound);

After creation or load, it is possible to configure various values of the expected behavior of the block with regards to the power:

powerProvider.configure (latency, minEnergyReceived, maxEnergyReceived, minActivationEnergy, maxEnergyStored)

latency – time between two doWork () calls, used only by the redstone power framework
minEnergyReceived – minimum amount of energy received per transfer
maxEnergyReceived – maximum amount of energy received per transfer
minActivationEnergy – minimum amount of energy received before calling doWork ()
maxEnergyStored – maximum amount of energy stored in the device

In addition to these basic attributes, you can configure power perdition:

powerProvider.configurePowerPerdition (powerLoss, powerLossRegularity)

powerLoss – amount of power lost each time there is a loss of power
powerLossRegularity – number of cycles to wait between two power loss

Let’s now look at the methods to be implemented by IPowerReceptor:

setPowerProvider – called at tile load, forces the internal reference to a certain object. The implementer has to store this value.
getPowerProvider – return the internal power provider reference
doWork – called when the power provider triggers a work, can be used in place of updateEntity
powerRequest – return the amount of power needed by this tile, used to route power in power networks. A good default is powerProvider.maxEnergyReceived

Once all of this is setup, the tile can make use of the power received using e.g. powerProvider.useEnergy method.