Unreal Engine Plugin Manual

The Unreal Engine plugin comes with full blueprint support to make it as easy as possible to use ODIN in your game. Please make sure to have a basic understanding of how ODIN works as this helps a lot understanding the next steps.

Info

If you hover with your mouse over a blueprint image a small Copy button will appear at the top right of the image. Click on it and the Blueprint will be copied in your Clipboard. You can then paste it in your Blueprint Editor.

Basic Process

If you have read the introduction you have learned that every user connected to the same ODIN room (given by a string of your choice) will be able to exchange data and voice. An ODIN room is automatically created by the ODIN server when the first user joins and is automatically removed once the last user leaves.

To join a room an access token needs to be created. An access token gives access to an ODIN room and can be created within the client. For testing and development purposes that’s fine. In production you should create an access token on server side. We’ll provide various packages for JavaScript (npm) or PHP (Composer) to create access tokens and we also have a complete server ready to go that you can deploy as a cloud function to AWS or Google Cloud.

After the room has been joined, data can be exchanged, i.e. text chat messages or other real-time data. If your user should be able to talk to others, a microphone stream (a so called media) has to be added to the room. Now, every user can talk to every other user in that room. More advanced techniques include 3D audio that allows you to update your position every couple of seconds to the server which then makes sure, that only users nearby hear your voice to reduce traffic bandwidth and CPU usage. But more on that later.

So, to summarize, the basic process is:

  • Get an access key
  • Create an access token with the access key for a specific room id (just a string identifying the room)
  • Join the room with the access token
  • Add a media stream to connect the microphone to the room

Implementing with Blueprint

Let’s get started adding ODIN to an existing (or new) Unreal Engine Project. You’ll find all Blueprint nodes in the root folder Odin.

This is the full blueprint that we are about to create:

The blueprint that we’ll create

The blueprint that we’ll create

Creating an access key

First, you need to create an access key. As the access key is used to authenticate your requests to the server and also includes information about your tier, e.g. how many users are able to join the same room and a few other settings. You can create a free access key for up to 25 users right here. If you need more or want to go into production, you need to sign up with one of our tiers. See pricing for more information.

More information about access keys can be found in our Understanding Access Keys guide.

For now, you can use this widget to create a demo access key suitable for up to 25 concurrent users:

Press the Create Access Key button and write the access key down somewhere. We’ll need this access key a bit later down the road.

Creating an access token

Add a Generate Room Token node to your Blueprint Canvas. Now, drag out from the left Target and choose Construct a Token Generator from the list. This will add the node to your canvas and connect both. Please note: In production you would load the token from your cloud function (see above) but for now we just generate a random access token directly in the game.

Now, drag out from “Room Id” and choose Promote to Variable to create a variable for the name of the Room. You’ll need to compile your Blueprint and then enter Lobby as the default value for the room name or anything else that makes sense to you.

Next, drag out from Access Key of your Construct a Token Generator node and choose Promote to Variable. This variable will hold our access key. Compile again and set the default value to the access key you created above.

Last but not least create an Event Begin Play node and connect it to the Generate Room Token node. In most use cases you might not want players to be able to talk to everyone else right from the start. Choose another event in this case. But for testing purposes this should be fine.

Your blueprint should look like this now.

Creating an Access Token

Creating an Access Token

Configure the room access

ODIN supports various settings when joining a room (APM settings). Here you can set features like “Voice Activity Detection” and many other features.

Create a new Construct a Room node and drag out from Initial APM Settings. Choose Make Odin APM Settings from the list. This will add the node to your canvas and connect both.

You can play around with APM settings to work out good values for your type of game.

It should look like this:

Preparing a room

Preparing a room

Info

The best way to get a clean blueprint is to set the output of the Construct a Room node to a variable. Everywhere in the Blueprint you can now access the Room with a Get Room node.

Event Flow

Once you are connected to the ODIN server, a couple of events will be fired that allow you to setup your scene and connecting audio output to your player objects in the scene.

Have a look at this application flow of a very basic lobby application. Events that you need to implement are highlighted in red.

1Join Room

The user navigates to the multiplayer lobby. Here, all players currently playing the game are connected to the same ODIN room so that they can figure out what to play. The application uses Join Room to join the room. Please note: The server automatically creates the room if it does not exist. There is no need for bookkeeping on your side.

2Room Joined

The On Room Joined event is triggered that allows you to handle logic on the joining client before the user actually joins the room. Please note: After that Room Joined event you’ll receive PeerJoined and MediaAdded events for each user that is already connected to the room. So you can use the same code/blueprint for users that are already connected or will later connect to the room.

3Peer Joined

For each user connected to the same ODIN room you’ll receive an On Peer Joined event that allows you to handle logic once a peer joined the room. This event contains user data that they sent when they have joined the room and is typically used to relfect any meta data of the user in your client application.

4Media Added

For each user connected to the same ODIN room which has a microphone stream enabled (some of them might only be spectators just listening) an On Media Added event is triggered. This event needs to be handled by your application. In this callback, you need to assign the media object via the Odin Assign Synth to Media function to an Odin Synth Component.

6Media Removed

Whenever a user disconnects from the room, or closes their microhone stream an On Media Removed event is triggered. You are responsible for cleaning up the synth components that you have created earlier in the Media Added callback function using the Remove Media function.

7Peer Left

