UOdinRoom
An opaque type representing an ODIN room handle, which is managed by the underlying connection. This abstraction provides a high-level interface for joining rooms, managing persistent state and sending/receiving data, making it easier to integrate room-based interactions into your application.
- Header:
#include "OdinRoom.h" - Module:
Odin - Inherits from:
UObject - Blueprint: Blueprint type, Blueprintable · Blueprint reference
Overview
Functions
| Name | Description |
|---|---|
ConstructRoom | Creates a new room object for the given world context. |
CloseRoom | Gracefully leaves the room: closes the native room, which makes our own peer leave the room on the server, waits for the native "closed" status (at most CloseTimeoutSeconds) and only then frees the native room. |
IsClosing | Whether CloseRoom was called and the native room has not been freed yet. |
CloseOdinRoomByHandle | Starts closing the specified native room, thus making our own peer leave the room on the server. |
FreeRoom | Frees the native room immediately. |
FreeRoomByHandle | Destroys the specified ODIN room handle and releases all underlying resources. |
FlushKnownPeers | Reports every peer this room announced via OnRoomPeerJoinedBP as left, through the same path as a real peer left event, and forgets them. |
ReleaseHandle | Frees the native room (if any), drops the subsystem registration and invalidates the crypto and all socket wrappers. |
InvalidateAllSockets | Invalidates all socket wrappers of this room without touching the native sockets. |
GetConnectionGeneration | Monotonic counter that is bumped whenever the native room handle changes (connect, free). |
ConnectRoom | Connects the room to an ODIN gateway and joins it with the given authentication token. |
ConnectRoomNative | Connects this room via the native API using this object's registered event callbacks. |
GetOwnPeerId | Get last retrieved peer id that represents "self". |
GetReconnectToken | Returns the latest reconnect token the server issued for this room (see On New Reconnect Token). |
GetRoomName | Returns the ID of the joined room, as reported by On Room Joined. |
GetConnectionStats | Returns statistics of the room's connection: the UDP datagrams and bytes sent and received, and the round-trip time. |
SendRpc | Sends a JSON-encoded RPC message to the server. |
ChangeSelf | Updates the local peer's User Data. |
SetChannelMasks | Sends the channel masks the local peer listens to, per remote peer. |
SetListenChannelMask | Sets the channel mask used when listening to peers that do not have a per-peer override set via SetListenChannelMaskForPeer. |
SetListenChannelMaskForPeer | Overrides the channel mask used when listening to a specific peer, taking precedence over the default set via SetListenChannelMask. |
ClearListenChannelMaskForPeer | Removes a previously set per-peer listen channel mask override, falling back to the default set via SetListenChannelMask for that peer. |
SendMessage | Sends an arbitrary data message to a specific list of peers. |
SendAudio | Drain Encoder pipline for audio data and sends encoded voice packets to the server. |
GetOdinRoomName | Returns the name of the room as reported by the native room handle. |
IsConnected | Returns true if the client is currently connected to the ODIN server and the room session is active. |
SetRoomEvents | Replaces the event callback struct used for future room creations. |
GetRoomEvents | |
RemoveRoomEvents | |
GetRoomCipher | |
GetHandle | |
SetHandle | |
SetPassword | Set a string password as arbitary shared secret. |
GetDecodersByPeer | Returns all decoders that are registered for the given peer of this room (see Register Decoder to Peer). |
CreateLocalSocket | Create an uobject socket, sets the native handle and refreshes socket info |
CreateRemoteSocket | Create an uobject socket, sets the native handle and refreshes socket info |
GetSocketByHandle | Gets socket from this room |
GetOrCreateRoomSocket | Gets socket from this room or creates a remote socket with the provided handle |
RemoveSocket | Close native socket and return uobject socket |
OpenSocket | Opens a socket to a peer in this room, or to all peers with a Target Peer Id of 0. |
RemoveSocketsForPeer | Close and remove all sockets whose remote peer is the given peer. |
RemoveAllSockets | Closes and removes all sockets of this room. |
Properties
| Name | Description |
|---|---|
CloseTimeoutSeconds | How long CloseRoom waits for the native "closed" status before it frees the room anyway. |
Crypto | Optional instance of pluggable encryption module for room communications. |
Events
| Name | Description |
|---|---|
OnRpcBP | Raised for every RPC the server sends to this room, with the raw JSON. |
OnSocketBP | Raised when a message arrives on any socket of this room. |
OnRoomStatusChangedBP | Raised when the connection status of the room changes: joining while (re)connecting, joined once the room is joined, and closed after the room was closed. |
OnRoomNewReconnectTokenBP | Event triggered when the server issues a new reconnect token. |
OnRoomMessageReceivedBP | Event triggered when an arbitrary message is received from a peer. |
OnRoomJoinedBP | Event triggered when the local client has successfully joined the room. |
OnRoomPeerJoinedBP | Event triggered when a remote peer joins the room. |
OnRoomPeerChangedBP | Event triggered when a remote peer updates their user data. |
OnRoomPeerLeftBP | A peer left the room. |
OnRoomErrorBP | Raised when the server reports an error for this room. |
OnRoomClosed | Native-only notification that a close started via CloseRoom has ended: the native room was freed after the "closed" status arrived or CloseTimeoutSeconds elapsed, or it was released otherwise while the close was pending (FreeRoom, ConnectRoom, destruction). |
Functions
ConstructRoom
Overload 1
Static · Blueprint: Construct Room
Creates a new room object for the given world context. It does not connect yet: bind the room events, then call ConnectRoom. The second overload wraps an existing native room (and optional cipher).
| Parameter | Type | Description |
|---|---|---|
WorldContextObject | UObject* |
Returns UOdinRoom* – The constructed room object.
Overload 2
Static
| Parameter | Type | Description |
|---|---|---|
WorldContextObject | UObject* | |
handle | OdinRoom* | |
crypto | OdinCipher* | Default: nullptr. |
Returns UOdinRoom*
CloseRoom
Blueprint: Close Room
Gracefully leaves the room: closes the native room, which makes our own peer leave the room on the server, waits for the native "closed" status (at most CloseTimeoutSeconds) and only then frees the native room. Every announced peer is reported via OnRoomPeerLeftBP before the "closed" status is broadcast; OnRoomClosed fires once the native room is freed.
Returns bool – False if there was no native room to close.
Must be called on the game thread. Returns false if there is no native room. Use FreeRoom to release the native room immediately without waiting.
IsClosing
Const · Inline · Blueprint: Is Closing
Whether CloseRoom was called and the native room has not been freed yet.
Returns bool
CloseOdinRoomByHandle
Static
Starts closing the specified native room, thus making our own peer leave the room on the server. The native close is asynchronous; the room reports the "closed" status afterwards.
| Parameter | Type | Description |
|---|---|---|
room | OdinRoom* |
Returns bool
To release resources, call FreeRoomByHandle. Freeing right after closing suppresses the "closed" status. Prefer CloseRoom on the owning UOdinRoom.
FreeRoom
Blueprint: Free Room
Frees the native room immediately. Announced peers are reported via OnRoomPeerLeftBP first. The native free closes the room as well, but the "closed" status is not delivered anymore.
Returns bool – True if a native room was freed.
FreeRoomByHandle
Static
Destroys the specified ODIN room handle and releases all underlying resources.
| Parameter | Type | Description |
|---|---|---|
room | OdinRoom* |
Returns bool
Since the handle could be invalid for the SDK while connecting, manual call odin_room_free would work, even if the room is still connecting. If the handle belongs to a registered UOdinRoom, this behaves like FreeRoom on that object.
FlushKnownPeers
Reports every peer this room announced via OnRoomPeerJoinedBP as left, through the same path as a real peer left event, and forgets them. Used when the session ends without the server sending peer left events: connection loss, close, free and reconnect. Game thread only.
ReleaseHandle
Frees the native room (if any), drops the subsystem registration and invalidates the crypto and all socket wrappers. Safe to call during destruction; every path that frees the native room must go through this, so the handle cannot be freed twice. Ends a pending CloseRoom and fires OnRoomClosed for it; no other delegate fires here, so callers that want announced peers reported as left call FlushKnownPeers first.
InvalidateAllSockets
Invalidates all socket wrappers of this room without touching the native sockets. Used when the native room is freed, since its sockets die with it.
GetConnectionGeneration
Const · Inline
Monotonic counter that is bumped whenever the native room handle changes (connect, free). Deferred event tasks compare it to detect that their captured native handles belong to a previous connection, even if a new native room reuses the same pointer value.
Returns uint64
ConnectRoom
Blueprint: Connect Room
Connects the room to an ODIN gateway and joins it with the given authentication token. The call returns right away: On Room Joined fires once the room is joined, and On Peer Joined fires for every peer that is already in the room or joins later. Bind the room events before calling this node.
| Parameter | Type | Description |
|---|---|---|
gateway | FString | The Gateway URL (e.g. 'https://gateway.odin.4players.io'). |
authentication | FString | The authentication token (JWT) or signed JSON payload. Generate this using Generate Room Token. |
bSuccess | bool& | True if the connection was started. Failures are logged. |
crypto | UOdinCrypto* | Optional crypto extension for end-to-end encryption, created with Construct Crypto Extension. Leave it empty for an unencrypted room. Default: nullptr. |
Returns UOdinRoom* – The room itself.
ConnectRoomNative
Connects this room via the native API using this object's registered event callbacks. Shares the full lifecycle handling (reconnect cleanup, cipher ownership, subsystem registration) with ConnectRoom, but returns the raw error code.
| Parameter | Type | Description |
|---|---|---|
Gateway | const FString& | |
Authentication | const FString& | |
InCrypto | UOdinCrypto* |
Returns OdinError
GetOwnPeerId
Blueprint: Get own Peer ID
Get last retrieved peer id that represents "self".
Returns int64 – The local peer's unique ID.
GetReconnectToken
Blueprint: Get Reconnect Token
Returns the latest reconnect token the server issued for this room (see On New Reconnect Token).
Returns FString – The reconnect token string.
GetRoomName
Blueprint: Get Room Name
Returns the ID of the joined room, as reported by On Room Joined. Empty before the room is joined.
Returns FName – The room name.
GetConnectionStats
Blueprint: Get Connection Stats
Returns statistics of the room's connection: the UDP datagrams and bytes sent and received, and the round-trip time.
Returns FOdinConnectionStats – Struct containing connection metrics.
SendRpc
Blueprint: Send Rpc
Sends a JSON-encoded RPC message to the server.
| Parameter | Type | Description |
|---|---|---|
json | FString | JSON rpc string |
Returns bool – true on ODIN_ERROR_SUCCESS or false
ChangeSelf
Blueprint: Send ChangeSelf Rpc
Updates the local peer's User Data. This data is synced to all other peers in the room (triggering On Peer Changed). Use this to broadcast player names, team info, or avatar URLs.
| Parameter | Type | Description |
|---|---|---|
request | FOdinChangeSelf | Change own peer request |
Returns bool – true on ODIN_ERROR_SUCCESS or false
SetChannelMasks
Overload 1
Blueprint: Send SetChannelMasks Rpc
Sends the channel masks the local peer listens to, per remote peer. Voice packets of a peer are only delivered on the channels of its mask. For most cases, the Set Listen ChannelMask nodes are easier to use: they keep the masks of known and newly joining peers up to date.
| Parameter | Type | Description |
|---|---|---|
request | const FOdinSetChannelMasks& | Change channel mask |
Returns bool – true on ODIN_ERROR_SUCCESS or false
Overload 2
Call SendRpc to set channel masks.
| Parameter | Type | Description |
|---|---|---|
masks | TMap<int64, uint64> | Masks to set, with map from peer Id to channel mask |
reset | bool |
Returns bool – true on ODIN_ERROR_SUCCESS or false
SetListenChannelMask
Blueprint: Set Listen ChannelMask
Sets the channel mask used when listening to peers that do not have a per-peer override set via SetListenChannelMaskForPeer. Applies immediately to every currently known peer and is automatically applied to peers that join afterward.
| Parameter | Type | Description |
|---|---|---|
Mask | FOdinChannelMask | channel mask to listen to for all peers without an override |
Returns bool – true on ODIN_ERROR_SUCCESS or false
Convenience wrapper around SetChannelMasks; for one room instead of multiple rooms
SetListenChannelMaskForPeer
Blueprint: Set Listen ChannelMask For Peer
Overrides the channel mask used when listening to a specific peer, taking precedence over the default set via SetListenChannelMask. Useful for finer per-sender control, e.g. always hearing party members on the non-spatialized group channel even when standing next to them.
| Parameter | Type | Description |
|---|---|---|
PeerId | int64 | peer to override the listen channel mask for |
Mask | FOdinChannelMask | channel mask to listen to for this peer |
Returns bool – true on ODIN_ERROR_SUCCESS or false
ClearListenChannelMaskForPeer
Blueprint: Clear Listen ChannelMask For Peer
Removes a previously set per-peer listen channel mask override, falling back to the default set via SetListenChannelMask for that peer.
| Parameter | Type | Description |
|---|---|---|
PeerId | int64 | peer to remove the override for |
Returns bool – true on ODIN_ERROR_SUCCESS or false
SendMessage
Blueprint: Send Message Rpc
Sends an arbitrary data message to a specific list of peers. Keep list empty, to send to all peers.
| Parameter | Type | Description |
|---|---|---|
request | const FOdinSendMessage& | Set Message |
Returns bool – true on ODIN_ERROR_SUCCESS or false
SendAudio
Blueprint: Send Audio
Drain Encoder pipline for audio data and sends encoded voice packets to the server.
| Parameter | Type | Description |
|---|---|---|
encoder | UOdinEncoder* | encoder to drain all datagrams |
Returns bool
GetOdinRoomName
Const · Blueprint: Get Odin Room Name
Returns the name of the room as reported by the native room handle.
Returns FString – room as string representation
IsConnected
Const · Blueprint: Is Connected
Returns true if the client is currently connected to the ODIN server and the room session is active.
Returns bool – true if JoinedStatus
SetRoomEvents
Replaces the event callback struct used for future room creations.
| Parameter | Type | Description |
|---|---|---|
roomcb | const OdinRoomEvents& |
The native room clones the event struct on odin_room_create, so changes made here have no effect on an already-created room; they only apply to the next connect.
GetRoomEvents
Returns OdinRoomEvents*
See also: SetRoomEvents for the remark on already-created rooms
RemoveRoomEvents
See also: SetRoomEvents for the remark on already-created rooms
GetRoomCipher
Returns OdinCipher*
GetHandle
Const · Inline
Returns OdinRoom*
SetHandle
Inline
| Parameter | Type | Description |
|---|---|---|
handle | OdinRoom* |
SetPassword
Const · Blueprint: Set Crypto Password
Set a string password as arbitary shared secret.
| Parameter | Type | Description |
|---|---|---|
Password | const FString | shared secret |
GetDecodersByPeer
Const · Blueprint: Get Decoders by Peer
Returns all decoders that are registered for the given peer of this room (see Register Decoder to Peer).
| Parameter | Type | Description |
|---|---|---|
PeerId | const int64 | Registered Decoder PeerId |
Returns TArray<UOdinDecoder*>
Used for registered/linked decoders in subsystem (GetDecodersFor)
CreateLocalSocket
Create an uobject socket, sets the native handle and refreshes socket info
| Parameter | Type | Description |
|---|---|---|
SocketKind | EOdinSocketKind | Kind of Socket i.e. reliable or unreliable |
TargetPeerId | int64 | Remote PeerId |
Label | int32 | Arbitrary Id |
Priority | int32 | Packet transport priority |
Returns TWeakObjectPtr<UOdinSocket>
Used for sockets with ownership
CreateRemoteSocket
Create an uobject socket, sets the native handle and refreshes socket info
| Parameter | Type | Description |
|---|---|---|
SocketHandle | OdinSocket* | Native Socket |
Returns TWeakObjectPtr<UOdinSocket>
Used for remote peer event sockets where this client does not have ownership
GetSocketByHandle
Const
Gets socket from this room
| Parameter | Type | Description |
|---|---|---|
SocketHandle | const OdinSocket* | Native Socket |
Returns TWeakObjectPtr<UOdinSocket>
GetOrCreateRoomSocket
Gets socket from this room or creates a remote socket with the provided handle
| Parameter | Type | Description |
|---|---|---|
SocketHandle | OdinSocket* | Native Socket |
Returns TWeakObjectPtr<UOdinSocket>
RemoveSocket
Close native socket and return uobject socket
| Parameter | Type | Description |
|---|---|---|
SocketHandle | const OdinSocket* | Native Socket |
Returns UOdinSocket*
OpenSocket
Blueprint: Open Socket
Opens a socket to a peer in this room, or to all peers with a Target Peer Id of 0. Send data with Send or Send String on the returned socket. The receivers get it through On Socket on their room and On Socket Message Received on their socket.
| Parameter | Type | Description |
|---|---|---|
TargetPeerId | int64 | Remote PeerId, or 0 to broadcast to all peers in the room |
SocketKind | EOdinSocketKind | Kind of socket |
Returns UOdinSocket*
Sockets are bound to the current room session and do not survive a reconnect. Sockets to a specific peer are closed automatically when that peer leaves the room, since the server recycles peer ids and a stale socket could otherwise reach a later peer under the same id; broadcast sockets (target peer 0) stay open for the whole session.
RemoveSocketsForPeer
Blueprint: Remove Peer Sockets
Close and remove all sockets whose remote peer is the given peer.
| Parameter | Type | Description |
|---|---|---|
PeerId | int64 | Remote PeerId |
Called automatically when the peer leaves the room. Outbound sockets are closed for good (the server recycles peer ids, so sending on a stale socket could reach a later peer under the same id); for inbound sockets only the wrapper object is released, the native socket stays open because the native layer reuses its address when a peer with the recycled id opens new sockets.
RemoveAllSockets
Blueprint: Remove All Sockets
Closes and removes all sockets of this room.
Properties
CloseTimeoutSeconds
Static · Constexpr
How long CloseRoom waits for the native "closed" status before it frees the room anyway. The native close only starts the leave; the status confirms that the connection is gone.
Crypto
Blueprint: Get/Set
Optional instance of pluggable encryption module for room communications. A cipher can be attached to the room on creation to enable customizable, end-to-end encryption(E2EE). Needs ODIN_USE_CRYPTO with CryptoExtention and associated library.
Events
OnRpcBP
Blueprint: On Rpc
Raised for every RPC the server sends to this room, with the raw JSON. The typed room events (On Room Joined, On Peer Joined, On Room Status Changed, ...) are raised in addition for the RPCs they handle.
Signature: FOdinRoomRpcDelegate void(UOdinRoom* room, FString json) (multicast)
OnSocketBP
Blueprint: On Socket
Raised when a message arrives on any socket of this room. The socket's own On Socket Message Received event is raised as well.
Signature: FOdinSocketDelegate void(UOdinSocket* socket, TArray<uint8> message) (multicast)
OnRoomStatusChangedBP
Blueprint: On Room Status Changed
Raised when the connection status of the room changes: joining while (re)connecting, joined once the room is joined, and closed after the room was closed.
Signature: FOdinRoomStatusChangedDelegate void(UOdinRoom* room, FOdinRoomStatusChanged data) (multicast)
OnRoomNewReconnectTokenBP
Blueprint: On New Reconnect Token
Event triggered when the server issues a new reconnect token.
Signature: FOdinNewReconnectTokenDelegate void(UOdinRoom* room, FOdinNewReconnectToken data) (multicast)
OnRoomMessageReceivedBP
Blueprint: On Message Received
Event triggered when an arbitrary message is received from a peer.
Signature: FOdinMessageReceivedDelegate void(UOdinRoom* room, FOdinMessageReceived data) (multicast)
OnRoomJoinedBP
Blueprint: On Room Joined
Event triggered when the local client has successfully joined the room.
Signature: FOdinJoinedDelegate void(UOdinRoom* room, FOdinJoined data) (multicast)
OnRoomPeerJoinedBP
Blueprint: On Peer Joined
Event triggered when a remote peer joins the room.
Signature: FOdinPeerJoinedDelegate void(UOdinRoom* room, FOdinPeerJoined data) (multicast)
OnRoomPeerChangedBP
Blueprint: On Peer Changed
Event triggered when a remote peer updates their user data.
Signature: FOdinPeerChangedDelegate void(UOdinRoom* room, FOdinPeerChanged data) (multicast)
OnRoomPeerLeftBP
Blueprint: On Peer Left
A peer left the room. Also raised synthetically for every peer this room announced via OnRoomPeerJoinedBP when the local session ends: on connection loss (status "joining"), on close (status "closed") and when the native room is freed or replaced by a reconnect. Each announced peer is reported as left exactly once, so handlers can tear down per-peer state without tracking the room status themselves.
Signature: FOdinPeerLeftDelegate void(UOdinRoom* room, FOdinPeerLeft data) (multicast)
OnRoomErrorBP
Blueprint: On Room Error
Raised when the server reports an error for this room.
Signature: FOdinErrorDelegate void(UOdinRoom* room, FOdinError data) (multicast)
OnRoomClosed
Native-only notification that a close started via CloseRoom has ended: the native room was freed after the "closed" status arrived or CloseTimeoutSeconds elapsed, or it was released otherwise while the close was pending (FreeRoom, ConnectRoom, destruction). Fired exactly once per CloseRoom, on the thread that released the room, after the synthetic peer left and the status changed events.
Signature: FOdinRoomClosedNativeDelegate void(UOdinRoom*) (multicast)