Get started with lootbox roll customization
The Extend Override and Events handler is currently available for Closed Beta partners only. Please submit a ticket if you're interested to apply as a Closed Beta partner.
Overview
AccelByte Gaming Services (AGS) has the capability to provide custom logic for different requirements when players open loot boxes. In this guide, we will provide a simple custom loot box roll function for AGS.
Prerequisites
- Go
- Python
- C#
Windows 10 WSL2 or Linux Ubuntu 20.04 with the following tools installed:
- Bash
- Make
- Docker v23.x
- docker-compose v2
- Go v1.19
- ngrok
Access to the AccelByte Gaming Services demo environment.
Base URL:
https://demo.accelbyte.io
.Create a game namespace if you don't have one yet. Keep the
Namespace ID
.Create an OAuth Client with
confidential
client type. Keep theClient ID
andClient Secret
.ADMIN:NAMESPACE:{namespace}:CATALOG:CONFIG - READ, UPDATE, DELETE
The extend-helper-cli downloaded, installed, and set up. Download Here
Windows 10 WSL2 or Linux Ubuntu 20.04 with the following tools installed:
- Bash
- Make
- Docker v23.x
- docker-compose v2
- Python 3.9
- ngrok
Access to the
AccelByte Gaming Services
demo environment.Base URL:
https://demo.accelbyte.io
.Create a game namespace if you don't have one yet. Keep the
Namespace ID
.Create an OAuth Client with
confidential
client type. Keep theClient ID
andClient Secret
.ADMIN:NAMESPACE:{namespace}:CATALOG:CONFIG - READ, UPDATE, DELETE
The extend-helper-cli downloaded, installed, and set up. Download Here
Windows 10 WSL2 or Linux Ubuntu 20.04 with the following tools installed.
- Bash
- Make
- Docker v23.x
- docker-compose v2
- .NET SDK 6.0
- ngrok
Access to
AccelByte Gaming Services
demo environment.Base URL: https://demo.accelbyte.io.
Create a Game Namespace if you don't have one yet. Keep the
Namespace ID
.Create an OAuth Client with
confidential
client type. Keep theClient ID
andClient Secret
.ADMIN:NAMESPACE:{namespace}:CATALOG:CONFIG - READ, UPDATE, DELETE
The extend-helper-cli downloaded, installed, and set up. Download Here
Download the sample app
- Go
- Python
- C#
Clone the loot box roll function gRPC plugin sample apps. loot box roll - sample app
git clone https://github.com/AccelByte/lootbox-roll-function-grpc-plugin-server-go.git
Follow the Setup
, Building
, and Running
sections of the repository README.md
. Alternatively, you can use the go
command shown below to run the server. Ensure that the server is running locally before moving onto the next section.
From sample app root directory (go
command):
go run main.go
Clone the loot box roll function gRPC plugin sample apps. loot box roll - sample app
git clone https://github.com/AccelByte/lootbox-roll-function-grpc-plugin-server-python.git
Follow the Setup
, Building
, and Running
sections of the repository README.md
. Alternatively, you can use the python
command shown below to run the server. Ensure that the server is running locally before moving onto the next section.
From sample app root directory (python
command):
PYTHONPATH=src python -m src.app
Clone the loot box roll function gRPC plugin sample apps. loot box roll - sample app
git clone https://github.com/AccelByte/lootbox-roll-function-grpc-plugin-server-csharp.git
Follow the Setup
, Building
, and Running
sections of the repository README.md
. Alternatively, you can use the dotnet
command shown below to run the server. Ensure that the server is running locally before moving onto the next section.
From sample app root directory:
cd src/AccelByte.PluginArch.LootBox.Demo.Server
dotnet run
Start ngrok
and expose the port
specified within the sample app. The following command assumes you have not changed the port in the sample app:
ngrok tcp localhost:6565
Test your local loot box roll sample app
Next, we will test the sample app locally by utilizing ngrok
to expose localhost to the internet and use the address for loot box gRPC url configuration. Lastly, we'll use the demo/cli
inside the sample app to test against the real environment.
Register the gRPC plugin
Copy the forwarding
address from ngrok
. An example of this will look like:
<number>.tcp.ngrok.io:<port>
Go to the AGS Admin Portal and use the namespace in which you wish to create your gRPC Plugin. Hover over left sidebar menu option E-Commerce and click Custom Configuration. Click the Loot Box Roll side menu. Click Add Configuration if you haven't added any.
Select the option Locally hosted (for testing purpose) and put the ngrok address from above. Then, click Create.
Test using gRPCurl
Testing with gRPCurl is optional, but it will ensure your proxy is working correctly.
Download and install grpcurl and run the following command that will print out the list of gRPC services served by the forwarded local sample app:
Use your ngrok tcp forwarding address below:
grpcurl -plaintext <number>.tcp.ngrok.io:<port> list
Sample output:
accelbyte.platform.entitlement.lootbox.v1.lootbox
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection
Test using demo CLI app
Demo CLI will basically create an e-commerce store, category, loot box items, and will also consume the loot box programmatically to verify the flow.
- Go
- Python
- C#
Demo CLI can be found inside demo/cli in the sample app. Please follow the readme to get more details. Alternatively, you can use cd
to navigate to demo/cli
and follow the commands below.
Demo CLI can be found inside demo/cli in the sample app. Please follow the readme to get more details. Alternatively, you can use cd
to navigate to demo/cli
and follow the commands below.
Demo CLI can be found inside src/AccelByte.PluginArch.LootBox.Demo.Client in the sample app. Please follow the readme to get more details. Alternatively, you can use cd
to navigate to src/AccelByte.PluginArch.LootBox.Demo.Client
and follow the commands below.
Create a .env
file containing your AccelByte account and IAM client inside the demo/cli
directory in the sample app:
AB_BASE_URL='https://demo.accelbyte.io'
AB_CLIENT_ID='<AccelByte IAM Client ID>'
AB_CLIENT_SECRET='<AccelByte IAM Client Secret>'
AB_NAMESPACE='namespace'
AB_USERNAME='<AccelByte account username>'
AB_PASSWORD='<AccelByte account password>'
Finally, run the demo
make run ENV_FILE_PATH=.env
Create the Extend app
Next, we're going to test the sample app and deploy it on the AccelByte hosted environment called Extend App.
To create the Extend app, go to the AGS Admin Portal and use the namespace in which you wish to create your gRPC plugin. On the left pane, hover over Extend and click Overridable Features
. Then, click Create New to create a new Rxtend app.
Type in the App Name and the Description (optional) and click Create.
You will be redirected back to Overridable Features app list page with the newly created app with the Pending status.
Wait until the status says Completed and click the app name in the list to see the details page.
Please take note of the Namespace, App Name, and the App Repository URL since we're going to use it in the next section.
Build and push the Extend app image
The extend-helper-cli
is required to get the temporary docker credentials for uploading your docker image.
Use the Namespace and App Name used to create your extend app for the following extend-helper-cli
command.
extend-helper-cli dockerlogin --namespace <game namespace> --app <app name> -p | docker login -u AWS --password-stdin https://342674635073.dkr.ecr.us-west-2.amazonaws.com
Create an OAuth Client with confidential
client type with the following permission. Keep the Client ID
and Client Secret
.
ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS
[READ]
If you use extend-helper-cli v0.0.3 or lower, create a user if you don't have any with the following permission. Keep the Username and Password.
ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS
[READ]
Go to the extend-helper-cli README for more details.
To directly build and push the sample app docker image, you can use the provided make script. Inside the sample app directory, run this:
make imagex_push IMAGE_TAG=v0.0.1 REPO_URL=<app-repository-url>
Note that REPO_URL can be copied from the app detail page App Repository URL
.
Deploy the Extend app
Back in the Admin Portal, inside the Extend App Details page, click Deploy Latest Image and wait until the deployment is successful.
Test the Extend app
Register the gRPC plugin with the Extend app
Go back to the Admin Portal and update the Loot Box Roll custom configuration. Click the Overridden by
section to edit the existing configuration.
Select the AccelByte hosted option and choose one of the Extend apps. Click Save to finish.
Test using the demo CLI app
Reuse the command from the previous steps to test the Extend app.
make run ENV_FILE_PATH=.env
A note on Extend App behavior
In the deployment setup, there's a timeout mechanism for the gRPC Extend app managed by Envoy. This timeout occurs when there's no incoming/outgoing data or request, allowing the system to free up resources. By default, the timeout duration is 300s for streamIdleTimeout
and 30s for routeTimeout
.