Maintenance script: UtilityConnect wiki

2026-10-19T07:07:06Z

UtilityConnect wiki

New page

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

{| class="wikitable"
! Important
| Utility Connect does '''not''' use these types itself. It moves no items, fluids or energy, and it does not look up a <code>TransportProvider</code> 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 <code>networkAt</code>. The interfaces give mods a shared vocabulary for that.
|}

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

{| class="wikitable"
! Member !! Description
|-
| <code>long insert(T resource, long amount, TransferMode mode)</code> || Tries to take in <code>amount</code> units. Returns how much was actually accepted, between 0 and <code>amount</code>. Throws <code>IllegalArgumentException</code> for a negative amount.
|-
| <code>long extract(T resource, long amount, TransferMode mode)</code> || Tries to give out <code>amount</code> units. Returns how much was actually removed, between 0 and <code>amount</code>. Throws <code>IllegalArgumentException</code> for a negative amount.
|-
| <code>long capacity()</code> || Total capacity, or <code>UNLIMITED</code>. Not the free space: ask <code>insert</code> with <code>SIMULATE</code> for that.
|-
| <code>int tier()</code> || Upgrade tier, 0-based, higher is better. Default <code>0</code>.
|-
| <code>UNLIMITED</code> || Constant <code>Long.MAX_VALUE</code> 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 <code>SIMULATE</code> changes nothing and returns the same value as an <code>EXECUTE</code> call made right after it. Callers plan transfers based on this, and breaking it makes resources disappear.

== TransferMode ==
{| class="wikitable"
! Value !! Meaning
|-
| <code>SIMULATE</code> || Only calculate, change nothing. For questions like "does this fit?".
|-
| <code>EXECUTE</code> || Actually perform the transfer.
|}
<code>isSimulation()</code> returns <code>true</code> for <code>SIMULATE</code>.

== Example ==
A simple item buffer that implements the contract:
<pre>
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;
}
}
</pre>

Moving 64 units from <code>source</code> to <code>target</code> without losing anything:
<pre>
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);
</pre>

{{UtilityConnect Nav}}

UtilityConnect:Transport API - Revision history

Maintenance script: UtilityConnect wiki