UtilityConnect:Transport API

The package com.cyberpiratepenguin.utilityconnect.api.transport describes a common contract for blocks that take in or give out a resource: a chest, a tank or a battery.

Important	Utility Connect does not use these types itself. It moves no items, fluids or energy, and it does not look up a TransportProvider for a node. If your mod wants to move resources through a network, it does that on its own, for example by walking the nodes from networkAt. The interfaces give mods a shared vocabulary for that.

TransportProvider<T>

Generic over the resource type T (for example an item key), so the same contract can be used for items, fluids and energy.

Member	Description
long insert(T resource, long amount, TransferMode mode)	Tries to take in amount units. Returns how much was actually accepted, between 0 and amount. Throws IllegalArgumentException for a negative amount.
long extract(T resource, long amount, TransferMode mode)	Tries to give out amount units. Returns how much was actually removed, between 0 and amount. Throws IllegalArgumentException for a negative amount.
long capacity()	Total capacity, or UNLIMITED. Not the free space: ask insert with SIMULATE for that.
int tier()	Upgrade tier, 0-based, higher is better. Default 0.
UNLIMITED	Constant Long.MAX_VALUE for "practically unlimited".

Contract for implementations:

• Partial transfers are normal. Return the amount actually moved. Do not throw because less fits than requested.
• Simulation must be exact. A call with SIMULATE changes nothing and returns the same value as an EXECUTE call made right after it. Callers plan transfers based on this, and breaking it makes resources disappear.

TransferMode

Value	Meaning
SIMULATE	Only calculate, change nothing. For questions like "does this fit?".
EXECUTE	Actually perform the transfer.

isSimulation() returns true for SIMULATE.

Example

A simple item buffer that implements the contract:

import com.cyberpiratepenguin.utilityconnect.api.transport.TransferMode;
import com.cyberpiratepenguin.utilityconnect.api.transport.TransportProvider;

public final class ItemBuffer implements TransportProvider<String> {
    private final long capacity = 1000;
    private final Map<String, Long> stored = new HashMap<>();

    @Override
    public long insert(String itemId, long amount, TransferMode mode) {
        if (amount < 0) throw new IllegalArgumentException("amount");
        long used = stored.values().stream().mapToLong(Long::longValue).sum();
        long accepted = Math.min(amount, capacity - used);
        if (!mode.isSimulation() && accepted > 0) {
            stored.merge(itemId, accepted, Long::sum);
        }
        return accepted;
    }

    @Override
    public long extract(String itemId, long amount, TransferMode mode) {
        if (amount < 0) throw new IllegalArgumentException("amount");
        long removed = Math.min(amount, stored.getOrDefault(itemId, 0L));
        if (!mode.isSimulation() && removed > 0) {
            stored.merge(itemId, -removed, Long::sum);
        }
        return removed;
    }

    @Override
    public long capacity() {
        return capacity;
    }
}

Moving 64 units from source to target without losing anything:

long possible = source.extract(item, 64, TransferMode.SIMULATE);
long fits = target.insert(item, possible, TransferMode.SIMULATE);
long moved = source.extract(item, fits, TransferMode.EXECUTE);
target.insert(item, moved, TransferMode.EXECUTE);