RealtimeIO
Socket.IO realtime client for Unreal

Overview

RealtimeIO connects Unreal Engine to any Socket.IO server. It emits and receives named events with JSON or binary payloads, supports namespaces and server acknowledgements, reconnects automatically, and exposes everything through an actor component that works identically from Blueprints and C++.

Typical uses: game/session chat, live dashboards and telemetry, matchmaking lobbies, IoT bridges, companion apps, and any gameplay that must react to server pushes without polling.

Requirements

Installation

From Fab

1. Install the plugin to your engine through the Epic Games Launcher (Library → Fab Library → Install to Engine).
2. Open your project, then open Edit → Plugins, search for RealtimeIO and make sure it is enabled. Restart the editor if prompted.

Manual (per-project) install

1. Copy the RealtimeIO folder into your project's Plugins/ directory (create the directory if it doesn't exist).
2. C++ projects: right-click the .uproject → Generate project files, then build. Blueprint-only projects can launch the editor directly — the editor compiles the plugin on first load.
3. Confirm the plugin is listed and enabled under Edit → Plugins → Networking.

Setting up a server

RealtimeIO is a client. To try it you need a Socket.IO server to connect to — the plugin talks to any Socket.IO-compatible implementation you may already run in production. If you don't have one yet, the reference Node.js server takes two minutes:

1. Install Node.js (LTS) from nodejs.org — the installer includes npm.
2. Create an empty folder, open a terminal in it and run:

   npm init -y
   npm install socket.io

3. Save the following as server.js:

   const { Server } = require("socket.io");
   const io = new Server(3000);
   
   io.on("connection", (socket) => {
     console.log("client connected:", socket.id);
   
     // echo any "chat message" event back to every client
     socket.on("chat message", (msg) => {
       console.log("received:", msg);
       io.emit("chat message", msg);
     });
   
     // acknowledgement example (see the Acknowledgements section)
     socket.on("ping me", (data, ack) => {
       if (ack) ack({ pong: Date.now() });
     });
   
     socket.on("disconnect", () => console.log("client left:", socket.id));
   });
   
   console.log("Socket.IO server listening on http://localhost:3000");

4. Run it: node server.js

Your server is now reachable at http://localhost:3000 — the plugin's default address. For other languages and production topics (rooms, scaling, TLS termination) see the official guides at socket.io/docs.

Quick start — Blueprints

Goal: connect, receive chat message events, and send one. No C++ involved.

1. Open (or create) an actor Blueprint and click Add Component → RealtimeIO.
2. Select the component. In Details → RealtimeIO Connection Properties you'll find URL Params → Address And Port, preset to http://localhost:3000. Change it to your server if needed.
3. Should Auto Connect is on by default, so the component connects on Begin Play. (Untick it if you prefer to call Connect yourself.)
4. With the component selected, add the On Connected event from the Details panel's Events section. It fires with your Socket Id and Session Id once the handshake completes.
5. Receive events: call Bind Event To Generic Event (Event Name = chat message) — e.g. right after On Connected — then add the component's On Generic Event event. Every bound event arrives there with its Event Name and an Event Data (RealtimeIO Json Value) pin. Drag off Event Data and use To String (JsonValue) to print it.
6. Send events: call Emit (Event Name = chat message). The Message pin accepts a plain String, Integer, Float or Bool directly — Blueprint auto-casts them via the To JsonValue conversion nodes. For structured payloads see Working with JSON.

Quick start — C++

Add the modules to your <Game>.Build.cs:

PrivateDependencyModuleNames.AddRange(new string[] {
    "RealtimeIO", "RealtimeIOJson", "Json"
});

Minimal actor that connects, listens and emits:

#include "RealtimeIOComponent.h"

AMyActor::AMyActor()
{
    Socket = CreateDefaultSubobject<URealtimeIOComponent>(TEXT("RealtimeIO"));
}

