RPC with C# (Unity)

Using RPC in Unity is very helpful when you have a experiment paradigm build in Unity and you want to run real-time data analysis in PhysioLabXR.

Setup

To use RPC with C#, PhysioLabXR needs the grpc plugin to compile protobuf into C# code. Additionally, you need the grpc packages in Unity to use the generated C# code. This section will guide you through the setup process.

Install dotnet SDK on MacOS

On MacOS, part of the installation (i.e., homebrew) requires admin privileges. So PhysioLabXR will not be able to install the dotnet-sdk automatically.

Please follow these steps to install the dotnet-sdk manually:

  1. You will need to install home brew, a package manager for MacOS, following the instructions here.

  2. Once home brew is install, install the dotnet-sdk using this command:

brew install --cask dotnet-sdk

  1. Once the dotnet-sdk is installed, restart PhysioLabXR and it should automatically install and configure the grpc plugin.

Install dotnet SDK on Windows

The setup for Windows involve install dotnet SDK via winget. The process is handled automatically by PhysioLabXR when it starts. Should you run into any problems, please refer to the troubleshooting page.

Set GRPC dependencies in Unity

On the Unity side, you can setup the grpc dependencies using one of the following methods.

Method 1: Using the Unity-PhysiolabXR-Package

In the Unity Editor, open the Package Manager, click on the +s button and select Add package from git URL. Add the following URL to the package manager:

https://github.com/PhysioLabXR/Unity-PhysioLabXR-Package.git

PhysioLabXR’s Unity Package has more than just the grpc package. Read more about it here.

Method 2: Manually installing the packages

Alternatively, you can manually install the grpc package and all its dependencies. We also need a third-party HTTP2 handler because Unity’s built-in HTTP handler does not support HTTP2.

To install the grpc package:

  1. In your Unity project, install NuGetForUnity, a package manager for NuGet packages in Unity.

  2. Install the following NuGet packages:

    • Grpc.Net.Client

    • Google.Protobuf

To install the HTTP2 handler, follow the instructions here.

Start Using RPC in Unity

If you installed the package with the Unity-PhysiolabXR-Package, you can import the samples from the package. In Unity’s package manager, you can find the samples if you select the PhysioLabXR package and click on the Samples tab.

The GRPC example include a sample scene with a script named ExampleClient.cs that shows how to communicate from the Unity client to the server in PhysioLabXR.

The sample PhyScript that contains the server code is named VariousArgsAndReturnsRPCExample.py. You can find the example here.

Here’s a video that shows how to run the example. It includes the following steps.

The time in the brackets indicates the time in the video when the step is shown:

  1. (0:00) Add the PhysioLabXR package into Unity.

  2. (0:22) Import the GRPC samples from the package into the Unity assets, and opens the sample scene.

  3. (0:42) Load the PhyScript VariousArgsAndReturnsRPCExample.py in PhysioLabXR.

  4. (1:01) Set the output path of the C# protobuf files to where the Unity project is. This will generate the client C# files in the Unity project when you run the PhyScript.

Note

You only need to set the output path when you

  • add new RPC functions

  • change the name of existing RPC functions

  • change the arguments or return values of existing RPC functions

because the above changes will change how the client calls RPCs from the server, there the client files (C# in this case) need to be regenerated.

  1. (1:15) Start the PhyScript to compile and start the RPC server.

  2. (1:31) Start the Play Mode in Unity to call the server from the client by pressing the Press Me button.

Note

Before you enter Play Mode in step 6, you may need to adjust the port number in Unity to match that of the server. In the GameObject “RPCClient”, you can find the ExampleClient.cs script. In the script, you must change the “Host” to match the server’s port number. PhysioLabXR uses the localhost by default, meaning the server and client are on the same machine. In this case, the port number on the Unity side should be http://localhost:<port number>. See example below:

../_images/grpc_unity_ports.png

Further Information

If your RPC is long-running, you may want to consider using Async RPC to prevent blocking the Unity application.