Standalone Microservices are new! This feature is intended for developers who are comfortable with writing DotNet solutions.
Starting with Beamable 1.11.0, it is possible to use a Beamable Microservice outside of Unity. This comes with many advantages.
- You can control the
Dockerfileof your Microservice.
- You can use Nuget packages.
- You can select your version of dotnet.
- You can run the service locally without
dockerif you prefer
- Unity doesn't need to be able to compile the Microservice code.
You must have an existing Beamable organization and login available.
You will need to install the Beamable CLI and the Beamable Dotnet Templates to get started.
dotnet tool install --global beamable.tools
dotnet new --install beamable.templates
Verify your installation by confirming you can execute
beam --version and that
dotnet new --list --tag beamable yields three results. If you are using dotnet version 7, use
dotnet new list --tag beamable
Now you can use the Beamable CLI to create a new Microservice and link it to a Unity project. The following command will create a new
.sln file configured with a Beamable Microservice. It will also require you to log into Beamable.
In the final phase of the
beam project new command, you will be asked if you want to link a Unity project. If you do, that Unity project will receive autogenerated
.cs client files and common
.dll files anytime the Standalone Microservice is built. You can link a project later too.
The second command will open the
.sln file in your default editor.
beam project new Example
Example.cs file contains the Microservice code. The Microservice class is equivalent to the ones from a Unity project. The same rules and conventions apply.
public class Example : Microservice
public int Add(int a, int b)
return a + b;
The Microservice can be run locally by running the Example project from your IDE, or by running
dotnet run. You can use the IDE to debug, or use
dotnet watch -- run to use hot reload.
You can open a swagger page to look at your local service by running
beam project open-swagger Example
To deploy the Microservice, use the following commands.
beam services ps --remote
beam services deploy
readme.md file for more details.
If you haven't already done so through the
beam project new flow, you can add associated Unity or Unreal projects to your Standalone Microservice. Run this command from your Standalone Microservice folder. The argument should be the relative path to a local Unity project.
beam project add-unity-project ../../MyProject
Behind the scenes, this will give the Standalone Microservice a relative reference to the Unity project. Anytime the Microservice builds, it will automatically generate the client code in the Unity project.
In the linked Unity project, you can write code that accesses the autogenerated client.
var ctx = await BeamContext.Default.Instance;
var client = ctx.Microservices().Example();
var sum = await client.Add(1,2);
When you run the Unity client, it will send a request to your local running Standalone Microservice if it is running. If your Microservice is not running, then the request will be sent to the remote Microservice.
Why are my Microservice requests are timing out?
If the requests are timing out in Unity, but you know for a fact your local Microservice is running, there may be a few things to check...
- Make sure you are using Beamable 1.16 or later.
- Make sure that Unity and your Standalone Microservice are using the same cid/pid.
In order to add a Microstorage object to a Standalone Microservice, run the following command from the recently created
/Example folder. You will be prompted for which Microservices should depend upon the new Storage. Use the space key to select services.
beam project new-storage MyStorage
This will create a third project in the existing
.sln. It will also modify the
.csproj file of any dependent service.
Microstorage objects will run automatically using Docker when you start a service that depends on the Microstorage object. You can see the running Microstorage object by checking
docker ps, or using Docker Desktop.
You can view the local data by running the following command,
beam services run
beam project open-mongo MyStorage
ExampleCommon project is a place to write code that will be shared with Unity and your Standalone Microservice. By default, this project has no dependencies. However, if you want to use Beamable primitives, such as
Promise, you can add a Nuget package reference to Beamable.Common .
When you build the Standalone Microservice, it will automatically build and copy the common built
.dll file into all linked Unity or Unreal projects.
.envfile: If you are experiencing issues starting up your Microservice locally, it may be because you are missing relevant environment information (customer id, project id). To create one,
cdto the specific microservice directory, and run
beam login --save-to-file. This will prompt you to login and create a
Updated 4 months ago