Maintenance script: UtilityConnect wiki

2026-10-19T07:07:06Z

UtilityConnect wiki

New page

This page shows how a mod adds its blocks to Utility Connect networks. All types are explained on [[UtilityConnect:Modding API|Modding API]]. The helper methods in the examples (<code>blockIdAt</code>, <code>isMyBlock</code>, <code>isMyPipe</code>) stand for your own code.

== Overview ==
# Add the manifest dependency (see [[UtilityConnect:Modding API#Setting up the dependency|Modding API]]).
# In your plugin's <code>setup()</code>, register a <code>NodeKindResolver</code>.
# When one of your blocks is placed, call <code>addNode</code>. When it is broken, call <code>removeNode</code>.
# Query networks with <code>networkAt</code>, <code>sameNetwork</code> and the counters whenever you need them.

Loading and saving are handled by the library. You do not need to re-register nodes after a restart or when a chunk loads.

== 1. Register a resolver ==
The resolver tells Utility Connect which of your blocks is a device and which is a connector. It is asked on every chunk load and fixes stored roles that are out of date.
<pre>
import com.cyberpiratepenguin.utilityconnect.api.UtilityConnectAPI;
import com.cyberpiratepenguin.utilityconnect.api.network.NodeKind;

@Override
protected void setup() {
UtilityConnectAPI.networks().registerKindResolver((world, pos) -> {
String blockId = blockIdAt(world, pos);
if (blockId == null || !isMyBlock(blockId)) {
return null; // not my block: do not guess
}
return isMyPipe(blockId) ? NodeKind.CONNECTOR : NodeKind.DEVICE;
});
}
</pre>
Always return <code>null</code> for positions that are not yours. Then the stored role stays, and other mods keep control over their own blocks.

== 2. Add and remove nodes ==
Call these from your block place and break handlers, on the world thread.
<pre>
import com.cyberpiratepenguin.utilityconnect.api.UtilityConnectAPI;
import com.cyberpiratepenguin.utilityconnect.api.network.NodeKind;
import com.cyberpiratepenguin.utilityconnect.api.network.NodePos;

void onMyBlockPlaced(World world, NodePos pos, String blockId) {
NodeKind kind = isMyPipe(blockId) ? NodeKind.CONNECTOR : NodeKind.DEVICE;
UtilityConnectAPI.networks().addNode(world, pos, kind);
}

void onMyBlockBroken(World world, NodePos pos) {
UtilityConnectAPI.networks().removeNode(world, pos);
}
</pre>
Use <code>NodePos.from(blockPosition)</code> to convert a Hytale <code>BlockPosition</code>.

Notes:
* The new node connects at once. Merging and splitting networks happen automatically.
* <code>addNode</code> on a position that is already a node returns <code>false</code>. If you pass a different kind, the node's role and connections change in memory, but no save is triggered for that call. A registered resolver corrects the stored role on the next chunk load.
* The chunk containing the node is saved automatically (see [[UtilityConnect:Persistence|Persistence]]).

== 3. Query networks ==
<pre>
Networks networks = UtilityConnectAPI.networks();

// All nodes connected to this block, including itself.
// Empty if there is no loaded node at that position.
Set<NodePos> members = networks.networkAt(world, pos);

// Are a terminal and a storage block linked?
boolean linked = networks.sameNetwork(world, terminalPos, storagePos);

// Statistics for a status command.
int networkCount = networks.networkCount(world);
int nodeCount = networks.nodeCount(world);
</pre>
A typical use is to collect all your device blocks from <code>networkAt</code> and work on their contents, for example to list every item stored in a network.

== Checking the version at runtime ==
<pre>
if (UtilityConnectAPI.isReady()) {
String running = UtilityConnectAPI.runtimeVersion(); // installed library
String compiled = UtilityConnectAPI.API_VERSION; // API you compiled against
}
</pre>
<code>networks()</code> throws <code>IllegalStateException</code> while the library is not ready. With a correct hard dependency this does not happen during your <code>setup()</code>, <code>start()</code> or normal gameplay. Use <code>isReady()</code> in code that might run during shutdown.

== Rules to keep in mind ==
* '''World thread only.''' Never call the API from an async command or another thread.
* '''Loaded chunks only.''' Queries only see nodes in loaded chunks. A network that runs through an unloaded chunk appears split until the chunk loads.
* '''Devices need connectors.''' Two <code>DEVICE</code> nodes side by side do not connect. Give your mod a connector block, or register blocks that should link directly as <code>CONNECTOR</code>.
* '''No diagonals.''' Only the six face neighbours connect.
* '''Positions inside the world height.''' Nodes are stored with packed chunk-relative coordinates, and a <code>y</code> outside the world height cannot be saved.

{{UtilityConnect Nav}}

UtilityConnect:Registering Nodes - Revision history

Maintenance script: UtilityConnect wiki