void AMyActor::BeginPlay()
{
    Super::BeginPlay();

    // bind before (or after) connecting - both work
    Socket->OnNativeEvent(TEXT("chat message"),
        [](const FString& Event, const TSharedPtr<FJsonValue>& Payload)
        {
            UE_LOG(LogTemp, Log, TEXT("%s: %s"), *Event, *Payload->AsString());
        });

    Socket->Connect(TEXT("http://localhost:3000"));
}

void AMyActor::SendHello()
{
    Socket->EmitNative(TEXT("chat message"), FString(TEXT("Hello from Unreal!")));
}

EmitNative is overloaded for FString, numbers, bool, TArray<uint8> (binary), TSharedPtr<FJsonObject>, TSharedPtr<FJsonValue>, arrays of values, and even raw UStruct* pointers (auto-converted to JSON). Every overload takes an optional callback receiving the server's acknowledgement:

Socket->EmitNative(TEXT("ping me"), FString(),
    [](const TArray<TSharedPtr<FJsonValue>>& Response)
    {
        // Response holds the arguments the server passed to ack(...)
    });

Component reference

Everything below lives on URealtimeIOComponent (Blueprint category “RealtimeIO”).

Functions

Events

Key properties

Working with JSON

Payloads travel as RealtimeIO Json Value / RealtimeIO Json Object objects (module RealtimeIOJson).

Building a payload

1. Simple values: plug a String / Integer / Float / Bool straight into Emit — the To JsonValue autocast nodes convert them implicitly. Byte arrays convert the same way for binary.
2. Objects: create a RealtimeIO Json Object (Construct node), fill it with its Set String/Number/Bool/Array/Object Field nodes, then plug it into Emit (autocasts via To JsonValue (JsonObject)).
3. Whole structs: To JsonValue (Struct) / Struct To Json Object serialize any Blueprint struct in one node — ideal for sending gameplay state. Json Object To Struct does the reverse on receive.

Reading a payload

1. Drag off Event Data and use To String / To Integer / To Float / To Bool / To Bytes (JsonValue) for simple values.
2. For objects: To Object (JsonValue), then Get … Field nodes — or the editor's Break Json node, which exposes chosen fields as typed output pins.
3. Files: Save Struct To Json File / Load Json File To Struct persist structs to disk as JSON.

Base64 helpers (Base64 Encode / Decode, string and bytes variants) and Percent Encode are included for interop with web APIs.

Acknowledgements (request/response)

Socket.IO lets the server answer a specific emit. Three ways to consume the reply:

Server side, an acknowledgement is just the callback parameter: socket.on("ping me", (data, ack) => ack({ pong: Date.now() })) — see the server example.

Namespaces

Namespaces multiplex one physical connection into separate channels (/, /chat, /admin, …). Every Emit and Bind node has a Namespace pin (default /). Binding or emitting to a namespace joins it automatically; Join Namespace / Leave Namespace give you explicit control, and On Socket Namespace Connected / Disconnected report membership changes. Normalize Namespace (utility) ensures a name is /-prefixed.

Binary data

Socket.IO supports raw binary alongside JSON. In Blueprints, plug a Byte array into Emit (autocast To JsonValue (Bytes)) and read incoming binary with To Bytes (JsonValue). In C++ use the TArray<uint8> overload of EmitNative; incoming binary values arrive as FJsonValueBinary. Useful for screenshots, audio chunks, or compact custom protocols.

Utility node pack

General-purpose networking utilities added to URealtimeIOFunctionLibrary — available from Blueprints and C++.

Troubleshooting

Extending the plugin

Full source ships in the package — you can read, debug and modify every layer:

To iterate on the plugin itself, install it into a C++ project's Plugins/ folder (see manual install) so your IDE rebuilds it with the project. C++ types are exported (REALTIMEIO_API), so game modules can subclass the component or call RealtimeIONative directly.

Credits & third-party

© Alpha XP — alphaxp.net. Developed and maintained for UE 4.27, 5.7 and 5.8.

The plugin bundles the header-only libraries asio, websocketpp and rapidjson (in Source/ThirdParty, compiled into the plugin — no separate installation required). Their license texts are included in the package. The Socket.IO server is separate software installed by you (see Setting up a server) under its own license (MIT for the Node.js reference implementation).