ItemFilterAsset — Fuel Filter Items

Advanced15-20 minutesWindowsVisual Studio

Keeping your vehicles and generators running on clean fuel in Unturned depends on understanding how fuel filters consume themselves to clear contamination states from fuel cans, bridging the gap between contaminated fuel sources and clean-fuel engines. ItemFilterAsset defines fuel filters — single-use items that clean contaminated fuel during the fuel pumping process. It extends ItemAsset directly and is one of the smallest non-supply item classes at 21 lines. Runtime behavior is provided by the UseableFilter class.

Source code location: Unturned/Bundles/ItemFilterAsset.cs

Inheritance Chain

ItemAsset
  → ItemFilterAsset

Class Definition

public class ItemFilterAsset : ItemAsset
{
    protected AudioClip _use;
    public AudioClip use => _use;
}

The class contains exactly one field: an AudioClip loaded from the asset bundle.

Core Fields

Field	Type	Source	Description
_use	AudioClip	Bundle "Use"	Sound played when cleaning fuel

PopulateAsset

public override void PopulateAsset(in PopulateAssetParameters p)
{
    base.PopulateAsset(in p);
    _use = p.bundle.load<AudioClip>("Use");
}

The implementation is minimal — load the use sound and delegate everything else to ItemAsset. There is no .dat-redirectable fallback for the audio clip (unlike ItemConsumeableAsset which supports ConsumeAudioClip).

UseableFilter Runtime Behavior

The UseableFilter class implements the filter's actual function:

Filtering Process

1. Prerequisite: The player must be holding a fuel can (ItemFuelAsset) with contaminated fuel.
2. Activation: Right-click with the filter item equipped.
3. Consumption: The filter item is consumed (deleted from inventory). It is single-use.
4. State clearing: The fuel can's contamination state is cleared — the fuel goes from contaminated to clean.
5. Audio feedback: The _use AudioClip plays.

Fuel Contamination System

Fuel contamination is a state within the fuel can that affects its utility:

• Contaminated fuel: Causes engine damage or reduced efficiency when used in vehicles.
• Clean fuel: Normal fuel behavior.
• Filtering: The only way to convert contaminated fuel to clean fuel is through a fuel filter.

Filter Limitations

1. Single use only: Each filter cleans one fuel can exactly once. There is no durability or charge counter.
2. No quality tracking: Filters have no showQuality or quality degradation. They work perfectly every time or not at all.
3. No partial cleaning: The entire fuel can's contents are cleaned at once. No incremental cleaning.
4. Fuel can type agnostic: Any fuel can can be filtered. There is no "compatible fuel type" or contamination level check.

Comparison to Other Service Items

Feature	ItemFilterAsset	ItemFuelAsset	ItemRefillAsset
Base class	ItemAsset	ItemAsset	ItemAsset
State bytes	No (default item amount)	2 bytes (fuel amount)	1 byte (water type)
Useable class	UseableFilter	UseableFuel	UseableRefill
Consumed on use	Yes	No (decremented only)	No (state changes)
Audio	Bundle "Use"	Bundle "Use"	Bundle "Use" + .dat fallback
Quality	No	No	No
Custom description	No	Yes (fuel/percentage)	Yes (water type + stats)

Cargo Data Export

ItemFilterAsset does not override BuildCargoData. Only the base ItemAsset fields are exported. The filter's behavior is an all-or-nothing clean, so there are no stat values or configuration parameters to export beyond the standard item fields.

Common Issues

1. No compatibility system — Fuel filters don't have a "compatible fuel type" field. The UseableFilter checks the player's held fuel item regardless of contamination level. Any fuel can — even one with clean fuel — can consume a filter, wasting it with no effect.
2. Missing Use audio silent failure — If the bundle lacks a "Use" AudioClip, p.bundle.load<AudioClip>("Use") returns null. The filtering works but produces no sound. There is no fallback audio path or .dat redirect key.
3. No contamination visibility — The fuel contamination state is not visible in the fuel can's description. Players cannot tell if their fuel is contaminated without attempting to use a filter. This may cause them to waste filters on clean fuel.
4. Single-use limitation — A fuel can with 65,535 contaminated fuel requires only one filter. The filter's effectiveness is absolute regardless of fuel quantity. This may be economically unrealistic for large-scale fuel operations.
5. Cannot clean vehicle tanks directly — Filters only work on fuel cans held by the player, not on fuel already in a vehicle or generator.

Worked Code Example: Fuel Contamination Plugin

using SDG.Unturned;
using Steamworks;

