Pumps & Pistons

Maintained source and issue tracking have moved to Offchunk Forgejo.

Pump it. Refine it. Move it.

Pumps & Pistons is a survival-focused Fabric fuel ecosystem. Its standalone core adds finite crude-oil reserves, practical extraction and refining, reusable fuel containers, service-station infrastructure and a complete forecourt building kit. Optional integrations connect that fuel economy to transport mods without making the core depend on a particular vehicle.

The first integration is Pumps & Pistons: Automobility, which adds persistent, server-authoritative vehicle tanks, deliberate refuelling, fuel consumption and a coordinated dashboard for Automobility.

Choose what to install

Install each selected component on the server and every client.

Experience	Required components
Extraction, refining, fuel storage and station building	Pumps & Pistons + Fabric API
Automobility vehicle tanks and refuelling	Matching Pumps & Pistons + Pumps & Pistons: Automobility + Automobility + Fabric API

Momentum is optional. When present, the Automobility integration docks the fuel gauge into Momentum's compact instrument cluster; without it, the gauge uses its own safe layout.

Always use matching Pumps & Pistons core and integration versions. Multiplayer servers verify the pair before a player enters the world and reject a missing or mismatched integration.

Upgrading from the 1.8 pre-release

Version 1.9 establishes the final technical namespaces pumps_and_pistons and pumps_and_pistons_automobility. Treat it as a clean namespace break from the 1.8 pre-release:

1. Back up any world that has been opened with 1.8.
2. Remove every 1.8 JAR before installing 1.9, including the earlier monolithic JAR and either split core or adapter JAR. Never load both generations together.
3. Install the matching 1.9 core and, when required, the matching Automobility integration on the server and every client.

Old 1.8 block and item identifiers, configuration and finite-reservoir data are not migrated. Existing AutoFuel* vehicle NBT remains compatible, so vehicle tank type and amount can carry forward when the correct 1.9 integration is installed. That vehicle compatibility does not restore missing 1.8 blocks, items or oil fields.

What the core adds

• reusable petroleum surveying with no ore placement or terrain-generation changes;
• deterministic, finite and shared underground oil fields;
• a redstone-driven animated pumpjack with a 100 L buffer;
• transportable crude oil in reusable 20 L jerry cans;
• a compact furnace-heated refinery with petrol-focused, balanced and diesel-focused yields;
• useful bitumen residue as a refining by-product;
• persistent 400 L service pumps with AUTO, PETROL and DIESEL designations;
• exact can-to-machine and machine-to-can transfers;
• comparator-readable pump stock and a live analogue gauge;
• canopy panels, connected columns, fascia signs, lights, bollards, kerbs, wheel stops, drains and roadside pylons for complete service stations;
• no chunk forcing, offline extraction, background terrain mutation or factory network.

Pumps & Pistons: Automobility

The optional Automobility integration adds:

• persistent petrol or diesel tanks on Automobility and RIAutomobility vehicles;
• engine-specific fuel requirements and tank capacities;
• server-authoritative consumption based on distance, speed, engine torque, frame weight, passengers, observed acceleration and high-speed load;
• a click-once pump nozzle workflow that targets the exact stopped vehicle;
• hold-to-refuel jerry cans with partial transfer and no lost remainder;
• multiplayer-safe pump and vehicle reservations;
• animated rubber hoses and carried nozzles;
• wrong-fuel protection, safe draining and capacity-changing engine swaps;
• a compact graphical fuel gauge, progress display and restrained low-fuel warning.

The core remains fully usable without Automobility or any other transport mod.

Illustrated field manual

The seven-sheet manual separates the system into two clear parts:

• sheets 00–03 cover the standalone core: the complete loop, surveying and extraction, refining, storage and service-station operation;
• sheets 04–06 cover Pumps & Pistons: Automobility: deliberate refuelling, engine compatibility, consumption and the dashboard.

It is available in English, Czech, German, Spanish, French, Norwegian Bokmål, Polish and Brazilian Portuguese.

Open the illustrated field manual and choose a language.

From field to service pump

