session-dsm-grpc-plugin-server-csharp

flowchart LR
   subgraph AccelByte Gaming Services
   CL[gRPC Client]
   end
   subgraph Extend Override App
   SV["gRPC Server"]
   end
   CL --- SV

Loading

AccelByte Gaming Services (AGS) features can be customized using Extend Override apps. An Extend Override app is basically a gRPC server which contains one or more custom functions which can be called by AGS instead of the default functions.

Overview

This repository provides a project template to create an Extend Override app for session dsm grpc plugin server written in C#. It includes an example of how the custom functions can be implemented. It also includes the essential gRPC server authentication and authorization to ensure security. Additionally, it comes with built-in instrumentation for observability, ensuring that metrics, traces, and logs are available upon deployment.

You can clone this repository to begin developing your own Extend Override app for session dsm grpc plugin server. Simply modify this project by implementing your own logic for the custom functions.

Prerequisites

1. Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed.

   a. Bash

   bash --version
   
   GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
   ...
   

   b. Make

   • To install from Ubuntu repository, run: sudo apt update && sudo apt install make

   make --version
   
   GNU Make 4.3
   ...
   

   c. Docker (Docker Engine v23.0+)

   • To install from Ubuntu repository, run: sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2
   • Add your user to docker group: sudo usermod -aG docker $USER
   • Log out and log back in so that the changes take effect

   docker version
   
   ...
   Server: Docker Desktop
    Engine:
     Version:          24.0.5
   ...
   

   d. .NET 8 SDK

   • On Linux Ubuntu:

     To install from the Ubuntu repository, run sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0.

   • On Windows or macOS:

     Follow Microsoft's documentation for installing .NET on Windows or on macOS.

     dotnet --version
     
     8.0.119
     

   e. Postman

   • Use binary available here

   f. extend-helper-cli

   • Use the available binary from extend-helper-cli.

   g. Local tunnel service that has TCP forwarding capability, such as:

   • Ngrok

     Need registration for free tier. Please refer to ngrok documentation for a quick start.

   • Pinggy

     Free to try without registration. Please refer to pinggy documentation for a quick start.

   ❗ In macOS, you may use Homebrew to easily install some of the tools above.

   git clone https://github.com/AccelByte/session-dsm-grpc-plugin-go.git
   

   a. Base URL

   • Sample URL for AGS Shared Cloud customers: https://spaceshooter.prod.gamingservices.accelbyte.io

   b. Create a Game Namespace if you don't have one yet. Keep the Namespace ID.

   c. Create an OAuth Client with confidential client type. Keep the Client ID and Client Secret.

Setup

To be able to run this app, you will need to follow these setup steps.

1. Create a docker compose .env file by copying the content of .env.template file.

   ⚠️ The host OS environment variables have higher precedence compared to .env file variables: If the variables in .env file do not seem to take effect properly, check if there are host OS environment variables with the same name. See documentation about docker compose environment variables precedence for more details.

2. Fill in the required environment variables in .env file as shown below.

   AB_BASE_URL=https://prod.gamingservices.accelbyte.io        # Base URL of AccelByte Gaming Services prod environment
   AB_CLIENT_ID='xxxxxxxxxx'                                   # Client ID from the Prerequisites section
   AB_CLIENT_SECRET='xxxxxxxxxx'                               # Client Secret from the Prerequisites section
   PLUGIN_GRPC_SERVER_AUTH_ENABLED=false                       # Enable or disable access token and permission verification
   DS_PROVIDER='DEMO'                                          # Select DS implementation, DEMO, GAMELIFT, or GCP
   
   // AWS Gamelift Config
   AWS_ACCESS_KEY_ID='xxxxxxx'                                 # AWS access key if using gamelift
   AWS_SECRET_ACCESS_KEY='xxxxxx'                              # AWS secret key if using gamelift
   AWS_REGION='us-west-2'                                      # AWS region for gamelift
   GAMELIFT_REGION='us-west-2'                                 # alias of AWS_REGION
      
   // GCP Config
   GCP_SERVICE_ACCOUNT_FILE='./account.json'                   # GCP service account file in json format
    GCP_PROJECT_ID=xxxxx-xxxx                                   # GCP Project ID
   GCP_NETWORK=public                                          # GCP Network type
   GCP_MACHINE_TYPE=e2-micro                                   # GCP intance type
   GCP_REPOSITORY=asia-southeast1-docker.pkg.dev/xxxx/gcpvm    # GCP Repository
   GCP_RETRY=3                                                 # GCP Retry to get instance
   GCP_WAIT_GET_IP=1                                           # GCP wait time to get the instance IP in seconds
   GCP_IMAGE_OPEN_PORT=8080                                    # Dedicated server open port
   

For more options, create src/AccelByte.PluginArch.SessionDsm.Demo.Server/appsettings.Development.json and fill in the required configuration.

