Use Extend Codegen CLI to generate Unity SDK Plugin for Extend Service Extension
Overview
This article provides a step-by-step guide on how to generate a custom service plugin for the AccelByte Unity SDK using the Extend Codegen CLI template pack.
A custom service plugin allows developers to leverage the AccelByte Unity SDK to interact with custom service APIs, such as those created with the Extend Service Extension.
The Extend Codegen CLI template pack consists of a Makefile and some Jinja template files. To generate the necessary code, simply invoke a single make
command. This command triggers the Extend Codegen CLI to process the Jinja template files alongside an OpenAPI 2.0 JSON file, which outlines the custom service APIs, to generate the corresponding code.
Prerequisites
Windows 11 WSL2 or Linux Ubuntu 22.04 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
...
Extend Codegen CLI template pack zip for AccelByte Unity SDK.
A valid OpenAPI 2.0 JSON file for your custom service.
tipIn an Extend Service Extension project, you can generate an OpenAPI 2.0 JSON file without running or deploying the service: First, ensure that the
base_path
property in theservice.proto
file matches the actual base path when the service is deployed and update it if needed. Then, runmake proto
in the project folder, and the file will be saved atgateway/apidocs/service.swagger.json
.
Generate Unity SDK Plugin for Extend Service Extension
Place the OpenAPI 2.0 JSON file for your custom service in the
my-unity-project/spec
folder. In this example, the file is namedguild.json
. Next, copy theguild.json
file into the following three folders:Client
,GameServer
, andModels
./path/to/my-unity-project/
|__ Assets/
|__ Library/
|__ Packages/
|__ ProjectSettings/
|__ spec/
|__ Client/
| |__ guild.json <
|__ GameServer/
| |__ guild.json <
|__ Models/
| |__ guild.json <
|__ guild.jsoninfoThe Extend Codegen CLI template pack uses the OpenAPI 2.0 JSON file name as an identifier for your service: You can rename the file according to your preferences, but we recommend using all lowercase alphabets (a-z) to avoid issues generating code.
cautionWhen working with multiple OpenAPI 2.0 JSON files, identical
basePath
values across files may cause issues in the generated code: We recommend ensuring that each OpenAPI 2.0 JSON file has a uniquebasePath
value that matches the actual base path when the service is deployed.Unzip the downloaded Extend Codegen CLI template pack, navigate to the extracted folder, and run the
make
command to generate the code.unzip accelbyte-unity-sdk-template-pack.zip
cd accelbyte-unity-sdk-template-pack/
make all \
CODEGEN_IMAGE_VERSION=x.x.x-alpha \
PROJECT_PATH=/path/to/my-unreal-project \
SPEC_PATH=/path/to/my-unity-project/spec \
PACKAGE_TYPE=plugin \
ADMIN_API_PATH=/admin/info- The
CODEGEN_IMAGE_VERSION
can be found here. For new projects, it is recommended to use the latest available version. - The
PROJECT_PATH
andSPEC_PATH
come from step 1. - The
PACKAGE_TYPE
has two options:- module: Generates as a module within the
AccelByteUe4Sdk
plugin. - plugin: Generates as a standalone plugin named
AccelByteUe4SdkCustomization
.
- module: Generates as a module within the
- If
ADMIN_API_PATH
is specified, the ServerAPI will include any endpoints with the specified path, while the ClientAPI will include all other endpoints. IfADMIN_API_PATH
is not specified, both ServerAPI and ClientAPI will include all available endpoints. - Make sure to remove any leftover files when modifying or replacing the OpenAPI 2.0 JSON file as they might cause compilation errors to show up.
- The
Add
com.accelbyte.sdk.custom
as a dependency inPackages/manifest.json
.{
"dependencies": {
"com.accelbyte.unitysdk": "file:../com.AccelByte.SDK",
...
"com.accelbyte.unitysdk.custom": "file:../com.AccelByte.SDK.Custom"
}
}
Integrate Extend Service Extension API into your Unity project
Include API from the
AccelByte SDK
plugin.using AccelByte.Api;
using AccelByte.Core;
using AccelByte.Models;Call the API function.
var apiClient = AccelByteSDK.GetClientRegistry().GetApi();
// apiClient.[GerServiceName].SomeFunction(...);noteIn case you need to override the
ServerUrl
of your custom service and/or thebasePath
(e.g.,/guild
), refer to the guide for Enabling environment switching for Unity.