ObjectDeliverer Blueprint API Reference

This page documents the API that ObjectDeliverer exposes to Blueprint. The same API is available from C++. For guidance on choosing between the parts, see the Use Cases page.

How the API fits together

The ObjectDeliverer API consists of four parts.

    flowchart TB
	  M["ObjectDelivererManager<br>Start / Send / Close"] --> P["Protocol"]
	  M --> R["PacketRule"]
	  M --> D["DeliveryBox (optional)"]
	  D -->|"Send / Received"| M
	  P -->|"Connected / Disconnected / ReceiveData"| M

UObjectDelivererManager

This class manages the whole communication. Keep a reference to it from Start until Close.

Create Object Deliverer Manager

Creates the manager.

Store the return value in a member variable. If it is not referenced anywhere, it becomes a garbage collection target and communication stops.

Start

Starts communication.

If communication is already running, call Close before starting again.

Close

Ends communication and releases connections and resources. All connected clients are disconnected. Call it when the level ends (in EndPlay).

Send

Sends data to all connected destinations.

SendTo

Sends data only to the specified destination. Use it with a TCP/IP server to send to a specific client.

IsConnected

Returns whether the manager is connected (true: connected, false: disconnected).

ConnectedList

The read-only list of currently connected destination objects. Use it when a TCP/IP server handles multiple clients.

With Object Deliverer Logger

Attaches a logger described in Logging. The return value is the manager itself, so you can chain the call right after creation. Pass nullptr to detach.

Is Event With Game Thread

Whether events are processed on the game thread (default: true). This is the same setting as the argument of Create Object Deliverer Manager.

Events

Protocol

Protocols are created with UProtocolFactory nodes and passed to Start.

UProtocolFactory node list

See the corresponding sections of Use Cases for the behavior and typical usage of each protocol.

Nodes common to protocol objects

Each protocol object (the return type of a Create Protocol ... node) provides the following nodes, except for a few protocols.

The With ... nodes return the protocol itself, so calls can be chained. The default buffer size is 1 MB.

GetIPAddress / GetIPAddressInString

Available on TCP/IP protocol objects and on destinations (ClientSocket) accepted by a server. Returns the IP address as bytes or as a string. Use it to identify the sender.

Additional WebSocket client nodes

Additional TLS client nodes (UProtocolTcpIpClientTls)

The return value of Create Protocol Tcp Ip Client Tls provides nodes that configure certificate verification.

Get Last Tls Error reports handshake failures (for example, a chain signed by a distrusted CA), certificate or CA configuration failures, and connections that drop right after the handshake. It is cleared once a connection is established.

Additional TLS server nodes (UProtocolTcpIpServerTls)

PacketRule

PacketRules are created with UPacketRuleFactory nodes.

Both the sender and the receiver must use the same rule. See Switching the packet fragmentation rules for details.

DeliveryBox

DeliveryBoxes are created with UDeliveryBoxFactory nodes and passed to the DeliveryBox input of Start.

UObjectDeliveryBoxUsingJson nodes

UUtf8StringDeliveryBox nodes

Logging

After attaching a UObjectDelivererLogger to a manager with With Object Deliverer Logger, internal plugin logs are delivered to Blueprint.

The On Log Message event has the following parameters.

Use it to investigate communication that does not behave as expected. Custom loggers can be created by inheriting UObjectDelivererLoggerBase.

Enums

C++ implementation example

The following example implements a TCP server in C++. It uses the same parts as the Blueprint configuration.

void UMyClass::Start()
{
    auto deliverer = UObjectDelivererManager::CreateObjectDelivererManager();

    // Set up event handlers
    deliverer->Connected.AddDynamic(this, &UMyClass::OnConnect);
    deliverer->Disconnected.AddDynamic(this, &UMyClass::OnDisConnect);
    deliverer->ReceiveData.AddDynamic(this, &UMyClass::OnReceive);

    // Start communication
    // Protocol: TCP/IP server
    // Division rule: header (size) + body
    // Serialization: byte array
    deliverer->Start(UProtocolFactory::CreateProtocolTcpIpServer(9099),
                     UPacketRuleFactory::CreatePacketRuleSizeBody());
}

void UMyClass::OnConnect(UObjectDelivererProtocol* ClientSocket)
{
    // Send data
    TArray<uint8> buffer;
    deliverer->Send(buffer);
}

void UMyClass::OnDisConnect(UObjectDelivererProtocol* ClientSocket)
{
    // Handle disconnection
    UE_LOG(LogTemp, Log, TEXT("closed"));
}

void UMyClass::OnReceive(UObjectDelivererProtocol* ClientSocket, const TArray<uint8>& Buffer)
{
    // Handle received data
}

Lifecycle and retention summary

1. Keep the manager created with Create Object Deliverer Manager in a member variable.
2. The Protocol, PacketRule, and DeliveryBox passed to Start are retained internally by the manager during communication. When you use the Received event of a DeliveryBox, also store the DeliveryBox itself in a variable for the event binding.
3. With a TCP/IP server or a UDP receiver, manage destinations using the ClientSocket of the Connected event and ConnectedList. SendTo sends to a specific destination.
4. Call Close when communication is no longer needed. If the object is destroyed without calling it, connections may remain.