Relay

Relay is a Blueprint API for Voices of the Void mods. It gives BP mods features that normally require native C++:

• observe, change, or cancel Blueprint function calls;
• register shop items, keybinds, calendar events, and dreams (WIP);
• connect game instances over UDP and exchange typed messages;
• replicate mod actors and selected vanilla classes without editing them.

Relay began as a small function watcher for an older mod. It now provides function hooks, runtime game integration, and a multiplayer transport/replication layer.

Relay calls a function hook a Watch. A Watch targets one class and function and returns an object with bindable events. A Pre Watch can change supported input parameters; a cancelable Watch can stop the call.

Networking is now the largest part of Relay. It provides low-latency UDP transport, typed messages, and a replication model inspired mainly by Unreal Engine 4.27, with ideas from Source, Doom 3, and Tribes.

Relay's goal is to let Blueprint authors create networked mods without relying on WebSockets over TCP or locking multiplayer into one closed ecosystem. Relay is designed to coexist with UE4SS and other Relay mods, allowing mods to communicate, share services, and build on one another.

Relay is not a co-op mod. It is a networking backend that other mods can use to build co-op or other multiplayer modes. Installing Relay by itself adds no host/join flow or replication rules.

Relay README Blueprint

Public test notice

This public test is intended for mod authors. It includes example assets, but it is not a finished multiplayer conversion of VotV.

Before testing multiplayer:

• back up every save involved;
• use the same Relay DLL, Relay.pak, gameplay mod, and rule profile on every machine;
• keep the UE4SS log from both machines when reporting a problem.

Relay does not provide a public lobby or a ready-to-play multiplayer mode. The release includes RelayExampleUI in cooked and editable form. Its basic Host/Join UI and rules are an integration example, not a complete gameplay mod.

To try it, rename RelayExampleUI.pak.example to RelayExampleUI.pak inside:

%AppData%\r2modmanPlus-local\VotV\profiles\<profile>\shimloader\pak\Moddy-Relay

Hosts must also set allow_listen=1 in relay_net.ini.

Raw, uncooked assets for mod authors are in the release's editor folder and on GitHub.

Install

A player needs both parts of the same Relay build. Install through r2modman, or place them manually:

1. RelayCpp at Mods/Moddy-Relay/dlls/main.dll.
2. Relay.pak at Content/Paks/LogicMods/Relay.pak or r2modman's shimmed pak path.

A mod using Relay should declare Relay as a dependency. Authors work against the assets under /Game/Mods/Relay/.

Relay_Version returns 0 when the DLL is absent. The current Blueprint API returns 3. Relay_NetVersion returns 0 when networking is unavailable and 19 for this build. Check both before enabling Relay-dependent UI or gameplay.

The DLL and pak form one API contract. If one is stale, nodes, properties, or struct fields may be missing. Replace both before debugging the gameplay mod.

Player quick start

Host

1. Copy relay_net.ini.example to <profile>/shimloader/cfg/relay_net.ini.

2. Change only:

   allow_listen=1
   

3. Allow the session's UDP port through the host firewall. Direct Internet hosting also requires forwarding that port on the router. If the gameplay mod uses LAN discovery, allow UDP Port + 1 through the firewall too. For example, a session on UDP 7777 answers LAN searches on UDP 7778. LAN discovery is not used for Internet connections.

4. Start hosting through the gameplay mod.

5. Share either the friend code shown by the mod or a reachable host:port, plus the password if one was set. Relay_NetFriendCode can provide the friend code when the mod does not display it directly.

allow_listen=1 is the only required player-side INI change. The gameplay mod supplies the port, password, peer limit, bind/public addresses, and authority policy through Blueprint nodes.

A shared password authenticates a peer. By default, a passwordless peer may connect but cannot request temporary authority over lease-backed objects. AllowPasswordlessAuthority=true removes that restriction for every connected peer. Use it only for a trusted private session.

Join

Joining requires no network INI and never opens a listening socket.

1. Install the same Relay and gameplay-mod versions as the host.
2. Paste the host's friend code into the mod's Address field. A friend code is accepted directly by Relay_NetConnect. For a direct connection, enter the host's reachable hostname/IP and session port instead.
3. Enter the same password, if the host used one.
4. Wait for the gameplay mod to load or fetch the host's save. A connected socket is not enough: replication stays closed until both machines report the same world.

A friend code pins the host's persistent identity on the first connection. It is not a password and contains no invite secret.

The gameplay mod owns this UI, save handling, and travel. RelayExampleUI shows the basic Blueprint node flow.

Mod author: session flow

Host

Relay_NetHost(
    Port=7777,
    BindAddress="",
    PublicAddress="",
    MaxPeers=8,
    Channels=8,
    Password="",
    AllowPasswordlessAuthority=false)
    -> Net, Reason

• BindAddress: interface to listen on. Blank means all interfaces and is the normal choice. 127.0.0.1 is useful only for two instances on one machine.
• PublicAddress: hostname/IP encoded into the direct friend code. It does not affect the listening socket.
• MaxPeers: requested session limit, capped by relay_net.ini.
• Channels: Relay needs eight. Request more only if your mod deliberately uses additional ENet channels.
• Password: invite secret; never stored in the INI or sent as plaintext.
• AllowPasswordlessAuthority: lets passwordless peers request leases. Leave it off for public or discoverable sessions.
• Reason: synchronous host refusal, such as missing listen permission, an invalid option, or a port that could not bind.