1. Craft a reusable Petroleum Survey Kit and use it on the ground. It checks the current underground region and its neighbours without changing a chunk.
2. Place a Compact Oil Pumpjack inside a discovered field region and power it with redstone. It extracts only while the chunk is loaded and its buffer has room.
3. Withdraw crude oil with an empty jerry can.
4. Insert crude into a Compact Fuel Refinery and add any vanilla furnace fuel. One 10 L batch takes 20 seconds.
5. Choose PETROL FOCUS, BALANCED or DIESEL FOCUS between batches. Each recipe produces petrol, diesel and one item of bitumen residue.
6. Withdraw petrol from the yellow left-side port, diesel from the green right-side port and unprocessed crude from the top. The coloured squares on the front are indicators, not fluid ports.
7. Move finished fuel in cans or store it in a designated service pump.

By default, only the Overworld contains oil. Each 16 x 16 chunk region has a 20% chance of one shared 400–900 L field. Multiple pumpjacks in the same region debit the same reserve. Generator settings are snapshotted on first extraction, so later configuration changes cannot silently move or refill established fields.

Stored liquids are not copied into dropped blocks. Drain pumps, pumpjacks and refineries before breaking them. This makes machine relocation explicit and avoids break-and-replace duplication.

Store and serve fuel

A service pump is finite storage, not an infinite source. It holds 400 L of one fuel type and can be designated PETROL, DIESEL or AUTO.

1. Sneak-use a filled petrol or diesel can to set a fixed designation. Sneak-use an empty can to restore AUTO. Setting the designation never transfers fuel.
2. Use compatible filled cans normally to add stock.
3. Use an empty can normally to withdraw up to 20 L.
4. Sneak-use the pump with an empty hand to inspect its designation, fuel type and stock.

AUTO accepts either fuel while empty and follows its current contents while stocked. A comparator outputs zero for an empty pump and one through fifteen as the stored amount rises.

Refuel an Automobility vehicle

With Pumps & Pistons: Automobility installed:

1. Stop a compatible vehicle within six blocks of a stocked service pump.
2. Right-click the pump with an empty hand to take the nozzle.
3. Right-click the exact vehicle once. Refuelling continues without holding the button.
4. Right-click the pump again to stop early and return the nozzle.

For roadside refuelling, hold right-click on the vehicle with a compatible filled can. Releasing immediately stops the transfer: delivered fuel stays in the tank and the unused remainder stays in the can. Wrong fuel is rejected before any transfer.

Consumption and dashboard

One block is treated as one metre. Stock cars typically use about 9–13 L/100 km, with the heaviest loaded combinations approaching roughly 15 L/100 km. Petrol uses a 0.075 ml/block travel baseline and a 0.015 ml/tick running-engine baseline. Diesel defaults to 90% of the petrol distance component and 80% of its running component.

The server applies bounded factors for engine torque, frame weight, passengers, speed and observed acceleration. Coasting and braking still incur distance use; extreme position corrections remain bounded. The calculation uses game ticks and measured distance rather than wall-clock time.

The graphical dashboard shows the required fuel by colour and the remaining level with ten segments. Amber and red indicate low and critical fuel; alternating red segments indicate an incompatible fuel.

Building a station

Forecourt pieces are ordinary, reusable blocks rather than a required multiblock. They support anything from a single rural pump to a large multiplayer service area.

• canopy panels and lit panels form walkable weather cover;
• connected support columns hide internal seams;
• neutral, PETROL and DIESEL fascia pieces form seamless runs;
• precise bollards, wheel stops, low kerbs and flush drains shape safe islands;
• two-block roadside pylons and directional floodlights provide clear wayfinding;
• static decoration states add no background ticks or extra networking.

See the premium station showcase for a complete production yard, forecourt, shop and workshop layout.

Configuration

Server operators can tune oil dimensions and distribution, machine capacities and rates, hose reach, transfer speeds, engine mappings, tank capacities and the complete consumption curve. Existing finite-field generator settings are preserved with the world once extraction begins.

The bundled Legacy Synthetic Fuel Recipes datapack restores the older direct full-can recipes for existing worlds. It is disabled by default so normal survival progression cannot bypass extraction and refining.

Compatibility

• Minecraft Java 26.2
• Fabric Loader 0.19.3+
• Fabric API 0.153.0+26.2+
• Automobility Unofficial Port 0.5.0-unofficial.29 for the Automobility integration
• Momentum optional
• RIAutomobility supported automatically when present

License

Pumps & Pistons code, documentation and original runtime assets are available under the MIT License. Automobility, Momentum, Minecraft and other referenced projects retain their own names, assets and licenses. No endorsement is implied.