ItemOilPumpAsset — Oil Pump Items

Advanced20-25 minutesWindowsVisual Studio

Generating a sustainable fuel supply in Unturned through oil pump barricades requires understanding how ItemOilPumpAsset defines fuel extraction capacity, integrates with the power grid, and interfaces with fuel cans for player extraction. ItemOilPumpAsset defines oil pump barricades — placeable structures that extract fuel from the ground. It extends ItemBarricadeAsset rather than ItemAsset, because it is placed in the world as a barricade rather than held as an inventory item.

Source code location: Unturned/Bundles/ItemOilAsset.cs (named in source as ItemOilPumpAsset)

Inheritance Chain

ItemAsset
  → ItemBarricadeAsset
    → ItemOilPumpAsset

The filename is ItemOilAsset.cs but the class name is ItemOilPumpAsset. This naming mismatch is retained for backwards compatibility with existing serialization and save data.

Class Definition

public class ItemOilPumpAsset : ItemBarricadeAsset
{
    public ushort fuelCapacity { get; protected set; }
}

Core Fields

Field	Type	.dat Key	Description
fuelCapacity	ushort	Fuel_Capacity	Maximum fuel stored in the pump (0-65,535)

The single field represents the pump's internal fuel storage capacity. This is the maximum amount of fuel the pump can accumulate before it stops producing. Players extract stored fuel using a fuel can (ItemFuelAsset).

PopulateAsset

public override void PopulateAsset(in PopulateAssetParameters p)
{
    base.PopulateAsset(in p);

    fuelCapacity = p.data.ParseUInt16("Fuel_Capacity");
}

The Fuel_Capacity key is a simple ushort parse. No default value — if the key is absent, fuelCapacity defaults to 0, making the pump unable to store any fuel.

Oil Pump Runtime Behavior

The oil pump's runtime behavior is implemented in the InteractableOilPump class (not shown in the asset). The pump operates as follows:

Fuel Extraction

1. Ground probe: The pump performs a raycast check beneath its position to detect fuel-rich ground.
2. Accumulation: Fuel accumulates in the pump's internal storage over time, up to fuelCapacity.
3. Rate: The accumulation rate is configurable in game mode config (default ~1 unit per tick).
4. Cap: When storage reaches fuelCapacity, accumulation stops.

Player Interaction

1. Extract: A player with an empty fuel can (ItemFuelAsset) faces the pump.
2. Transfer: Fuel flows from the pump's storage into the can.
3. State update: The pump's internal fuel state is reduced; the can's fuel state increases.
4. Completion: Transfer completes when the pump is empty or the can is full.

Power Requirements

The oil pump connects to the power system:

• If power is required (game mode config), the pump must be connected to a generator or electrical grid.
• Without power, the pump does not produce fuel.
• The power connection uses PowerTool and its range validation.

Comparison to ItemFuelAsset and ItemTankAsset

Feature	ItemFuelAsset	ItemTankAsset	ItemOilPumpAsset
Base class	ItemAsset	ItemBarricadeAsset	ItemBarricadeAsset
Is placeable	No	Yes	Yes
Produces fuel	No (stores)	No (stores)	Yes (generates)
Capacity type	Fuel	Resource	Fuel_Capacity
Power required	No	No	Yes (optional)
Interaction	Fill/drain vehicles	Fill/drain containers	Extract to fuel can

The oil pump is the only item in this group that generates fuel. Fuel cans and tanks only store and transfer existing fuel.

Cargo Data Export

CargoDeclaration data = builder.GetOrAddDeclaration("OilPump");
data.Append("GUID", GUID);
data.Append("Fuel_Capacity", fuelCapacity);

The base class appends barricade fields from ItemBarricadeAsset.BuildCargoData.

Power System Integration

The oil pump connects to the power system managed by PowerTool:

1. Generator connection: The pump must be within PowerTool.MAX_POWER_RANGE of a powered generator.
2. Power consumption: The pump draws power based on game mode config while operating.
3. Power loss: If power is lost (generator out of fuel, destroyed, or disconnected), the pump stops producing fuel.
4. Accumulated fuel preserved: Fuel already accumulated is not lost during power outages.

Capacity Considerations

The fuelCapacity is a ushort (max 65,535), the same type used by ItemFuelAsset._fuel and ItemGeneratorAsset.capacity. This means:

• A pump with Fuel_Capacity=1000 can fuel approximately 25 standard vehicles (40 fuel each).
• The pump and connected generators operate in the same value space — a generator with capacity=500 could run on a single pump's output for its entire duration.
• Large capacity values may create long extraction times. The transfer rate is fixed (configurable in game mode); a 65,535 unit tank could take minutes to drain.

Common Issues

1. Oil pump capacity vs generator capacity — The pump stores fuel as ushort (max 65,535); generators also use ushort. These are independent — the pump doesn't auto-feed generators without player interaction.
2. Power dependency — If the game mode requires power for oil pumps, a pump placed outside generator range will produce no fuel. The pump's location must be planned around the electrical grid.
3. Zero capacity pump — Omitting Fuel_Capacity or setting it to 0 creates a pump that can accumulate 0 fuel. It functions as a cosmetic barricade only.
4. Filename vs class name — The file is ItemOilAsset.cs but the class is ItemOilPumpAsset. This naming mismatch can cause confusion when searching the codebase. Both names appear in different contexts.
5. No passive consumption — Unlike generators which consume fuel while operating, oil pumps produce fuel without consuming any resource (beyond optional power). The pump is a net-positive fuel generator once placed.