Whenever a user disconnects a room, this event is triggered. For example, you can show a push notification that a player has left the room. More info here: On Peer Left . Important notice:. Whenever a peer leaves a room, the media gets removed as well. So, aligned with this event, for each media of this peer, an On Media Removed event will be triggered as well.

Adding a Peer Joined Event

To create event handling, create a new delegate Bind to On Peer Joined node.

Warning

Unreal does not list the Bind to On Peer Joined option without dragging off of an Odin Room variable. If you want to have that option shown in any case, disable the Context Sensitive checkbox on the top right corner. Then you should find the event in the Odin/Events folder.

You’ll need to connect the Room object reference that you created earlier with the Construct a Room node. This way, you can easily handle events differently for different rooms you connect. You can even connect multiple rooms at the same time, but handle them differently in your code.

Now, that you have created that node, drag out from the Events slot until you see a red line. Next, release the mouse cursor and Unreal will automatically create the correct event node which will handle this event.

The wired up peer joined event handler

The wired up peer joined event handler

Don’t forget to connect the Exec slot with the process flow of your application. You should always setup event handling before joining a room.

The On Media Added Event

The On Media Added event is triggered whenever a user connected to the room activates their microphone, or directly after joining a room you’ll get these events for all active users in that room.

You’ll get a Media object that represents the microphone input for the peer (i.e. connected user) that this media belongs to. The Media object is a real-time representation which is basically just a number of floats that represent the users voice. A node needs to be created that translates that into audio output. This is the Odin Synth Component. You use the Odin Assign Synth to Media node that will connect both and actually activates the audio.

The easiest way is to add the Odin Sync Component to your player asset and place it somewhere near the head. Then, in your blueprint you can use the Get Component By Class node to get the Odin Sync Component from the player character.

Instead of adding the Odin Sync Component at runtime to an asset, you can also use the Add Odin Synth Component to create the component at runtime.

After wiring everything together, it should look something like that:

Handling On Media Added events

Handling On Media Added events

That’s it. Now, every user connected to the same room will be heard with full volume where the local player is located.

Info

In a real 3D shooter with 3D audio you would not choose the local player, but map the Odin Peer Id with your Unreal Player Id and then assign the Media to the corresponding player character. This way, Unreal will automatically process the audio in its audio engine and apply attenuation, e.g. dampen the volume the farther away the player is from the listener.

Joining a room

Now, we have everything in place to join a room: We have created an access token with the room id “Lobby” and have configured room settings for our client. Now let’s connect them to join a room.

Add a Join Room node to your Blueprint Canvas.

Joining a room

Joining a room

Connect the Return Value from Construct a Room with the Room input of the Join Room node. Next, connect the Return Value of your Generate Room Token node to the Token input of the Join Room node. Next, we need to configure our gateway: Drag out from URL of the Join Room node and choose Promote to Variable. This variable will hold the gateway. Compile the Blueprint and set https://gateway.odin.4players.io as the default value. This is our public gateway. You can also launch your own gateway for maximum privacy, but to get started, our public one is a good option.

As shown in the image above, you can also drag out event handling to get notifications if something went wrong. We just added simple output to the Log to see what happens.

Last but not least, you need to connect the Generate Room Token process flow output to the input of your Join Room node.

Adding a media stream

Now that we have joined a room, we need to add our microphone (at least if users should be able to talk) to the room so everyone else in the room hears what we are saying. To do that, create an Add Media node and a Create Audio Capture node and connect both as shown in the image below. As you need to start capturing from the audio device, we save the Audio Capture object in a variable and use that later to activate the microphone. By stopping the audio capture you can implement mute very easily later or something like push to talk.

Addind a microphone

Addind a microphone

You can create event handling for errors as shown before. The process is basically always the same. Odin delivers an error code, and you can use the Format Error node to create an error message that you can place in a log or somewhere else.

Warning

If you don’t find the Create Audio Capture and Start Audio Capturenode, please make sure you have the Audio Capture Plugin enabled which is part of the default Unreal installation. See FAQ for a more detailed description on how to resolve that issue.

Testing with ODIN client

As ODIN is working cross platform, you can use our ODIN client app to connect users to your Unreal based game. There are numerous use cases where this is a great option (see Use Cases Guide) but its also great for development.

Fire up your browser and load our ODIN client: https://odin.4players.de/app/. We need to configure that client to use the same access key that we use within Unreal. Click on the Gear icon next to the Connect button. You should see something like this:

Testing with ODIN client

Testing with ODIN client

Info

If you don’t see the Your Access Key option at the end of the dialog, you need to scroll down a bit.

Enter your access key that you have created earlier and that you have set in the Access Key variable exposed in the Blueprint and click on Save. Now, the ODIN client will use the same access key as your Unreal based game, connecting both platforms together.

In the connection dialog, set the same room name as you did in Unreal (i.e. Lobby), make sure the same gateway is set as in Unreal (i.e. https://gateway.odin.4players.io) and enter a name. Then click on Connect.

Connecting the room with ODIN client

Connecting the room with ODIN client

You should see something like this:

ODIN Client

ODIN Client

Now, get back to Unreal and press Play in the editor. Unreal will fire up your game and will join the same room as you have in your browser. You should here a nice sound indicating that another user has joined the room. Navigate to your browse, and now you should see another entry in the users list: “Unknown”. If you talk, you should here yourself.

Ask a colleague or fried to setup the ODIN client with your access key and the same room and you’ll be able to chat together, one inside your game and the other one in their browser. This is a great way of quickly testing if everything works fine and we do that internally at 4Players very often.