UtilityConnect:Registering Nodes

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

Overview

1. Add the manifest dependency (see Modding API).
2. In your plugin's setup(), register a NodeKindResolver.
3. When one of your blocks is placed, call addNode. When it is broken, call removeNode.
4. Query networks with networkAt, sameNetwork 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.

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;
    });
}

Always return null 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.

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);
}

Use NodePos.from(blockPosition) to convert a Hytale BlockPosition.

Notes:

• The new node connects at once. Merging and splitting networks happen automatically.
• addNode on a position that is already a node returns false. 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 Persistence).

3. Query networks

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);

A typical use is to collect all your device blocks from networkAt and work on their contents, for example to list every item stored in a network.

Checking the version at runtime

if (UtilityConnectAPI.isReady()) {
    String running = UtilityConnectAPI.runtimeVersion();   // installed library
    String compiled = UtilityConnectAPI.API_VERSION;       // API you compiled against
}

networks() throws IllegalStateException while the library is not ready. With a correct hard dependency this does not happen during your setup(), start() or normal gameplay. Use isReady() 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 DEVICE nodes side by side do not connect. Give your mod a connector block, or register blocks that should link directly as CONNECTOR.
• No diagonals. Only the six face neighbours connect.
• Positions inside the world height. Nodes are stored with packed chunk-relative coordinates, and a y outside the world height cannot be saved.