Maintenance script: UtilityConnect wiki

2026-10-19T07:07:05Z

UtilityConnect wiki

New page

Utility Connect gives your mod a shared network graph. You register your network blocks, and the library connects them, splits and merges networks, saves them per chunk and rebuilds them after a restart. This page lists the public types. Worked examples are on [[UtilityConnect:Registering Nodes|Registering Nodes]].

{| class="wikitable"
! Status
| The network side is complete. The transport types (<code>TransportProvider</code>, <code>TransferMode</code>) are interfaces only: the library does not call them and moves nothing on its own. See [[UtilityConnect:Transport API|Transport API]].
|-
! Stability
| The library is pinned to exact versions. 0.1.0-Alpha to 0.2.0-Alpha broke the API (<code>registerKindResolver</code> was added). 1.0.0 kept the API of 0.2.0-Alpha unchanged.
|}

== Setting up the dependency ==
Add Utility Connect as a '''hard dependency''' in your <code>manifest.json</code>:
<pre>
"Dependencies": {
"com.cyberpiratepenguin:utilityconnect": "1.0.0"
}
</pre>

With the hytale-tools Gradle plugin, the same line goes into <code>gradle.properties</code>:
<pre>
manifest_dependencies = com.cyberpiratepenguin:utilityconnect=1.0.0
</pre>

Compile against the Utility Connect jar (Java 25), but do not ship it inside your own jar. Players install it as a separate mod. A bundled copy would never be started by the server, so its <code>networks()</code> would always throw.

The hard dependency makes the server load Utility Connect first. Its <code>setup()</code> has finished before your plugin's <code>setup()</code> runs, so you can use the API from your own <code>setup()</code> on.

== Packages ==
Only use the <code>api</code> packages. Everything under <code>com.cyberpiratepenguin.utilityconnect.internal</code> is an implementation detail and may change at any time.

{| class="wikitable"
! Package !! Contents
|-
| <code>com.cyberpiratepenguin.utilityconnect.api</code> || <code>UtilityConnectAPI</code>
|-
| <code>com.cyberpiratepenguin.utilityconnect.api.network</code> || <code>Networks</code>, <code>NodeKind</code>, <code>NodeKindResolver</code>, <code>NodePos</code>, <code>ChunkKey</code>
|-
| <code>com.cyberpiratepenguin.utilityconnect.api.transport</code> || <code>TransportProvider<T></code>, <code>TransferMode</code>
|}

== UtilityConnectAPI ==
Static entry point.
{| class="wikitable"
! Member !! Description
|-
| <code>API_VERSION</code> || Version string of the public API, currently <code>"1.0.0"</code>. Compiled into your mod.
|-
| <code>isReady()</code> || <code>true</code> once the library's <code>setup()</code> has run, <code>false</code> before that and after shutdown.
|-
| <code>runtimeVersion()</code> || Version of the installed library, or <code>null</code> while it is not running.
|-
| <code>networks()</code> || The <code>Networks</code> access. Throws <code>IllegalStateException</code> when the library is not ready, usually because the manifest dependency is missing.
|}

== Networks ==
Access to the networks of all worlds. Every method takes the Hytale <code>World</code>; networks never span worlds.
{| class="wikitable"
! Method !! Returns !! Description
|-
| <code>addNode(World, NodePos, NodeKind)</code> || <code>boolean</code> || Registers a block as a node. It connects at once to all allowed neighbours, also across chunk borders. <code>true</code> if the position was new.
|-
| <code>removeNode(World, NodePos)</code> || <code>boolean</code> || Removes a node. Networks split on their own. <code>true</code> if the position was known.
|-
| <code>hasNode(World, NodePos)</code> || <code>boolean</code> || Whether a loaded node exists at that position.
|-
| <code>networkAt(World, NodePos)</code> || <code>Set<NodePos></code> || All nodes in the same network, including the position itself. Empty if there is no loaded node there. A node without connections returns a set with only itself.
|-
| <code>sameNetwork(World, NodePos, NodePos)</code> || <code>boolean</code> || Whether both positions are loaded and in the same network.
|-
| <code>networkCount(World)</code> || <code>int</code> || Number of separate networks in that world (loaded chunks only).
|-
| <code>nodeCount(World)</code> || <code>int</code> || Number of loaded nodes in that world.
|-
| <code>registerKindResolver(NodeKindResolver)</code> || <code>void</code> || Registers a resolver that reads a block's role on chunk load. Call once at startup.
|}

'''Threading:''' call every method on the '''world thread''' only, for example from block place and break event handlers. Never from an async command or your own thread. The world thread serialises all player actions, so no locking is needed.

'''Loaded chunks only:''' nodes in unloaded chunks are not part of any network and do not show up in queries. They come back when the chunk loads.

== NodeKind ==
Enum with the role of a node.
{| class="wikitable"
! Value !! Meaning
|-
| <code>DEVICE</code> || Storage, terminal, machine. Connects to connectors only, never directly to another device.
|-
| <code>CONNECTOR</code> || Pipe, cable. Connects to every adjacent node in all six directions.
|}
<code>isConnector()</code> and the static <code>connects(a, b)</code> (true if at least one side is a connector) express the rule in code.

== NodeKindResolver ==
Functional interface <code>NodeKind resolve(World world, NodePos pos)</code>. Utility Connect calls it on the world thread for every stored node once a chunk has loaded and its blocks can be read. Return the role of your block, or <code>null</code> if the position is not yours. The first registered resolver that returns a value wins, so another mod cannot reinterpret your blocks. Corrected roles are saved.

== NodePos and ChunkKey ==
* <code>NodePos(int x, int y, int z)</code>: immutable block position, the identity of a node. <code>of(x, y, z)</code>, <code>from(BlockPosition)</code>, <code>toBlockPosition()</code>, <code>offset(dx, dy, dz)</code>, <code>adjacent()</code> (the six face neighbours), <code>isAdjacentTo(other)</code>. The <code>y</code> value must be inside the world height, because nodes are stored with chunk-relative packed positions.
* <code>ChunkKey(int x, int z)</code>: a chunk column. <code>of(chunkX, chunkZ)</code>, <code>containing(NodePos)</code>, <code>contains(NodePos)</code>.

== Transport ==
<code>TransportProvider<T></code> and <code>TransferMode</code> are described on [[UtilityConnect:Transport API|Transport API]].

{{UtilityConnect Nav}}

UtilityConnect:Modding API - Revision history

Maintenance script: UtilityConnect wiki