Worked Code Example: Oil Pump Plugin

using SDG.Unturned;
using UnityEngine;

public class FuelDistributor : MonoBehaviour
{
    /// <summary>
    /// Automatically distributes fuel from oil pumps to generators
    /// within a configurable radius, keeping generators filled.
    /// </summary>
    public static void DistributeFuelInZone(Vector3 center, float radius)
    {
        System.Collections.Generic.List<InteractableOilPump> pumps =
            new System.Collections.Generic.List<InteractableOilPump>();
        System.Collections.Generic.List<InteractableGenerator> generators =
            new System.Collections.Generic.List<InteractableGenerator>();

        foreach (BarricadeRegion region in BarricadeManager.regions.Values)
        {
            foreach (BarricadeDrop drop in region.drops)
            {
                if (Vector3.Distance(drop.model.position, center) > radius)
                    continue;

                InteractableOilPump pump = drop.model.GetComponent<InteractableOilPump>();
                if (pump != null && pump.fuel > 0)
                    pumps.Add(pump);

                InteractableGenerator gen = drop.model.GetComponent<InteractableGenerator>();
                if (gen != null)
                    generators.Add(gen);
            }
        }

        foreach (InteractableGenerator gen in generators)
        {
            ushort needed = (ushort)(gen.capacity - gen.fuel);
            if (needed == 0) continue;

            foreach (InteractableOilPump pump in pumps)
            {
                if (needed == 0) break;
                if (pump.fuel == 0) continue;

                ushort transfer = System.Math.Min(needed, pump.fuel);
                pump.askBurn(transfer);
                gen.askFill(transfer);
                needed -= transfer;
            }
        }
    }
}

Mermaid Diagram: Oil Pump Production Cycle

Comparison: Oil Pump vs. Other Fuel Systems

Feature	Oil Pump	Fuel Can (ItemFuelAsset)	Generator	Fuel Tank (ItemTankAsset)
Generates fuel	Yes (ground extraction)	No	No (consumes)	No
Stores fuel	Yes (up to fuelCapacity)	Yes (up to fuel)	Yes (capacity)	Yes (Resource)
Power required	Optional (game mode)	No	No (it produces power)	No
Player extraction	Via fuel can	N/A	Via siphoning	Via fuel can
Base class	ItemBarricadeAsset	ItemAsset	ItemBarricadeAsset	ItemBarricadeAsset
Net positive fuel	Yes	N/A (neutral)	No (net negative)	No (neutral)

Failure Modes and Common Mistakes

6. Ground probe fails on custom terrains — On custom maps with non-standard terrain layers, the pump's ground probe raycast may fail, producing zero fuel despite correct placement.

7. Multiple pumps on same ground node — Fuel extraction is per-pump, not per-ground-node. Ten pumps on one patch = 10x production, an economic exploit on unlimited resources.

8. Power loss zeros accumulated fuel — Some game mode configs cause the pump to clear accumulated fuel on power loss, which surprises players who assumed fuel preservation.

How This Field Behaves Differently from the SDG Docs

• SDG docs describe oil pumps as "infinite fuel sources." In the SDK, the pump caps at fuelCapacity and stops producing. Untended pumps waste production cycles.
• SDG docs claim pumps require "specific terrain." The ground probe logic is game-mode-configurable; custom game modes can enable extraction on any surface.
• SDG docs reference an "Oil" item type. The SDK uses ItemBarricadeAsset hierarchy with barricade type assignment, not a dedicated OIL enum.

Performance Considerations

Oil pumps have minimal runtime cost. Each pump checks power (O(1) boolean), does one raycast for ground probe (~0.01ms), and one arithmetic operation per accumulation tick. With 500 pumps, per-tick cost is ~5ms. Acceptable for all but the largest installations.

Deeper FAQ

Q: Can I change the fuel production rate per pump?

Not through vanilla config. Production rate is game-mode-wide. A Harmony patch on the accumulation tick in InteractableOilPump is needed for per-pump customization.

Q: Do oil pumps work in underground bases?

Yes, but only if the ground probe reaches a terrain collider. Underground bases may have ceiling colliders above terrain that the probe hits instead, returning zero fuel.

Q: Can I extract fuel while the pump is unpowered?

Yes. Fuel extraction (transfer to can) does not require power. Only accumulation does. Pumped fuel is preserved through power outages.

Cross-References

• ItemFuelAsset — Fuel Can Items — Fuel cans for transporting pump output.
• Interactable Generator — Power Supply — Generators that consume pumped fuel.
• ItemGeneratorAsset — Generator Asset Definition — Generator fuel capacity and consumption determining pump sizing.
• ItemTankAsset — Fuel Tank Storage — Large-scale fuel storage using tank barricades.

Document history