Relay_NetHost returns null on synchronous failure. Display Reason; do not replace it with a hard-coded guess.

Connect

Relay_NetConnect(Address, Port=7777, Channels=8, Password="") -> Net

Address accepts a hostname, an IP address, or a complete friend code. A connect is asynchronous: a returned handle means the attempt started, not that the handshake succeeded. Bind the handle's OnConnect, OnDisconnect, and OnError dispatchers.

Kick a peer

Relay_NetKickPeer(Peer) -> bool

This node is host-only. Pass a live obj_relayPeer from the current session's Peers array. true means Relay queued an orderly disconnect. It returns false when the caller is not the host, the peer is null, stale, or from another session, or no transport is active. Normal disconnect events still fire. This is a disconnect, not a ban; the peer may connect again.

Recover the process session after a map load

Host and client sessions are process-scoped. They survive map travel and the destruction of the ModActor that started the connection.

Use:

Relay_NetSession -> Net, IsRunning, IsHost, LocalPeerId

Call it from the new world's ModActor to recover the current session handle. Do not call Host or Connect again just to recover that handle. The host's LocalPeerId is 0; a client's is -1 until it receives Welcome.

Repeating Host or Connect with the exact settings for the same live endpoint returns that endpoint instead of opening another one. Relay_NetSession is the direct way to read the session that already exists.

Get a code for UI

Relay_NetFriendCode(PublicAddress="") -> Code, Reason

• With a configured rendezvous service and a blank input, it returns the rendezvous code.
• Otherwise it returns the direct code created by Relay_NetHost.
• Supplying PublicAddress creates a direct code for that address.
• It refuses wildcard addresses and explains the missing prerequisite in Reason.

Session events and state

Bind these on obj_relayNet:

The handle also maintains IsRunning, IsHost, LocalPeerId, Peers, and basic byte/ping statistics.

OnConnect means the transport is ready. It does not mean actors may replicate. Gate multiplayer gameplay on OnWorldStatusChanged.ReplicationOpen, or query:

Relay_NetWorldStatus
    -> LocalKnown, HostKnown, IdentityMatches, ReplicationOpen
    -> LocalMap, LocalSaveId, HostMap, HostSaveId, Reason

Show Reason when the fence is closed. Do not hide a save mismatch behind a generic "connecting" message.

World/save identity

The world fence always compares the map. A gameplay mod that knows the save should also provide its stable identity:

• Relay_NetSetWorldIdentity(SaveId) when the mod already has the value.
• Relay_NetSetWorldIdentitySource(Holder, PropertyName) when Relay should re-read a property.

Both sources are cleared on map load; set them from each world's ModActor. For VotV, the relevant game-instance property is commonly slotName.

Relay_NetHostWorld returns the host's announced map/save. Use Relay_NetPublishSave and Relay_NetRequestSave only as the transfer plane; the gameplay mod still owns save consent, naming, loading, and travel.

Built-in VotV adapters

These adapters do not make ordinary VotV actors replicable by themselves. Mod authors must still declare the same rules on every peer, include one per-peer player presentation, use Transform or TransformAttach for physical actors, and wait for ReplicationOpen. An explicit Player role is optional when exactly one per-peer VotV player presentation exists; register the role to remove ambiguity or to use that player as a routed-function identity.

Replication model

For every actor, answer four separate questions:

Mod-owned actor

Add comp_relayNet and declare its Fields, Events, authority, identity, presence, and optional remote class. Relay registers the actor when the component starts.

Vanilla or third-party class

Build a struct_relayNetRuleDef and call:

Relay_NetBindClass(Def, Owner=self) -> Rule

The Rule handle exposes OnActorBound and OnActorUnbound. Use those events instead of rescanning the world. Relay_NetRuleBoundActors is the current snapshot for UI or late initialization.

Large rule sets can live in shimloader/cfg/relay_rules.json; set rules_profile=relay_rules.json in the public INI. Every peer must use the same rule contract.

When a ModActor already has the full JSON document as a string, call Relay_NetLoadRulesJson(RulesJson). It accepts the same relay.rules.v1 schema as the file profile and adds the rules to the same pending rule set. Invalid JSON or an invalid top-level document returns false and installs nothing. A valid document returns true; malformed rows inside it are logged and skipped. Loading the same semantic document again in one world is a successful no-op. Rules are cleared on map travel, so each new ModActor must still declare them again for the new world. An explicit Relay_NetBindClass rule still takes priority over a profile rule for the same class. Load the same accepted rules on every peer before replication starts.

Fields

A field name can be a reflected property such as Health, an object-relative path such as Component.Value, or one of Relay's predefined pseudo-fields. Pseudo-field names begin with $, are case-sensitive, and do not require a matching Blueprint property.

Each field row also controls when and how often Relay sends it, wire precision, optional smoothing, and an optional zero-argument OnRep callback.

