OmniGRPC Quick Start

In this tutorial, you send login credentials from Blueprint to the downloaded sample server. No C++ work is required.

The features used in this tutorial (.proto import and Unary RPC) are also available in the Free Edition. The Free Edition supports only Windows (Win64).

Unary is the most basic communication method: send data once and receive the result once.

Blueprint structure

In this tutorial, the sample server and Unreal Editor run on the same PC. Complete Setup before continuing.

    flowchart TD
	  Begin[BeginPlay] --> Create[Create Channel → save to variable]
	  Create --> Valid{"Is the Channel valid?"}
	  Valid -->|Yes| Wait[Wait for gRPC Channel Connected]
	  Valid -->|No| Config[Check connection settings]
	  Wait --> Result{"On Connected → Success"}
	  Result -->|true| Request[Make LoginRequest]
	  Result -->|false| Retry[Show connection failure]
	  Request --> Call[Call gRPC: Login]
	  Call -->|On Success| Response[Check LoginResponse]
	  Call -->|On Error| Error[Check Status Code and Message]
	  End[EndPlay] --> Cancel[Cancel the running Action]
	  Cancel --> Close[Close Channel]

1. Download the sample server

Open the OmniGRPC Sample Server download page, download the package for the OS of your development PC, and extract it.

The package contains the GUI application, user_service.proto, TUTORIAL.md, and THIRD_PARTY_NOTICES.md. On macOS, open the DMG and copy user_service.proto from the same location as the application to your working folder.

2. Start the sample server

Windows

Extract the ZIP and double-click OmniGrpcTestServer.exe.

macOS

Copy OmniGrpcTestServer.app from the DMG to Applications and double-click it. Use the arm64 package on Apple Silicon and the amd64 package on an Intel Mac.

Linux

Extract the ZIP. In a terminal, move to the extracted folder and run the application, replacing <version> with the version of the file you downloaded.

chmod +x OmniGrpcTestServer_<version>_linux-amd64.AppImage
./OmniGrpcTestServer_<version>_linux-amd64.AppImage

If mounting fails in your environment, add --appimage-extract-and-run to the end of the launch command.

Check the startup result

Keep the application running until you finish the tutorial. The listen address is retained the next time you start the application.

The sample server does not encrypt its communication. Do not expose it to the internet; use it only on your local PC.

3. Import the .proto file

Drag user_service.proto from the downloaded package into the Unreal Editor Content Browser. This file describes the shape of the data sent to and received from the sample server. Import it without modifying its contents.

Confirm that the following assets were generated.

• LoginRequest Struct
• LoginResponse Struct
• UserService Service Asset

See Setup for a detailed explanation of the generated assets.

4. Create a Channel

Connection settings and storage

Add a Make Insecure Channel Config node and set Host to 127.0.0.1 and Port to 50051. Connect this config to a Create Channel node and save the return value in a variable of type OmniGrpcChannel.

A Channel is an object that manages the connection to the server. If you communicate with the same server multiple times, reuse the Channel. In this tutorial, save it in a Level Blueprint variable.

Wait for the connection

Check that the return value is valid, then pass the Channel to Wait for gRPC Channel Connected and set Timeout Seconds to 5.0. Connect the Success output of On Connected to a Branch and run the next Login step only when it is true. If it is false, show a connection failure.

On Connected is also called with false when the connection fails. In this example, branch on success and failure using On Connected only, and leave On Timeout unconnected. Connecting failure handling to both events would run the same logic twice.

Insecure means that communication is not encrypted. This setting is for the sample only. For a game or app you publish, use the TLS settings in Data Types and Production Settings.

5. Create a LoginRequest

Add the generated Make LoginRequest node and set Username to alice and Password to tutorial. This Struct is the login information sent to the server.

The sample server does not verify the password. This example is for checking communication and is not production authentication. Do not enter a real password or expose it in logs or on screen.

6. Run the Login RPC

1. Right-click the Blueprint graph, search for gRPC, and add a Call gRPC Unary node.
2. Set Service on the node to the generated UserService.
3. Select the node and choose Login from gRPC → Method Name in the Details panel.

Choose the Method in the Details panel. There is no Method input pin. The candidates show only the Unary methods of the selected Service.

After you choose a Method, the node name becomes Call gRPC: Login, and the Request and Response pins switch to LoginRequest and LoginResponse. Run this node from the success branch of the connection wait.

The Unary node has no Then output immediately after it starts. If you want to save the Action so you can cancel the call, place a Sequence on the success branch of the connection wait, call Login from Then 0, and save the Action output of the Login node to a variable from Then 1.

7. Handle the result

Run Play in the Editor. When communication succeeds, On Success is called. Break the Response with Break LoginResponse and check the following values.

In a real service, save the received token to a variable and use it to authenticate subsequent calls. Treat the token like a password and do not show it in logs.

If communication fails, On Error is called. Break the Status with a Break node and check the Code and Message. Common Codes and responses are listed below.

8. Shut down the Channel and the sample server

When the Level or game ends, call Cancel if the saved Action is still valid, then call Close Channel. Close Channel alone does not stop an RPC that is already in progress. A closed Channel cannot be reused, so create a new Channel the next time you communicate.

On the sample server, click “Stop” to stop listening, then click “Exit” or close the window to quit the application.

Try the error cases too

These input values are specific to the sample server. After changing the settings, run Play again and check the On Error handling.

Troubleshooting

1. Is the server listening on 127.0.0.1:50051?
2. Did you import user_service.proto from the downloaded package?
3. Did you set Service on Call gRPC Unary to UserService and Method Name in Details to Login?
4. What Code and Message appear in On Error?
5. Are there any issues with the firewall, VPN, or the route from a mobile device?

Continue to the Use Case Guides for the next implementation steps by purpose.