public static class FuelContaminationManager
{
    /// <summary>
    /// Tags a fuel can as contaminated. Used when fuel is sourced
    /// from unrefined or unsafe locations.
    /// </summary>
    public static void ContaminateFuelCan(Player player, byte page, byte index)
    {
        ItemJar jar = player.inventory.getItem(page, index);
        if (jar == null) return;

        ItemFuelAsset fuelAsset = jar.GetAsset() as ItemFuelAsset;
        if (fuelAsset == null) return;

        // Set contamination flag via a custom state byte convention
        byte[] currentState = jar.item.state;
        if (currentState == null || currentState.Length < 3)
            currentState = new byte[3];

        currentState[2] = 1; // Contamination flag
        jar.item.state = currentState;

        ChatManager.serverSendMessage(
            "Fuel can is now contaminated.",
            UnityEngine.Color.yellow,
            toPlayer: player,
            iconURL: null,
            useRichTextFormatting: true
        );
    }

    /// <summary>
    /// Checks whether a fuel can contains contaminated fuel.
    /// Returns true if the contamination flag byte is set.
    /// </summary>
    public static bool IsFuelContaminated(ItemJar jar)
    {
        if (jar?.item?.state == null || jar.item.state.Length < 3)
            return false;
        return jar.item.state[2] == 1;
    }
}

Mermaid Diagram: Filter Usage Flow

Comparison: Filter vs. Other Fuel-Related Items

Feature	ItemFilterAsset	ItemFuelAsset	ItemOilPumpAsset	ItemGeneratorAsset
Base class	ItemAsset	ItemAsset	ItemBarricadeAsset	ItemBarricadeAsset
Consumed on use	Yes (single use)	No (transfers)	No	No (consumes fuel)
Affects fuel quality	Yes (clean contaminated)	No	No	No
State bytes	Default	2 bytes (fuel amount)	Varies	3 bytes (fuel + power)
Audio	Bundle "Use"	Bundle "Use"	None	None
Cost per use	Full item deletion	Amount decrement	N/A	Fuel decrement
Contamination source	Removes contamination	Carries contamination	N/A	N/A

Failure Modes and Common Mistakes

6. Filter wasted on clean fuel — There is no UI indication of contamination. Players routinely consume filters on clean fuel cans, getting audio feedback but no actual cleaning effect.

7. Multiple filters stacked — A player with 10 filters can right-click 10 times on the same fuel can. Each filter is consumed and plays the sound, but only the first actually clears the contamination state.

8. Filter not working on newly pumped fuel — If a server plugin sets contamination after the filter has already been applied, the filter effectiveness appears to fail (it worked, but contamination was re-applied). This is a plugin-timing issue, not a filter bug.

How This Differs from SDG Docs

• SDG docs describe contamination as a "quality level." Community documentation suggests fuel has contamination "percentages." In the SDK, contamination is a binary flag — fuel is either contaminated or clean. There is no gradual or percentage-based contamination.
• SDG docs claim filters work on generators. The wiki sometimes lists generators as filter-eligible. In the SDK, UseableFilter only checks the player's held ItemFuelAsset. Generators are not filterable — fuel must be extracted to a can first.
• SDG docs reference a "Contamination" key. Older documentation referenced a .dat key for fuel contamination. In the current SDK, contamination is managed through item state bytes at runtime, not through asset .dat configuration.

Performance Considerations

Filter usage is a one-time operation: consume item, clear state, play sound. No per-frame cost. No physics queries. No network sync beyond item consumption/deletion (standard inventory RPC). Memory footprint: ~16 bytes per filter item instance in inventory.

Deeper FAQ

Q: Can filters be crafted or are they loot-only?

Filters follow the standard ItemAsset path — they can have crafting recipes, spawn in loot tables, or be sold by vendors. There is no asset-level restriction on filter acquisition. The EItemType assignment determines which loot tables accept the filter.

Q: Can filters be used to clean water or other liquids?

No. UseableFilter only interacts with ItemFuelAsset. There is no water/food filter equivalent in the SDK. For water purification, modders must implement a custom useable class.

Q: What happens if the fuel can is destroyed during filtering?

The filter is consumed first, then the contamination state is cleared. If the fuel can is destroyed (by dropping, swapping items, or connection loss) between consumption and clearing, the filter is lost without cleaning the fuel. This is a rare race condition on high-latency servers.

Cross-References

• ItemFuelAsset — Fuel Can Items — Fuel cans that carry the contamination state cleaned by filters.
• ItemOilPumpAsset — Oil Pump Items — Oil pumps that produce fuel (potentially contaminated depending on game mode).
• Interactable Generator — Power Supply — Generators that are affected by contaminated vs. clean fuel.
• ItemRefillAsset — Refillable Container Items — Similarly small asset class with water-type state management.

Document history