{
  "EnableAuthorization": true,                  // Enable or disable access token and permission check (env var: PLUGIN_GRPC_SERVER_AUTH_ENABLED)
  "RevocationListRefreshPeriod": 60,
  "AccelByte": {
    "BaseUrl": "https://test.accelbyte.io",     // Base URL (env var: AB_BASE_URL)
    "ClientId": "xxxxxxxxxx",                   // Client ID (env var: AB_CLIENT_ID)    
    "ClientSecret": "xxxxxxxxxx",               // Client Secret (env var: AB_CLIENT_SECRET)
    "AppName": "LOOTBOXGRPCSERVICE",
    "TraceIdVersion": "1",
    "Namespace": "xxxxxxxxxx",                  // Namespace ID (env var: AB_NAMESPACE)
    "EnableTraceId": true,
    "EnableUserAgentInfo": true,
    "ResourceName": "SESSIONDSMGRPCSERVICE"
  }
}

⚠️ Environment variable values will override related configuration values in this file.

3. Access to AccelByte Gaming Services environment. a. Base URL: https://prod.gamingservices.accelbyte.io/admin

Building

To build this app, use the following command.

make build

The build output will be available in .output directory.

Running

To (build and) run this app in a container, use the following command.

docker compose up --build

Testing

Test in Local Development Environment

The custom functions in this app can be tested locally using postman.

1. Run this app by using the command below.

   docker compose up --build

2. Open postman, create a new gRPC request, and enter localhost:6565 as server URL.

3. In postman, continue by selecting CreateGameSession grpc call method and click Invoke button, this will start stream connection to the gRPC server.

4. Still in postman, continue sending parameters first to specify number of players in a match by copying sample json below and click Send.

   {
    "client_version": "test",
    "deployment": "test-deployment",
    "game_mode": "test-game",
    "maximum_player": "10",
    "namespace": "testing",
    "requested_region": [
        "us-west-1",
        "us-west-2"
    ],
    "session_data": "testing",
    "session_id": "uuidv4"
   }

Test with AccelByte Gaming Services

To test the app, which runs locally with AGS, the gRPC server needs to be connected to the internet. To do this without requiring public IP, you can use local tunnel service.

1. Run this app by using command below.

   docker compose up --build

2. Expose gRPC server TCP port 6565 in local development environment to the internet. Simplest way to do this is by using local tunnel service provider.

   • Sign in to ngrok and get your authtoken from the ngrok dashboard and set it up in your local environment. And, to expose gRPC server use following command:

     ngrok tcp 6565

   • Or alternatively, you can use pinggy and use only ssh command line to setup simple tunnel. Then to expose gRPC server use following command:

     ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -R0:127.0.0.1:6565 tcp@a.pinggy.io

   Please take note of the tunnel forwarding URL, e.g., http://0.tcp.ap.ngrok.io:xxxxx or tcp://xxxxx-xxx-xxx-xxx-xxx.a.free.pinggy.link:xxxxx.

   ❗ You may also use other local tunnel service and different method to expose the gRPC server port (TCP) to the internet.

3. In admin portal go to -> Multiplayer > Matchmaking > Session Configuration. Click on the Add Session Template button. Select the Server configuration to be a DS - Custom. Then, select the Custom URL option and provide the tunnel forwarding URL from step 2.

4. create gamesession or do matchmaking

5. in Sessions and Parties - > check in session detail base on session id -> if ds status available check your server in GCPVM or gamelift

Deploying

After completing testing, the next step is to deploy your app to AccelByte Gaming Services.

1. Create an Extend Override app

   If you do not already have one, create a new Extend Override App.

   On the App Detail page, take note of the following values.

   • Namespace
   • App Name

   Under the Environment Configuration section, set the required secrets and/or variables.

   • Secrets
     • AB_CLIENT_ID
     • AB_CLIENT_SECRET
     • AWS_ACCESS_KEY_ID (for GameLift only)
     • AWS_SECRET_ACCESS_KEY (for GameLift only)
   • Variables
     • DS_PROVIDER
     • AWS_REGION (for GameLift only)
     • GAMELIFT_REGION (for GameLift only)
     • GCP_SERVICE_ACCOUNT_FILE (for GCP only)
     • GCP_PROJECT_ID (for GCP only)
     • GCP_NETWORK (for GCP only)
     • GCP_MACHINE_TYPE (for GCP only)
     • GCP_REPOSITORY (for GCP only)
     • GCP_RETRY (for GCP only)
     • GCP_WAIT_GET_IP (for GCP only)
     • GCP_IMAGE_OPEN_PORT (for GCP only)

2. Build and Push the Container Image

   Use extend-helper-cli to build and upload the container image.

   extend-helper-cli image-upload --login --namespace <namespace> --app <app-name> --image-tag v0.0.1
   

   ⚠️ Run this command from your project directory. If you are in a different directory, add the --work-dir <project-dir> option to specify the correct path.

3. Deploy the Image

   On the App Detail page:

   • Click Image Version History
   • Select the image you just pushed
   • Click Deploy Image

Next Step

Proceed by modifying this Extend Override app template to implement your own custom logic. For more details, see here.