Field order is part of the wire schema. Append new fields. Do not insert, remove, or reorder rows between compatible builds.

Whole reflected structs and arrays are supported when both sides have the same shape. Actor/object pointers are not portable across processes; send a stable id/key and resolve it locally.

Identity

• Use a stable NetKey when both machines already create the same logical object.
• Use bPerPeer for exactly one object per peer, such as a remote-player proxy or name badge.
• Leave the key blank for a runtime actor spawned on one authority; Relay mints an id and the spawn record carries it.
• Use Relay_NetRegisterActor when you assign a key at runtime.
• Use Relay_NetBind only when an id is already exchanged out of band.

Do not give independently spawned objects the same key while declaring each side as Owner authority. Both machines will believe they own one object and Relay will reject the conflict.

Presence and auto-spawn

Auto-spawn is on by default for eligible mod actors. A remote class must be known locally and allowed by the receiver's own component/rule contract. Derived world identities are never spawned as duplicates. Rate, total, queue, and per-frame work limits are enforced internally.

Use RemotePresence=BindExisting for actors the world already creates, SpawnProxy when only a presentation proxy should exist remotely, and BindOrSpawn when a save actor may or may not exist on the receiver.

Authority and leases

Use Relay_NetIsAuthority(Actor) before writing replicated state. Relay_NetAuthorityFor answers who owns it and whether the current ownership is a lease.

For an interaction that may wait on the host, prefer:

Relay_NetRequestAuthorityAsync(Actor) -> Request
Bind Request.OnGranted / Request.OnDenied

Always release a lease when the interaction ends:

Relay_NetReleaseAuthority(Actor)

The older Relay_NetRequestAuthority returns only whether a request was sent; it is not a grant result.

Events and routed functions

A replicated field is durable state. An event is a one-time action.

Give every declared Event or RoutedFunction one clear direction: client to host/authority, authority to one peer, or authority to all peers. Replicate durable values such as health, position, or an open/closed flag as fields. Then use OnRep to update local effects or UI when a value changes. Do not send durable state only as an event: late joiners and resync cannot recover its current value.

Arbitrary messages

For chat or mod-specific data not owned by an actor:

Relay_NewParams -> AddString/AddInt/... -> Net.Broadcast
Net.OnMessage -> GetString/GetInt/...

Channels 0 through 7 are allocated to Relay planes. If a mod deliberately uses a higher channel, request enough Channels on Host and Connect on every peer. Prefer Relay's typed actor/event surfaces for gameplay.

Diagnostics

Call Relay_Debug after WorldReady. It returns stable RLY-* issue strings and error/warning/info counts. Also useful:

• Relay_NetMarkDirty(Actor, PropertyName) forces the next authoritative field flush; blank marks all fields.
• Relay_NetRequestResync(Actor) asks for bounded targeted recovery of one remote-owned actor. This is diagnostics/recovery, not normal gameplay.
• Relay_NetIdFor, Relay_NetFindByKey, Relay_NetPeer, and Relay_NetRuleBoundActors expose current state without log scraping.

Watch and integration API

Observe a Blueprint call

1. Call Relay_Watch(Class, Function, Phase=Post, Owner=self, bAllowTick=false).
2. Bind the returned Sub's OnFired dispatcher.
3. Read Target, Function, Phase, and Params in the handler.

Params supports Bool, Int, Float, String, Name, Byte, Vector, Rotator, and Object getters. Has and ListParams are safer than guessing a pin name. Caller and CallerFunction identify the Blueprint frame that made the call.

A Pre watch may change supported input parameters with Set*. A Post watch is observation only.

Use Relay_WatchCancelable and call Params.Cancel() to suppress a function. Cancellation rewrites Blueprint bytecode. It is allowed for shipped game Blueprints by default and can damage gameplay or saves if used carelessly. relay_gates.ini supplies the operator kill switches.

Pass Owner=self for subscriptions and rule handles so they die with the world. Host/connect sessions are the exception and intentionally have no Owner pin.

Voice API

Voice is separate from session hosting. Copy relay_voice.example.ini to relay_voice.ini and set allow_capture=1 before opening a microphone. With 0, Relay can list devices but refuses to open capture hardware. Listing devices and changing the preferred device do not open the microphone.

The public nodes are Relay_VoiceListDevices, Relay_VoiceOpen, Relay_VoiceGet, Relay_VoiceBindSink, Relay_VoiceMonitorLocal, Relay_VoiceSetPreferredDevice, and Relay_VoiceGetPreferredDevice. Relay_VoiceVersion returns 0 when unavailable.

Settings

All persistent settings and identity files live under <profile>/shimloader/cfg/. Package updates should not replace this directory.

log_votv_hints=0
allow_listen=0
max_peers=8
server_name=
rendezvous_address=
punch_only=0
rules_profile=relay_rules.json

enabled=1
dump_prologue=0
allow_game_functions=1

Troubleshooting

When reporting a multiplayer bug, include both UE4SS logs, exact DLL/pak/mod versions, host/connect options, map/save names, and whether direct or rendezvous transport was used.

Node reference